Code Review 与代码规范

一、为什么要有 Code Review（CR）

• 质量：多一双眼睛，少一堆 bug。
• 传承：新人通过 review 学最佳实践。
• 统一：全团队风格一致，好阅读好维护。

正确心态：CR 是"帮我看代码"，不是"打脸"。

二、一个 PR 长什么样（规范）

标题：<type>: <一句话描述>
示例：feat: 商品搜索支持分类筛选
     fix: 修复高并发下库存超卖

描述：
- 背景：为什么做
- 改动：改了哪些文件、动了什么逻辑
- 测试：自测情况 / 影响范围
- 截图：UI 改动附截图

git checkout -b feature/product-filter    # 小而专的分支
# ... 开发 + 自测 ...
git add . && git commit -m "feat: 商品支持分类筛选"
git push origin feature/product-filter
# GitHub/GitLab 上发起 Pull Request

PR 越小越好：一个 PR 一两个功能点，几百行以内，review 的人才愿意认真看。

三、评审意见该怎么写

给出"改什么 + 为什么"，对新人尤其有效：

// ❌ 好难读的写法
if (user != null && user.getStatus() != null && user.getStatus().equals(1)) {}

// ✅ 意见：抽成方法，语义清晰
if (userService.isActive(user)) {}

四、代码规范清单（照着做）

命名与结构

场景	规范	反面例子
类/文件	大驼峰 ProductService	product_service
方法/变量	小驼峰 getProductList	get_productList
常量	全大写 MAX_PAGE_SIZE	maxPageSize
布尔变量	isLogin hasStock	flag、statu
方法职责	一个方法一件事	又查库又算钱又发消息

后端规范

• Controller 不放业务逻辑（现在的做法已经满足）。
• 魔法值转常量/枚举："PENDING" → OrderStatus.PENDING。
• 判空用工具：StringUtils.hasText(user.getPhone())。
• 返回结构统一 Result，不裸返回。

前端规范

• TypeScript 引入 types，不写 any（必要处注释原因）。
• 组件拆分：一个页面超 200 行就抽子组件。
• 依赖数组写对：useEffect 缺依赖或冗余依赖。
• 不用魔法字符串重复拼接 URL，收进 api/。

兜底规则

• 提交前跑 lint + 测试（接入 CI 后自动拦）。
• 日志打对级别：info 业务、warn 异常、error 故障。
• 密钥绝不提交（.gitignore + 环境变量）。

五、Review 里最常见的 10 个问题

1. 缺少空值判断（NPE 隐患）
2. 魔法值写死在代码里
3. 事务边界错 / 该加没加 @Transactional
4. 未处理异常被吞（catch 空异常）
5. SQL 明显没走索引（LIKE %xx%）
6. 前端请求不统一走封装，错误无提示
7. 权限/归属校验缺失
8. 命名不达意（data1、tmp）
9. 重复代码未抽公共方法
10. 注释过期或误导（代码改了注释没改）

六、新人如何应对 CR

1. 虚心读取每条意见 → 问清楚"为什么"
2. 快速回应：改或不改都说清理由
3. 批量改完重新 push，回复 @ 一起的人
4. 把同类问题记进自己的 checklist

被批最狠的那次 review，进步最快。把它当免费的学习机会。

七、代码规范落地工具

# 后端：Maven Spotless / Checkstyle
# 前端：ESLint + Prettier（脚手架已配）
# 全站：Husky 提交前自动跑 lint + 测试

企业里的规范大多是"约定 + 工具强制"：约定靠团队，强制靠 CI。