代码审查清单

采用全面、结构化的方式审查代码。请系统性地逐项检查每个维度，而非随机浏览。

安装

OpenClaw / Moltbot / Clawbot

npx clawhub@latest install code-review

审查维度

安全审查清单

对每一处变更均需检查以下安全漏洞：

• SQL 注入 — 所有数据库查询均使用参数化语句或 ORM；禁止将用户输入直接拼接到 SQL 字符串中
• XSS — 用户提供的内容在渲染前必须进行转义或净化；如使用 dangerouslySetInnerHTML 或其等效机制，须有充分理由且确保安全
• CSRF 防护 — 状态变更类请求必须携带有效的 CSRF Token；Cookie 的 SameSite 属性已正确设置
• 认证（Authentication） — 每个受保护的端点在处理请求前，必须验证用户是否已通过身份认证
• 授权（Authorization） — 对资源的访问必须严格限制在当前请求用户的权限范围内；杜绝 IDOR 类漏洞
• 输入校验 — 所有来自外部的输入（URL 参数、Header、请求体、文件上传等）均需在服务端进行类型、长度、格式及取值范围校验
• 密钥管理（Secrets Management） — 源码中不得硬编码 API Key、密码、Token 或其他凭证；所有密钥应通过环境变量或密钥管理服务（Vault）注入
• 依赖安全性 — 新增依赖必须来自可信源、处于活跃维护状态，且无已知 CVE 漏洞
• 敏感数据处理 — PII（个人身份信息）、Token、密钥等不得记录到日志、不得出现在错误消息中、不得返回至 API 响应体
• 速率限制（Rate Limiting） — 公共接口与认证接口均需配置合理速率限制，防止暴力破解与滥用
• 文件上传安全 — 上传文件须校验类型与大小，存储路径须位于 Web 根目录之外，并以安全的 Content-Type 头提供服务
• HTTP 安全响应头 — 已正确配置 Content-Security-Policy、X-Content-Type-Options、Strict-Transport-Security 等安全头

性能审查清单

• N+1 查询 — 数据库访问模式已优化为批量查询或 JOIN；避免在循环中逐条发起查询
• 非必要重渲染 — 组件仅在其相关状态或属性变更时才触发重渲染；对可测量收益的场景应用 memoization
• 内存泄漏 — 事件监听器、订阅、定时器与周期任务均在组件卸载或资源销毁时被正确清理
• 构建包体积 — 新增依赖支持 Tree-shaking；大型库采用动态加载；禁止仅为单个函数而引入整库
• 懒加载（Lazy Loading） — 计算密集型组件、路由及首屏以下内容均已启用懒加载 / 代码分割
• 缓存策略 — 开销较大的计算结果与 API 响应均已配置合适的缓存机制（如 memoization、HTTP 缓存头、Redis）
• 数据库索引 — 查询中涉及过滤与排序的字段均已建立索引；新增查询已通过 EXPLAIN 进行验证
• 分页机制 — 列表类端点与查询均已启用分页或游标式分页；禁止无限制的 SELECT *
• 异步操作 — 耗时较长的任务已交由后台作业或队列处理，避免阻塞请求线程
• 图片与静态资源优化 — 图片尺寸适配、采用现代格式（WebP/AVIF），并依托 CDN 分发

正确性审查清单

• 边界情况（Edge Cases） — 已处理空数组、空字符串、零值、负数及最大值等场景
• 空值处理（Null/Undefined Handling） — 对可能为空的值访问前均已做显式检查；通过可选链（Optional Chaining）或防护条件（Guard Clause）避免运行时错误
• 差一错误（Off-by-One Errors） — 循环边界、数组切片、分页偏移量及范围计算均已验证
• 竞态条件（Race Conditions） — 对共享状态的并发访问已通过锁、事务或原子操作保障一致性
• 时区处理（Timezone Handling） — 时间戳统一以 UTC 存储；展示层负责时区转换
• Unicode 与编码（Unicode & Encoding） — 字符串操作兼容多字节字符；文本编码明确指定为 UTF-8
• 整数溢出 / 精度问题（Integer Overflow / Precision） — 大数运算或货币计算已选用合适类型（如 BigInt、Decimal）
• 错误传播（Error Propagation） — 异步调用及外部服务抛出的错误已被捕获并妥善处理；Promise 不会被静默吞没
• 状态一致性（State Consistency） — 多步状态变更具备事务性；部分失败后系统仍保持有效状态
• 边界值校验（Boundary Validation） — 已对合法取值范围的边界值（最小值、最大值、恰好等于阈值）进行测试

可维护性审查清单

