code-review-skill

代码审查技能

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

何时使用此技能

• 审查拉取请求和代码变更
• 为团队制定代码审查标准
• 通过审查指导初级开发者
• 开展架构审查
• 创建审查清单和指南
• 改善团队协作
• 缩短代码审查周期
• 维护代码质量标准

核心原则

1. 审查心态

代码审查的目标：

• 发现错误和边界情况
• 确保代码易于维护
• 在团队中分享知识
• 落实编码标准
• 改进设计和架构
• 建设团队文化

非审查目标：

• 炫耀知识
• 纠结格式问题（使用代码检查工具）
• 无故阻碍进度
• 按自己的偏好重写代码

2. 有效反馈

好的反馈应当：

• 具体且可执行
• 有助于学习，而非带有评判
• 针对代码，而非个人
• 有所侧重（也要称赞做得好的地方）
• 按优先级区分（关键问题与锦上添花的建议）

❌ Bad: "This is wrong."
✅ Good: "This could cause a race condition when multiple users
         access simultaneously. Consider using a mutex here."

❌ Bad: "Why didn't you use X pattern?"
✅ Good: "Have you considered the Repository pattern? It would
         make this easier to test. Here's an example: [link]"

❌ Bad: "Rename this variable."
✅ Good: "[nit] Consider `userCount` instead of `uc` for
         clarity. Not blocking if you prefer to keep it."

3. 审查范围

需要审查的内容：

• 逻辑正确性和边界情况
• 安全漏洞
• 对性能的影响
• 测试覆盖率和质量
• 错误处理
• 文档和注释
• API 设计和命名
• 是否符合架构要求

无需手动审查的内容：

• 代码格式（使用 Prettier、Black 等工具）
• 导入项排序
• 代码检查违规项
• 简单的拼写错误

审查流程

阶段 1：收集背景信息（2-3 分钟）

开始查看代码前，先了解以下内容：

1. 阅读 PR 描述和关联的问题
2. 检查 PR 的规模（超过 400 行？请对方拆分）
3. 检查 CI/CD 状态（测试是否通过？）
4. 了解业务需求
5. 记录相关的架构决策

对于较大的差异，可将差异内容通过管道传给 scripts/pr-analyzer.py（git diff main...HEAD | python scripts/pr-analyzer.py），在阅读前评估复杂度，并获取建议的审查方法。

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

1. 架构与设计——解决方案是否符合问题需求？
   • 对于重大变更，请参考架构审查指南
   • 检查：SOLID 原则、耦合与内聚、反模式
2. 性能评估——是否存在性能问题？
   • 对于性能关键代码，请参考性能审查指南
   • 检查：算法复杂度、N+1 查询、内存使用情况
3. 文件组织——新增文件是否放在了合适的位置？
4. 测试策略——是否有测试覆盖边界情况？

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

逐个文件检查：

• 逻辑与正确性——边界情况、差一错误、空值检查、竞态条件
• 安全性——输入验证、注入风险、XSS、敏感数据
• 性能——N+1 查询、不必要的循环、内存泄漏
• 可维护性——名称清晰、职责单一、注释
• 复用——接受新增代码前，先查找是否有现有的实用工具或辅助函数可以替代。检查相邻文件和共享模块中是否存在类似模式。反模式示例包括参数泛滥、抽象泄漏、嵌套条件、字符串类型编码、TOCTOU 和无操作更新，详见通用质量指南。

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

1. 总结主要问题
2. 指出你认可的地方
3. 明确给出决定：
   • ✅ 批准
   • 💬 评论（小建议）
   • 🔄 请求修改（必须处理）
4. 如果问题复杂，可提出结对协作

审查技巧

技巧 1：清单法

使用清单，确保审查方式一致。完整的安全检查清单请参见安全审查指南。

技巧 2：提问法

不要直接指出问题，而是提出问题：

❌ "This will fail if the list is empty."
✅ "What happens if `items` is an empty array?"

❌ "You need error handling here."
✅ "How should this behave if the API call fails?"

技巧 3：提出建议，而非发号施令

使用协作式措辞：

❌ "You must change this to use async/await"
✅ "Suggestion: async/await might make this more readable. What do you think?"

❌ "Extract this into a function"
✅ "This logic appears in 3 places. Would it make sense to extract it?"

技巧 4：区分严重程度

使用标签标明优先级：

• 🔴 [blocking] - 合并前必须修复
• 🟡 [important] - 应当修复，如有异议可讨论
• 🟢 [nit] - 有则更好，不会阻碍合并
• 💡 [suggestion] - 值得考虑的替代方案
• 📚 [learning] - 教学性评论，无需采取行动
• 🎉 [praise] - 做得不错，请继续保持！

