代码审查

何时使用

• 合并 MR/PR 前,用户说"帮我 review 一下";
• 用户说"这段代码有没有问题""帮我检查下这段改动";
• 写完一大段代码,自查"有没有问题";
• 审查 AI 生成的大量代码(重点查隐蔽问题);
• 代码行为异常,需要定位可疑点。

使用步骤

第 1 步:理解改动意图

先搞清楚:

1. 这次改动要解决什么问题;
2. 涉及哪些文件、哪些函数;
3. 有没有对应的测试或需求文档。

第 2 步:按四个维度逐项审查

正确性

• 边界条件(空、零、负数、超长、并发);
• 异常处理(是否吞异常、是否暴露内部信息);
• 状态一致性(失败后是否留下脏状态);
• 数值与类型(浮点比较、隐式类型转换、时区)。

安全性

• 输入校验(注入、路径穿越、XSS、SSRF);
• 敏感信息(密钥、token 是否硬编码或打进日志);
• 权限检查是否在服务端而非前端;
• 依赖来源是否可信。

性能

• 循环内是否有重复计算或 N+1 查询;
• 是否缺少索引、缓存;
• 大数据量场景的复杂度是否可接受。

可维护性

• 命名是否表意;
• 是否复制粘贴代码、是否有死代码;
• 错误信息是否可理解;
• 是否符合项目既有风格。

第 3 步:重点审查 AI 生成代码

AI 生成代码的常见问题,需额外检查:

• 未验证假设:用了不存在的 API、错误的环境变量名;
• 死代码与重复:复制了多段相似逻辑;
• 幻觉依赖:import 了未声明的库;
• 吞掉错误:except 后无日志无处理;
• 不安全默认值:宽松的正则、过大的权限、硬编码密钥。

第 4 步:输出审查报告

完整的四维检查清单和级别定义见 references/CHECKLIST.md。

完整的四维检查清单和级别定义见 references/CHECKLIST.md。

# 代码审查报告

## 结论
建议:通过 / 修改后通过 / 不通过

## 问题清单
| 严重级别 | 位置 | 问题 | 建议 |
|----------|------|------|------|
| P0 阻断 | src/auth.py:42 | 密码以明文存库 | 使用 bcrypt 哈希 |
| P1 严重 | api/user.py:88 | 未校验用户输入 | 增加白名单校验 |
| P2 一般 | utils.py:15 | 异常被吞掉 | 记录日志并返回友好错误 |
| P3 建议 | main.py:3 | 命名不表意 | 改名 process_user_input |

严重级别定义:

• P0 阻断:会导致事故或安全问题,必须修复;
• P1 严重:明显缺陷,建议合并前修复;
• P2 一般:可修复但不阻塞;
• P3 建议:风格与改进建议。

输入与输出

• 输入:代码改动(diff、文件、PR)或待审查的代码;
• 输出:带严重级别的结构化审查意见。

辅助脚本

scripts/review_helper.py 能扫描改动文件,标记硬编码密钥、裸 except、调试输出等常见可疑点:

python scripts/review_helper.py --base main --head HEAD

脚本只做标记,结论需要人确认。

注意事项

• 对代码不对人:评论用"这里可能…"而不是"你写错了";
• 先看大局再看细节:先确认设计方向对,再抠命名;
• 每个意见给出位置 + 问题 + 建议,不要只说"这有问题";
• 不确定的判断标注"需确认",不要臆断;
• 审查范围只覆盖改动相关代码,不扩展到无关模块。

不适用场景

• 用户只是问"这段代码干嘛的"(那是解释,不是审查);
• 没有代码上下文时要求给出绝对结论(应先要求提供代码);
• 已经冻结且无法修改的历史代码(只做了解即可)。

验证方式

1. 触发:"帮我 review""检查这段代码";
2. 检查:报告是否覆盖正确性/安全/性能/可维护性,并含严重级别;
3. 抽查:任选一条 P0/P1 意见,人工确认问题真实存在。