15-代码规范与代码审查
代码规范与代码审查
从个人习惯到团队协作：建立可落地的代码规范体系与高效的代码审查流程
学习目标
读完本文，你将学会：
- 制定适合团队的代码规范（命名、注释、文件组织）
- 掌握代码审查的最佳实践和检查清单
- 使用 Git Hooks 自动化规范检查
- 理解 Commit Message 规范与版本管理
一、代码规范体系
1.1 命名规范
// ✅ 清晰、一致的命名// 常量: SCREAMING_SNAKE_CASEconstMAX_RETRY_COUNT=3;constAPI_BASE_URL='https://api.example.com';// 变量/函数: camelCaseletuserCount=0;functionfetchUserData(userId){}// 类/构造函数: PascalCaseclassUserManager{}classHttpRequestErrorextendsError{}// 私有属性: 下划线前缀 或 #privateFieldclassBankAccount{#balance=0;// 真正私有（推荐）_internalCache={};// 约定私有}// 布尔值: 使用 is/has/should/can 前缀constisLoading=true;consthasPermission=false;constshouldRetry=true;// 文件命名// components/UserProfile.jsx// utils/dateHelpers.js// constants/apiEndpoints.js1.2 注释规范
/** * 计算订单总金额（含税费和运费） * @param {Object} order - 订单对象 * @param {number} order.subtotal - 小计金额 * @param {number} order.taxRate - 税率（如 0.08） * @param {number} order.shipping - 运费 * @returns {number} 总金额（保留两位小数） * @throws {Error} 当 subtotal 为负数时抛出 * @example * calculateTotal({ subtotal: 100, taxRate: 0.08, shipping: 10 }) * // => 118.00 */functioncalculateTotal(order){if(order.subtotal<0){thrownewError('subtotal cannot be negative');}consttax=order.subtotal*order.taxRate;returnNumber((order.subtotal+tax+order.shipping).toFixed(2));}// 行内注释：解释"为什么"，而非"做什么"// ❌ 错误：重复代码显而易见的含义letcount=0;// 初始化计数器为 0// ✅ 正确：解释业务原因letcount=0;// 从 0 开始，API 要求分页参数从 0 起算1.3 文件组织规范
src/ ├── assets/ # 静态资源（图片、字体） │ ├── images/ │ └── fonts/ ├── components/ # 通用组件 │ ├── Button/ │ │ ├── index.jsx │ │ ├── Button.test.jsx │ │ └── Button.module.css │ └── Input/ ├── pages/ # 页面级组件 │ ├── Home/ │ └── About/ ├── hooks/ # 自定义 Hooks ├── utils/ # 工具函数 │ ├── date.js │ ├── validate.js │ └── request.js ├── constants/ # 常量 │ ├── api.js │ └── config.js ├── services/ # API 服务层 └── styles/ # 全局样式 ├── variables.css └── global.css二、代码审查（Code Review）
2.1 审查清单
## 代码审查检查清单 ### 功能正确性 - [ ] 代码是否实现了需求？ - [ ] 边界条件是否处理？ - [ ] 错误处理是否完善？ ### 代码质量 - [ ] 命名是否清晰、一致？ - [ ] 函数是否过长（>50 行需拆分）？ - [ ] 是否避免了重复代码？ - [ ] 是否有不必要的复杂度？ ### 安全性 - [ ] 是否有 SQL/XSS 注入风险？ - [ ] 敏感数据是否安全处理？ - [ ] 权限检查是否到位？ ### 性能 - [ ] 是否有明显的性能问题？ - [ ] 循环中是否有不必要的操作？ - [ ] 大数据量处理是否合理？ ### 测试 - [ ] 是否有对应的单元测试？ - [ ] 测试是否覆盖主要路径？ - [ ] 测试用例名称是否清晰？2.2 审查原则
1. 对事不对人 ❌ "你这里写错了" ✅ "这个变量名可能会让人误解，建议改为..." 2. 解释为什么 ❌ "不要这样写" ✅ "这里如果用户传入 null 会抛异常，建议添加默认值" 3. 区分严重级别 🔴 Blocker: 必须修复（安全问题、功能错误） 🟡 Warning: 建议修复（代码异味、性能问题） 🟢 Nitpick: 可选修复（格式、命名偏好） 4. 及时响应 - 提交者应在 24h 内响应评论 - 审查者应在收到修改后尽快再次审查三、Git 工作流与提交规范
3.1 Commit Message 规范（Conventional Commits）
<type>(<scope>): <subject> <body> <footer>类型说明：
| 类型 | 含义 | 示例 |
|---|---|---|
| feat | 新功能 | feat(user): 添加用户登录功能 |
| fix | 修复 bug | fix(api): 修复空指针异常 |
| docs | 文档更新 | docs(readme): 更新安装说明 |
| style | 代码格式 | style: 修复缩进 |
| refactor | 重构 | refactor(utils): 提取公共函数 |
| test | 测试相关 | test(user): 添加登录单元测试 |
| chore | 构建/工具 | chore(deps): 升级 lodash |
# 示例feat(auth): 支持 OAuth2.0 登录 - 集成 Google 和 GitHub 登录 - 添加 token 刷新机制 - 更新登录页面 UI Closes#1233.2 Git Hooks 自动化
# 安装 husky 和 lint-stagednpminstall--save-dev husky lint-staged# 初始化 huskynpx husky init// package.json{"lint-staged":{"*.{js,jsx,ts,tsx}":["eslint --fix","prettier --write"],"*.{css,scss,json,md}":["prettier --write"]}}# .husky/pre-commitnpx lint-staged# .husky/commit-msgnpx--no-- commitlint--edit${1}// commitlint.config.jsmodule.exports={extends:['@commitlint/config-conventional'],rules:{'type-enum':[2,'always',['feat','fix','docs','style','refactor','test','chore']],'subject-full-stop':[0,'never'],'subject-case':[0,'never']}};四、代码度量与质量控制
4.1 复杂度指标
// 圈复杂度示例functiongetGrade(score){// 圈复杂度: 5if(score>=90)return'A';if(score>=80)return'B';if(score>=70)return'C';if(score>=60)return'D';return'F';}// 使用查找表降低复杂度（圈复杂度: 1）constGRADE_MAP=[{min:90,grade:'A'},{min:80,grade:'B'},{min:70,grade:'C'},{min:60,grade:'D'}];functiongetGrade(score){constentry=GRADE_MAP.find(g=>score>=g.min);returnentry?entry.grade:'F';}4.2 SonarQube 质量门禁
# sonar-project.propertiessonar.projectKey=my-project sonar.sources=src sonar.tests=src/__tests__ sonar.javascript.lcov.reportPaths=coverage/lcov.info# 质量门禁sonar.qualitygate.wait=true二、常见误区与注意点
| 误区 | 正确做法 |
|---|---|
| 代码审查是找茬 | 审查是团队协作，共同提升代码质量 |
| 规范越多越好 | 规则要可执行、可遵守，适度即可 |
| 一次审查提所有问题 | 区分优先级，Blocker 必须修，Nitpick 可协商 |
| Commit Message 随便写 | 规范的提交信息便于生成 CHANGELOG 和回滚 |
| 只在提交前检查 | 配置 IDE 实时提示，问题尽早发现 |
三、动手练习
练习 1：审查一段问题代码
给出一组包含命名不规范、缺少错误处理、重复代码的示例，按检查清单逐项审查。
练习 2：配置完整的前端工程规范
配置 ESLint + Prettier + Husky + Commitlint 的完整工作流。
四、AI 辅助学习
4.1 本节知识点的 AI 提问模板
- “如何制定适合小团队的代码规范？”
- “代码审查时如何给出有建设性的反馈？”
- “Commit Message 规范的完整规则是什么？”
4.2 警惕 AI 的常见错误
- AI 可能推荐过于严格的规则集，需根据团队规模调整
- AI 可能混淆不同的 Git 工作流（Git Flow vs GitHub Flow）
五、配套代码
本文示例代码位于：CODE-ADVANCED/15-代码规范与代码审查/
| 文件名 | 说明 |
|---|---|
code-review-checklist.md | 代码审查检查清单模板 |
commitlint-demo.js | Commit Message 规范验证示例 |
husky-setup.sh | Husky + lint-staged 配置脚本 |
六、本章小结
- 代码规范包括命名、注释、文件组织三个层面
- 代码审查应以协作态度进行，区分问题优先级
- Conventional Commits 规范便于自动化版本管理和 CHANGELOG 生成
- Git Hooks 实现提交前自动化检查，防止问题代码入库
如果本文对你有帮助，欢迎点赞、收藏、关注专栏。有任何问题可以在评论区交流！