严重程度级别： 🔴 / 🟡 / 🟢 是本技能所有指南中使用的三个标准严重程度级别——🔴 会阻止合并，🟡 应当处理，🟢 可选。其余标记（💡 / 📚 / 🎉）均为非阻塞性注释。

按语言分类的指南

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

语言/框架	参考文件	主要主题
React	React 指南	Hooks、useEffect、React 19 Actions、RSC、Suspense、TanStack Query v5
Vue 3	Vue 指南	Composition API、响应性系统、Props/Emits、Watchers、Composables
Angular 17+	Angular 指南	Signals、Standalone、RxJS、Zoneless、模板优化、测试、路由守卫、HttpInterceptor
Rust	Rust 指南	所有权/借用、Unsafe 审查、异步代码、取消安全性、错误处理
TypeScript	TypeScript 指南	类型安全、async/await、不可变性、测试、模块解析、TS 5.x
Python	Python 指南	可变默认参数、异常处理、类属性
Django / DRF	Django 指南	安全审查、N+1 查询、Serializer 反模式、ViewSet、异步视图
FastAPI	FastAPI 指南	Depends、Pydantic v2 验证、异步正确性、会话/N+1、身份验证与授权、测试驱动验证
Java	Java 指南	Java 17/21 新特性、Spring Boot 3、虚拟线程、Stream/Optional
Java 8 / Legacy	Java 8 指南	Java 8、Spring Boot 2、javax.*、Stream/Optional、java.time、CompletableFuture
PHP	PHP 指南	PHP 8.x 类型系统、PDO、安全审查、Composer、PHPUnit/PHPStan
Ruby / Rails	Ruby 指南	Ruby 语义、Rails 8、Active Record、Active Job、安全、测试
C# / .NET	C# 指南	C# 12 特性、异步编程、EF Core 性能、ASP.NET Core、LINQ
Go	Go 指南	错误处理、goroutine/channel、context、接口设计
Kotlin / Android	Kotlin 指南	协程、Flow、Jetpack Compose、空安全、内存泄漏、架构模式
Swift / SwiftUI	Swift 指南	Optionals、Swift Concurrency、Sendable/actors、SwiftUI 属性包装器、值类型与引用类型、API 设计
Dart / Flutter	Dart 指南	Widget 重建、const 构造函数、空安全、隔离区、在 build 中使用异步代码、Riverpod/Bloc、平台通道、键、释放
NestJS	NestJS 指南	依赖注入、分层架构、DTO 验证、Guard/Interceptor、循环依赖
Svelte / SvelteKit	Svelte 指南	Runes、Load 函数、Form Actions、Store 迁移、SSR/CSR 边界
C	C 指南	指针/缓冲区、内存安全、UB、安全编码、可移植性、测试
C++	C++ 指南	RAII、智能指针、C++20/23、constexpr、测试
Zig	Zig 指南	分配器、错误联合、defer/errdefer、comptime、C 互操作
CSS/Less/Sass	CSS 指南	变量规范、!important、性能优化、响应式、兼容性
Qt	Qt 指南	对象模型、信号/槽、Model/View、QML、Qt6 迁移、测试

跨领域指南

适用于所有代码审查的语言无关模式：

主题	参考文件	主要主题
架构审查	架构审查指南	SOLID、反模式、耦合/内聚、依赖方向
性能审查	性能审查指南	Web Vitals、N+1、算法复杂度、内存泄漏、缓存
安全审查	安全审查指南	SQLi、XSS、CSRF、SSRF、IDOR、命令注入、跨语言示例
通用质量	通用质量指南	复用审查、参数泛滥、泄漏的抽象、嵌套条件、字符串化类型代码、TOCTOU、无操作更新、冗余状态
常见错误	常见错误检查清单	特定语言的错误模式、常见陷阱
SQL 注入防护	SQL 注入指南	参数化查询、ORM 安全性、6 种语言、动态标识符、检测
XSS 防护	XSS 防护指南	输出编码、CSP、5 个框架、输入验证与编码、检测
N+1 查询	N+1 查询指南	预加载、批量获取、DataLoader、5 种语言、检测
错误处理	错误处理指南	快速失败、错误层级、7 种语言、反模式、日志记录
异步与并发	并发指南	Goroutine、async/await、actor、结构化并发、7 种语言
审查最佳实践	代码审查最佳实践	沟通、审查者心态、提供反馈、严重性标签

其他资源

• PR 审查模板 - PR 审查评论模板
• 审查检查清单 - 快速参考清单