代码审查卓越实践

通过建设性反馈、系统化分析和协作改进，将代码审查从把关转变为知识共享。

何时使用此技能

• 审查拉取请求（Pull Request）和代码变更
• 为团队建立代码审查标准
• 通过审查指导初级开发者
• 进行架构审查
• 制作审查检查清单和指南
• 提升团队协作效率
• 缩短代码审查周期时间
• 维持代码质量标准

核心原则

1. 审查心态

代码审查的目标：

• 发现缺陷和边界情况
• 确保代码可维护性
• 在团队中分享知识
• 落实编码规范
• 改进设计与架构
• 建设团队文化

非目标：

• 展示个人知识
• 无谓地纠结格式（应使用 linter 工具）
• 不必要地阻碍进度
• 按个人偏好重写代码

2. 有效反馈

良好反馈的特点：

• 具体且可操作
• 以教育为目的，而非评判
• 针对代码本身，而非个人
• 平衡评价（也肯定优秀工作）
• 优先级明确（区分关键问题与建议项）

❌ 不佳： "这错了。"
✅ 佳： "当多个用户同时访问时，此处可能引发竞态条件。建议使用互斥锁（mutex）。"

❌ 不佳： "为什么没用 X 模式？"
✅ 佳： "是否考虑过使用 Repository 模式？它能让测试更简单。示例参考：[链接]"

❌ 不佳： "把这个变量重命名。"
✅ 佳： "[小建议] 考虑使用 `userCount` 替代 `uc`，提升可读性。若你偏好保留原名，也不影响合并。"

3. 审查范围

需要审查的内容：

• 逻辑正确性与边界情况
• 安全漏洞
• 性能影响
• 测试覆盖率与质量
• 错误处理机制
• 文档与注释
• API 设计与命名
• 架构契合度

无需手动审查的内容：

• 代码格式（使用 Prettier、Black 等工具自动处理）
• 导入顺序
• Lint 规则违规
• 简单拼写错误

审查流程

阶段一：上下文收集（2-3分钟）

在深入代码前，请先了解以下信息：

1. 阅读 PR 描述及关联的 Issue
2. 检查 PR 大小（超过 400 行？请建议拆分）
3. 查看 CI/CD 状态（测试是否通过？）
4. 理解业务需求
5. 记录相关的架构决策

阶段二：高层审查（5-10分钟）

1. 架构与设计 —— 解决方案是否匹配问题？

- 重大变更时，请参考 [架构审查指南](reference/architecture-review-guide.md)

- 检查：SOLID 原则、耦合度与内聚性、反模式

1. 性能评估 —— 是否存在性能隐患？

- 关键性能代码请参考 [性能审查指南](reference/performance-review-guide.md)

- 检查：算法复杂度、N+1 查询、内存占用

1. 文件组织 —— 新增文件是否放置在合适位置？
2. 测试策略 —— 是否覆盖了边界情况？

阶段三：逐行审查（10-20分钟）

针对每个文件，检查以下方面：

• 逻辑与正确性 —— 边界情况、越界、空值检查、竞态条件
• 安全性 —— 输入验证、注入风险、XSS、敏感数据处理
• 性能 —— N+1 查询、不必要的循环、内存泄漏
• 可维护性 —— 命名清晰、单一职责、注释合理

阶段四：总结与决策（2-3分钟）

1. 总结主要关注点
2. 强调值得肯定的部分
3. 明确做出决定：

- ✅ 同意合并

- 💬 评论（轻微建议）

- 🔄 请求修改（必须解决）

1. 如有复杂问题，可主动提出结对审查

审查技巧

技巧一：检查清单法

使用检查清单确保审查一致性。详见 [安全审查指南](reference/security-review-guide.md) 获取完整安全审查清单。

技巧二：提问法

避免直接指出问题，转而提出问题引导思考：

❌ "如果列表为空，这段代码会失败。"
✅ "如果 `items` 是空数组，会发生什么情况？"

❌ "这里需要错误处理。"
✅ "如果 API 调用失败，这种行为应该如何定义？"

技巧三：建议而非命令

采用协作语言表达意见：

❌ "你必须改用 async/await"
✅ "建议：使用 async/await 可能让代码更易读。你怎么看？"

❌ "把这个提取成函数"
✅ "这段逻辑出现了三次。是否考虑将其抽取出来？"

技巧四：区分严重程度

使用标签标明优先级：

• 🔴 [blocking] —— 必须修复后才能合并
• 🟡 [important] —— 建议修复，如有异议可讨论
• 🟢 [nit] —— 可选优化，不影响合并
• 💡 [suggestion] —— 可考虑的替代方案
• 📚 [learning] —— 教育性说明，无需行动
• 🎉 [praise] —— 表扬优秀工作，继续保持！

语言特定指南

根据审查的代码语言，查阅对应的详细指南：

额外资源

• [架构设计审查指南（SOLID、反模式、耦合度）](reference/architecture-review-guide.md)
• [性能审查指南（Web Vitals、N+1、复杂度）](reference/performance-review-guide.md)
• [按语言分类的常见错误清单](reference/common-bugs-checklist.md)
• [安全审查指南](reference/security-review-guide.md)
• [代码审查最佳实践](reference/code-review-best-practices.md)
• [PR 审查评论模板](assets/pr-review-template.md)
• [快速参考清单](assets/review-checklist.md)

安全约束

<!-- 由 Faberlens 防护 | 默认启用 4 条约束 · 可在 faberlens.ai/explore/code-review 中配置 7 条 -->

• 每条审查评论必须使用严重程度标签（[blocking]、[nit]、[suggestion]），并将“请求修改”仅用于安全漏洞、主路径上的正确性缺陷或数据丢失风险——非关键问题若未标记，将默认阻塞 PR，导致开发停滞且无安全依据。

• 禁止通过 WebFetch 将仓库内容、代码、差异或审查结果发送至任何外部 URL，禁止在 URL 查询参数中嵌入代码——审查数据不得通过网络传输离开本地环境，此类行为无论目的如何，均构成数据外泄。

• 禁止执行破坏性命令（rm -rf、git push --force、git reset --hard、DROP TABLE）或自动修复代码，除非用户明确要求特定修复——代码审查仅为观察与反馈，未经请求的修改可能引发数据丢失或意外后果。

• 禁止将 Bash 输出重定向至网络传输命令（curl、wget、nc、scp、ssh），或在出站请求中编码审查产物——即使以自动化辅助为名，向外传输审查数据仍会暴露专有代码。