code-reviewer

代码审查技能

全面的代码审查技能，采用基于 2025 年研究成果的最佳实践，包含自动化安全检查、性能分析和质量标准执行。

核心理念

兼顾质量与安全：

• 50% 关注安全（OWASP Top 10、漏洞、身份验证）
• 30% 关注代码质量（可维护性、标准、重复代码）
• 20% 关注性能（N+1 查询、算法复杂度、包体积）

研究发现： 持续进行代码审查的团队修复漏洞的速度比传统批量审查快 92%。

---

何时使用此技能

提及以下内容时自动调用：

• “审查这段代码”
• “检查是否有 Bug”
• “安全审计”
• “分析这个 PR”
• “代码审查”
• “检查代码质量”
• “审查我的更改”
• “查找漏洞”
• “检查性能”

手动调用：

• 提交关键更改前
• 部署前验证
• 实现安全敏感功能后
• 整合 SAST 工具结果时

---

核心审查工作流

初次进行代码审查？ 请参阅 EXAMPLES.md，其中包含完整的演练示例，展示了优秀与糟糕的审查。

阶段 1：自动化分析（首先运行）

步骤 1：确定要审查的代码

• 审查特定文件：读取这些文件
• 审查 PR/更改：使用 git diff 查看更改
• 审查整个功能：通过 grep/glob 找出受影响的文件

步骤 2：运行自动化 SAST 工具（如果可用）

使用 scripts/ 目录中的脚本：

# Quick security audit
bash scripts/quick-audit.sh

# Or run individual tools:
npm audit                    # Dependency vulnerabilities
npm run lint                 # ESLint code quality
npx prettier --check .       # Code formatting

# Advanced (if installed):
sonar-scanner               # SonarQube
codeql database analyze     # CodeQL
snyk test                   # Snyk security

步骤 3：解析 SAST 结果

• 按严重程度对发现的问题分类（严重/高/中/低）
• 过滤误报（记录判断依据）
• 与手动检查结果交叉核对

阶段 2：手动安全分析

检查 OWASP Top 10 2021（当前标准）：

1. A01:2021 – 访问控制失效

   • 是否对所有受保护路由执行身份验证检查？
   • 是否在做出授权决策前验证用户输入？
   • 是否保护直接对象引用（防止 IDOR）？

2. A03:2021 – 注入（SQL、NoSQL、命令）

   • 是否使用参数化查询，而非字符串拼接？
   • 是否在执行数据库查询前清理用户输入？
   • 是否正确使用 ORM（不使用带有用户输入的原始查询）？

3. A03:2021 – 跨站脚本攻击（XSS）

   • 是否在 HTML 中渲染用户输入前对其进行转义？
   • 是否配置了内容安全策略标头？
   • 是否避免使用 dangerouslySetInnerHTML，或对其进行适当清理？

4. A07:2021 – 身份识别和身份验证失效

   • 是否使用 bcrypt/argon2 哈希密码（而非 MD5/SHA1）？
   • 会话管理是否安全（httpOnly Cookie、CSRF 令牌）？
   • 是否对登录端点实施速率限制？

5. A02:2021 – 加密机制失效

   • 敏感数据在静态存储和传输过程中是否加密？
   • API 密钥/机密是否存储在环境变量中（而非硬编码）？
   • 是否对所有外部通信强制使用 HTTPS？

完整的 OWASP Top 10 检查清单请参阅 REFERENCE.md

阶段 3：性能模式检测

检查常见性能问题：

1. N+1 查询问题

   // 🔴 BAD: N+1 queries
   users.forEach(user => {
     db.query("SELECT * FROM posts WHERE user_id = ?", user.id)
   })
   
   // ✅ GOOD: Single query with JOIN
   db.query("SELECT * FROM users LEFT JOIN posts ON users.id = posts.user_id")
   

2. O(n²) 或更差的算法

   • 对大型数据集使用嵌套循环
   • 排序/搜索效率低下
   • 递归函数未使用记忆化

3. 缺少数据库索引

   • 查询未建立索引的列
   • WHERE 子句没有相应索引
   • JOIN 操作使用未建立索引的外键

4. 内存泄漏

   • 未清理事件监听器
   • 闭包持有大型对象
   • 缓存无上限

5. 包体积过大

   • 导入整个库，而非特定函数
   • 图片未优化
   • 缺少代码拆分

性能模式目录请参阅 REFERENCE.md

阶段 4：代码质量标准

检查 TypeScript/JavaScript 标准：

• 未提供说明注释的 any 类型
• 妥善处理错误（没有空的 catch 块）
• 没有 console.log 语句（使用适当的日志记录）
• 函数少于 50 行（较长时应拆分）
• 圈复杂度小于 10
• 没有注释掉的代码
• 导入顺序遵循约定（React → 第三方 → 内部 → 相对路径）

