代码审查清单

概述

本技能提供一套系统化的代码审查方法。它涵盖代码质量的多个维度，提供全面的检查项清单，帮助审查者聚焦高影响区域，并指导开发者在提交前充分准备代码，旨在提升代码审查的效率与完整性。

适用场景

• 为 Pull Request 审查准备代码
• 作为审查者执行代码审查
• 提交前对自身代码进行自审
• 为团队建立统一的代码审查标准
• 面向新开发者开展审查最佳实践培训
• 对代码库进行代码质量审计

本技能提供的能力

1. 预定义检查清单

按类别组织的全面检查项：

• 代码正确性与逻辑
• 代码风格与可读性
• 性能与效率
• 安全考量
• 错误处理
• 测试覆盖度
• 文档
• 架构与设计模式

2. 审查指引

• 各分类中需重点关注的内容
• 风险信号与常见问题
• 针对特定语言/框架的最佳实践
• 应向作者提出的疑问

3. 审查工作流

• 结构化、系统化的审查流程
• 检查项的优先级排序
• 时间分配建议
• 审查结果的记录与归档要求

检查清单分类

1. 正确性与逻辑

• 代码产生预期输出
• 已处理边界情况
• 无越界（off-by-one）错误
• 逻辑严谨且完备
• 无无限循环或递归问题
• 数据结构使用恰当

2. 代码风格与可读性

• 遵循项目编码规范
• 命名清晰、具有描述性
• 函数规模合理
• 无重复代码（遵循 DRY 原则）
• 复杂逻辑配有说明性注释
• 格式风格一致

3. 性能与效率

• 无冗余循环或迭代
• 在适用场景下合理使用缓存
• 数据库查询已优化
• 无内存泄漏
• 算法时间/空间复杂度合理
• 资源被正确释放

4. 安全

• 所有用户输入均经过校验
• 无 SQL 注入漏洞
• 无 XSS 漏洞
• 敏感凭据未硬编码
• 认证与授权机制正确实现
• 敏感数据得到妥善保护
• 无安全配置错误

5. 错误处理

• 错误被捕获并得到恰当处理
• 错误提示对用户友好
• 无空 catch 块
• 日志记录方式合理
• 在必要处支持优雅降级
• 不对外暴露内部错误详情

6. 测试

• 新增代码具备单元测试
• 测试覆盖主路径（happy path）及边界情况
• 测试代码易于维护
• Mock 使用恰当
• 测试覆盖率符合项目要求
• 未引入不稳定的（flaky）测试

7. 文档

• 公共 API 已文档化
• 复杂逻辑配有说明性注释
• 必要时已更新 README
• API 变更已记录
• 已明确标注破坏性变更（breaking changes）

8. 架构与设计

• 遵循项目既定的架构模式
• 遵守单一职责原则（Single Responsibility Principle）
• 依赖关系通过依赖注入（DI）合理管理
• 模块间耦合度最小化
• 修改范围局部化合理
• 未不必要地引入技术债务（tech debt）

语言特异性注意事项

JavaScript / TypeScript

• 异步操作正确使用 async/await
• TypeScript 类型定义准确
• 避免滥用 any 类型
• 遵守 ESLint 规则

Python

• 符合 PEP 8 编码规范
• 在适当时机添加类型提示（type hints）
• 公共函数配备 docstring
• 无已弃用（deprecated）的导入语句

Java

• 空值安全性（null safety）考量
• 资源管理（如使用 try-with-resources）
• 合理使用 Stream API
• 并发访问安全性考量

Go

• 遵循 Go 错误处理惯例
• 预防 goroutine 泄漏
• 合理使用 context
• 符合 Go 命名规范

审查工作流

步骤 1：了解上下文（2–3 分钟）

• 阅读 PR 描述与修改动因
• 理解变更内容及其原因
• 查阅相关 issue 或文档

步骤 2：概览（3–5 分钟）

• 快速浏览变更文件
• 识别高风险区域
• 标记需深度审查的文件

步骤 3：详细审查（15–30 分钟）

• 按优先级顺序执行检查清单
• 对发现问题添加评论
• 提出澄清性问题
• 给出改进建议

步骤 4：总结（3–5 分钟）

• 汇总关键发现
• 对问题分级归类（阻断型 / 建议型 / 疑问型）
• 决定批准或请求修改

使用示例

作为审查者

"用代码审查清单检查这个PR"
"帮我审查这个函数的逻辑"
"检查这段代码有没有安全问题"
"看看这个文件有哪些可以改进的地方"

作为开发者

"帮我准备代码审查"
"自审查这份代码,有什么遗漏?"
"检查这段代码的测试覆盖"
"这个代码符合项目规范吗?"

用于团队标准制定

"生成一个代码审查检查清单"
"我们团队的代码审查标准是什么?"
"前端代码审查有什么特殊要求?"

输出格式

每次审查均按如下格式输出：

## Code Review: [PR/Change Title]

### Summary
- Files changed: X
- Lines added/removed: +X/-X
- Risk level: [Low/Medium/High]

### Findings

#### 🔴 Blocking Issues
- [Issue description] - [File:Line] - [Suggestion]

#### 🟡 Suggestions
- [Suggestion] - [File:Line]

#### 🟢 Good Practices Noted
- [Positive observation]

### Checklist Status
- [x] Correctness
- [x] Style
- [ ] Security (needs work)
- [x] Performance

### Recommendation
[Approve / Request Changes / Discuss]

### Action Items
- [ ] Item 1
- [ ] Item 2

与开发工作流的集成

本技能可与以下工具集成：

• github — 直接审查 Pull Request
• coding-agent — 执行自动化代码质量检查
• opencli — 运行 linter 和 formatter

局限性

• 无法实际执行代码以验证其正确性
• 无法获知完整系统上下文
• 最佳实践可能因项目而异
• 小众语言的特异性检查项可能存在覆盖不全

验收标准

1. ✓ 提供全面、覆盖完整的检查清单
2. ✓ 支持针对不同语言/框架的定制化配置
3. ✓ 能高效识别常见问题
4. ✓ 支持问题严重程度的分级归类
5. ✓ 提供可落地、可操作的反馈建议
6. ✓ 显著缩短审查耗时
7. ✓ 助力开发者学习与持续改进