code-review-and-quality

name	code-review-and-quality
description	Multi-axis code review. Use before merging any change.

代码审查与质量保障

概述

一套多维度的代码审查方法论，确保每次变更加入代码库时都经过正确性、可读性、架构、安全性和性能的检验。审查不是找茬，而是知识共享和质量兜底。

何时使用

• PR/MR 合并前的强制审查
• 紧急修复的快速审查（严格程度可调整，但不能省略）
• 不适用于：代码已合并后的马后炮（应通过回溯或文档处理）

审查维度

1. 正确性（Correctness）

• 代码是否实现了需求？有没有遗漏边缘情况？
• 是否存在竞态条件、并发问题？
• 错误处理是否完备？外部依赖失效时的行为是否可接受？
• 类型系统和编译检查是否覆盖了变更？

2. 可读性与简洁性（Readability & Simplicity）

• 代码是否自文档化？命名是否表达了意图？
• 有没有过度抽象或不必要的复杂性？
• 能否用更少的代码实现相同功能？

3. 架构（Architecture）

• 变更是否符合项目的分层和模块边界？
• 是否引入了循环依赖或深层耦合？
• 新增的抽象是否值得其复杂度成本？

4. 安全性（Security）

• 用户输入是否经过校验和转义？
• 是否存在注入风险（SQL、XSS、命令注入）？
• 敏感数据（密钥、Token、PII）是否被正确处理？

5. 性能（Performance）

• 是否存在 N+1 查询、不必要的重计算、内存泄漏？
• 热路径上的代码是否高效？
• 大数据量场景下是否经过验证？

变更尺寸与审查策略

变更行数	预期	处理方式
≤100	标准的 PR 尺寸	完整审查所有维度
100–500	需要拆分	请作者拆分为多个 PR，或至少提供变更摘要
≥500	极不推荐	应拆分为逻辑独立的提交；大规模重构需额外审查会议

严重性标签

标签	含义	行动
Critical	正确性或安全性问题，合并将导致故障	必须修复后方可合并
Nit	风格或小优化，不影响功能	作者自行决定是否采纳
Optional	建议或替代方案	讨论后可选择是否跟进
FYI	信息分享，无需行动	阅读后标记已读即可

审查速度规范

• 小 PR（≤100行）：24 小时内开始审查
• 中 PR（100–300行）：48 小时内开始审查
• 大变更：需提前协调审查时间

结构性补救措施

当发现代码质量问题时，可建议以下结构性改进（而非逐行注释）：

问题	推荐措施
函数过长	提取辅助函数，拆分职责
文件职责过多	拆分文件，单一职责原则
条件嵌套过深	提前返回（early return）、策略模式
重复逻辑	提取公共函数或抽象基类
硬编码值	提取为常量或配置
魔法数字	定义命名常量

死代码卫生

• 审查变更时注意是否引入了未使用的 import、变量、函数
• 删除注释掉的代码块（除非有明确的重用计划并附 TODO）
• 标记过时的注释和 FIXME——要么修复，要么删掉

完整审查清单

变更理解

• 理解了变更的背景和目的
• 确认 PR 描述与代码变更一致
• 检查了关联的 Issue/Ticket

正确性

• 核心逻辑正确，覆盖了正向和异常路径
• 边界条件和边缘情况已处理
• 错误处理完备（fail-fast vs graceful degradation 选择合理）
• 并发/异步代码无竞态

可读性

• 命名清晰准确
• 无冗余注释，有必要的复杂逻辑注释
• 函数和文件职责单一
• 遵循项目代码风格

架构

• 模块边界未破坏
• 无循环依赖
• 抽象层次合理

安全性

• 用户输入经过校验/转义
• 敏感信息未硬编码或泄露
• 身份验证和授权逻辑正确

性能

• 无 N+1 或不必要的循环
• 资源使用合理（内存、连接池、缓存）
• 大规模数据场景已验证

测试

• 新增/修改的代码有对应测试
• 测试覆盖了临界和异常场景
• 测试可读且稳定（无 flaky test）

基础设施

• CI 通过，Lint 无新增警告
• 日志和监控指标已评估
• 文档（README、API 文档、注释）已同步更新