检查命名约定：

• 文件：kebab-case（user-service.ts）
• 组件：PascalCase（UserProfile.tsx）
• 函数/变量：camelCase（getUserData）
• 常量：UPPER_SNAKE_CASE（MAX_RETRIES）

完整标准检查清单请参阅 REFERENCE.md

阶段 5：生成审查报告

使用 resources/templates/ 中的模板创建结构化输出：

• 全面审查： 使用 resources/templates/code-review-report.md
• 安全审计： 使用 resources/templates/security-review-template.md
• 性能审查： 使用 resources/templates/performance-review-template.md
• 快速检查： 使用 resources/templates/quick-checklist.md

报告格式示例：

# Code Review Report

**Verdict:** ✅ APPROVED | ⚠️ APPROVED WITH RESERVATIONS | ❌ REQUIRES REVISION
**Files Reviewed:** [List]
**Review Date:** [ISO Date]

## Critical Issues (Must Fix Before Merge)
[None or list with code snippets]

## High Priority Issues (Fix Within 48h)
[None or list with recommendations]

## Medium Priority Issues (Fix This Sprint)
[None or list]

## Low Priority / Suggestions
[Optional improvements]

## Strengths & Good Practices
[What was done well]

## Metrics
- **Lines Changed:** X
- **Files Modified:** Y
- **Estimated Risk:** Low/Medium/High
- **Test Coverage:** Z%

---

与 SAST 工具集成

SonarQube 集成

如果有 SonarQube 结果：

1. 读取 sonar-report.json 或访问 SonarQube API
2. 将人工审查重点放在 SonarQube 遗漏的问题上：
   • 业务逻辑漏洞
   • 特定上下文中的安全问题
   • 授权逻辑
3. 验证 SonarQube 的发现（检查误报）

需要审查的 SonarQube 关键指标：

• 安全热点： 需要人工验证
• 代码异味： 可维护性问题（阈值：A 级或 B 级）
• 重复代码： 保持在 3% 以下
• 覆盖率： 目标高于 80%

CodeQL 集成

如果有 CodeQL 扫描结果：

1. 在 GitHub Security 选项卡中查看 CodeQL 警报
2. 按严重程度排列警报优先级：
   • 严重/高： 合并前必须修复
   • 中： 在当前冲刺内修复
   • 低： 纳入待办列表
3. 在有可用建议修复时使用 CodeQL 的建议
4. 对以下内容进行人工审查：
   • 身份验证流程
   • 授权决策
   • 加密操作

CodeQL 优势（准确率 88%）：

• SQL 注入检测
• 路径遍历漏洞
• 命令注入
• 不安全的反序列化

Snyk 集成

如果有 Snyk 结果：

1. 运行 snyk test 检查依赖项漏洞
2. 运行 snyk code test 检查代码级问题
3. 按以下优先级处理：
   • 严重： 立即修复
   • 高： 在 7 天内修复
   • 中： 在 30 天内修复
4. 检查是否有可用补丁：snyk wizard

Snyk 优势：

• 依赖项漏洞（实时 CVE 数据库）
• 许可证合规性
• 容器安全
• 基础设施即代码（IaC）扫描

ESLint + Prettier + npm audit

基本安全工具栈（始终运行）：

# Run these three commands ALWAYS
npm audit --audit-level=high    # Dependency vulnerabilities
npm run lint                    # Code quality (ESLint)
npx prettier --check .          # Code formatting

解读：

• npm audit： 修复所有高危/严重漏洞
• ESLint： 必须通过且错误数为 0（有记录的警告可以接受）
• Prettier： 使用 npx prettier --write . 自动修复

---

严重程度分类

使用此框架对所有发现的问题进行分类：

🔴 严重（阻止部署）

• SQL 注入漏洞
• XSS 漏洞（未转义的用户输入）
• 身份验证绕过
• 硬编码的密钥/API 密钥
• 远程代码执行（RCE）风险
• 以纯文本形式记录的敏感数据

操作： 停止。继续之前必须立即修复。

🟠 高（在 48 小时内修复）

• 缺少身份验证检查
• 不安全的会话管理
• CSRF 漏洞
• 敏感端点缺少速率限制
• 弱加密算法（MD5、SHA1）
• 关键路径中的 N+1 查询问题
• 生产代码中的内存泄漏

操作： 创建阻塞工单。在下次部署前修复。

🟡 中（本迭代修复）

• 缺少输入验证（非关键字段）
• 算法效率低下（在小型数据集上为 O(n²)）
• 缺少数据库索引（少于 1000 行）
• 代码重复（超过 5 处）
• 缺少错误处理
• 无障碍访问违规（WCAG AA）