• 命名清晰性（Naming Clarity） — 变量、函数与类名具有描述性，能直观体现其设计意图
• 单一职责（Single Responsibility） — 每个函数 / 类 / 模块仅承担一项职责；单一关注点的修改不会波及无关代码
• DRY 原则 — 重复逻辑已提取为通用工具；复制粘贴的代码块已合并
• 圈复杂度（Cyclomatic Complexity） — 函数分支逻辑简洁；深度嵌套结构已重构
• 错误处理（Error Handling） — 错误在恰当边界被捕获，附带上下文记录，并以有意义的方式向上暴露
• 废弃代码清理（Dead Code Removal） — 已移除注释掉的代码、未使用的导入、不可达分支及过时的功能开关
• 魔法数字与字符串（Magic Numbers & Strings） — 字面量值已提取为具语义的命名常量
• 风格一致性（Consistent Patterns） — 新增代码严格遵循现有代码库约定
• 函数长度（Function Length） — 函数足够简短，可一目了然；过长函数已拆解
• 依赖方向（Dependency Direction） — 依赖关系指向内层（如 infrastructure → domain）；核心业务逻辑不反向依赖 UI 或框架层

测试审查清单

• 测试覆盖率（Test Coverage） — 新增逻辑路径均有对应测试；关键路径同时覆盖正常流程与异常场景
• 边界情况测试（Edge Case Tests） — 测试覆盖边界值、空输入、null 值及错误条件
• 非脆弱测试（No Flaky Tests） — 测试确定性强；不依赖时间、外部服务或共享可变状态
• 测试独立性（Test Independence） — 每个测试独立构建并销毁自身状态；测试执行顺序不影响结果
• 有意义的断言（Meaningful Assertions） — 断言聚焦于行为与结果，而非实现细节
• 测试可读性（Test Readability） — 测试遵循 Arrange-Act-Assert 模式；测试名称准确描述场景与预期结果
• 模拟规范性（Mocking Discipline） — 仅对外部边界（网络、数据库、文件系统）进行模拟
• 回归测试（Regression Tests） — Bug 修复必须包含复现原问题并验证已解决的测试用例

审查流程

分三轮通读代码，切勿试图一次完成全部审查。

第一轮（2–5 分钟）

1. 通读 PR 描述及关联 Issue
2. 浏览变更文件列表 —— 变更范围是否合理？
3. 评估整体方案 —— 这是否是解决该问题的恰当方式？
4. 确认变更未导致架构漂移（Architectural Drift）

第二轮（审查主要耗时）

1. 自上而下逐行阅读每个文件 Diff
2. 对照上述各清单逐项核查每个函数变更
3. 验证所有 I/O 边界处的错误处理逻辑
4. 对任何引发疑虑的内容及时标记 —— 信任你的直觉

第三轮（5 分钟）

1. 思考该代码在生产环境中可能发生的故障场景
2. 检查此前标记路径是否补充了相应测试
3. 验证回滚安全性 —— 此变更能否在不丢失数据的前提下安全回退？
4. 确认文档与变更日志（Changelog）是否按需更新

严重程度分级

为每条评论标注严重程度，便于作者快速识别哪些问题会阻断合并。

务必在每条评论开头添加严重程度标签，消除理解歧义。

反馈撰写规范

基本原则

• 具体明确 — 指出确切行号，并解释问题本质，而非简单断言“此处有误”
• 阐明原因 — 说明潜在风险或后果，而非仅复述规则
• 提供方案 — 尽可能给出具体修改建议或可运行的代码片段
• 以问代令 — 对主观判断点使用提问语气：“您觉得……如何？”
• 肯定亮点 — 明确指出简洁的实现、巧妙的优化或完备的测试
• 区分阻断与非阻断项 — 使用严重程度标签帮助作者快速识别优先级

示例评论

反面示例：

此处有误，请修正。

正面示例：

[MAJOR] 此查询将用户输入直接拼接进 SQL 字符串（第 42 行），存在 SQL 注入风险。建议改用参数化查询：

SELECT * FROM users WHERE id = $1

反面示例：

为何未补充测试？

正面示例：

[MINOR] 新增的 calculateDiscount() 函数包含多个分支路径，建议补充零数量与负价格等边界情况的测试用例，以防回归。

反面示例：

我会用不同方式实现。

正面示例：

[NIT] 当前实现效果良好。另一种思路是将重试逻辑抽离为共享的 withRetry() 封装器 —— 此为可选优化，可后续跟进。

审查反模式

避免以下常见误区，以免浪费时间并损害团队信任：

绝对禁止事项

1. 绝对禁止未逐行审阅即批准 —— 走形式审批比不审查危害更大
2. 绝对禁止仅因风格偏好阻断 PR —— 交由 Linter 自动约束；人工审查聚焦逻辑正确性
3. 绝对禁止未标注严重程度的反馈 —— 模糊性将导致无效返工
4. 绝对禁止未说明原因即要求修改 —— “请修复此处”无法传递任何知识
5. 绝对禁止单次审查超过 400 行 —— 理解力急剧下降；大 PR 应拆分为多次审查
6. 绝对禁止跳过安全审查清单 —— 一个遗漏的漏洞，其危害远超百条风格建议
7. 绝对禁止人身攻击 —— 审查对象是代码，不是开发者；请始终假定对方善意