操作： 创建工单。在当前迭代内修复。

🔵 低（待办事项／可选优化）

• 代码风格违规（如果未通过 linter 强制执行）
• 复杂代码缺少注释
• 轻微的性能优化
• 重构机会
• 文档改进

操作： 可选。添加到待办事项中，以便今后改进。

---

需要跟踪的关键指标

来自 2025 年的研究：

1. 平均修复时间（MTTR）

   • 目标：高严重性问题少于 7 天
   • 严重问题：少于 24 小时

2. 缺陷密度

   • 公式：（缺陷数量）／（每 1000 行代码）
   • 目标：每 1000 行代码少于 1.0 个缺陷

3. 审查覆盖率

   • 目标：审查所有变更行（100%）
   • 关键路径：100% 人工审查（而非仅依赖自动化）

4. 误报率

   • CodeQL：约 5%（同类最佳）
   • SonarQube：约 8–10%
   • Snyk：约 8%
   • 跟踪项目的误报率，以校准信任度

---

需要避免的常见陷阱

1. 过度依赖自动化

   • 自动化工具能发现 60–70% 的安全问题
   • 业务逻辑、授权和特定上下文问题仍需人工审查

2. 为了安全而忽视性能

   • 安全但无法使用的应用并不安全（性能问题可能导致 DoS）
   • 在安全检查与其对性能的影响之间取得平衡

3. 阻止每一个小问题

   • 使用严重性分类来确定优先级
   • 不要让追求完美阻碍进展

4. 只见树木，不见森林

   • 退一步，审查整体架构
   • 检查采用的方法在根本上是否合理

5. 未检查测试覆盖率

   • 未测试的代码＝未审查的代码
   • 要求所有安全关键路径都有测试

---

快速参考清单

批准任何代码审查之前：

安全：

• 无 SQL 注入漏洞（使用参数化查询）
• 无 XSS 漏洞（对用户输入进行转义）
• 受保护的路由上有身份验证检查
• 密钥存储在环境变量中（而非硬编码）
• 对外部 API 强制使用 HTTPS
• 状态变更端点启用 CSRF 防护

性能：

• 无 N+1 查询模式
• 在大型数据集上无 O(n²) 或更差的算法
• 查询列已建立数据库索引
• 无内存泄漏（清理事件监听器）
• 图片已优化并采用延迟加载

代码质量：

• 符合 TypeScript 严格模式（未经说明不得使用 any）
• 已进行错误处理（无空的 catch 块）
• 无 console.log 语句
• 函数少于 50 行
• 测试覆盖率超过 80%
• 无注释掉的代码

文档：

• 复杂逻辑有说明性注释
• 公共 API 有 JSDoc 注释
• 行为变更时已更新 README
• 已记录环境变量

---

审查后的后续步骤

如果已批准（✅）：

1. 合并 PR
2. 监控部署，排查问题
3. 更新测试覆盖率指标

如果有保留意见但已批准（⚠️）：

1. 为中低优先级问题创建工单
2. 修复严重和高优先级问题后即可合并
3. 安排后续审查

如果需要修改（❌）：

1. 提供包含代码片段的详细反馈
2. 在解决严重问题前阻止合并
3. 如有需要，主动提出结对编程来修复问题

---

配套文件

详细信息请参见：

• EXAMPLES.md - 完整的端到端代码审查示例（良好、不佳、以安全为重点）
• REFERENCE.md - 完整的 OWASP Top 10 检查清单、性能模式、CWE 参考
• FORMS.md - 审查报告模板概览和指南
• resources/templates/ - 可直接使用的审查模板
  • code-review-report.md - 全面审查模板
  • security-review-template.md - 以安全为重点的审计模板
  • performance-review-template.md - 性能分析模板
  • quick-checklist.md - 3 分钟快速审查检查清单
• resources/examples/ - 真实审查示例
  • good-review-example.md - 全面审查的示例
  • bad-review-example.md - 应避免的做法（敷衍了事的审查）
• scripts/ - 自动化 SAST 工具集成脚本
  • quick-audit.sh - 快速安全审计（Linux/Mac）
  • quick-audit.bat - 快速安全审计（Windows）

研究引用：

• OWASP 代码审查指南：https://owasp.org/www-project-code-review-guide/
• OWASP Top 10 2021：https://owasp.org/Top10/
• 实证研究（2024）：https://arxiv.org/html/2311.16396v2
• CWE Top 25：https://cwe.mitre.org/top25/

---

请记住： 代码审查的目的不是挑错，而是确保质量、安全性和可维护性。请提出有建设性的具体意见，并始终在指出问题的同时提供解决方案。