code-review

代码审查

步骤 0 — 选择范围

首先，向用户提出以下问题并等待回答：

---

你想审查什么？

1. 未提交的更改 — 已修改但尚未暂存或提交的文件（git diff HEAD）
2. 仅暂存的更改 — 已添加到索引但尚未提交的文件（git diff --cached）
3. 当前分支与基础分支的差异 — 此分支相较于其合并基点引入的所有提交（例如 git diff main...HEAD）
4. 特定提交 — 单个提交引入的更改（请提供提交哈希）
5. 提交范围 — 一系列提交中的更改（请提供 <from>..<to>）

输入你选择的编号。若选择 4 或 5，还需提供提交哈希或范围。

---

用户回答后，运行相应的 git 命令获取差异，然后继续执行以下审查。

选择	要运行的命令
1	git diff HEAD
2	git diff --cached
3	询问：“基础分支是什么？（例如 main、develop）” — 然后运行 git diff $(git merge-base HEAD <base-branch>)...HEAD
4	git show <commit-hash>
5	git diff <from>..<to>

---

报告问题时应标注严重级别：

• 严重：阻碍合并；合并前必须修复
• 警告：应在合并后尽快修复；不会阻碍合并
• 建议：可选改进；不会阻碍合并

---

步骤 1 — 调查代码库

开始审查前，检查以下文件以确定项目所用技术栈（仅阅读存在的文件）：

• package.json → 确定 JS/TS 框架、打包器和工具
• composer.json → 确定 PHP 框架（Laravel、Symfony 等）
• pyproject.toml / requirements.txt / setup.py → Python
• go.mod → Go
• *.csproj / global.json → .NET / C#
• pom.xml / build.gradle → Java / Spring Boot
• pubspec.yaml → Flutter / Dart
• vite.config.* / webpack.config.* → 打包器和前端技术栈
• tailwind.config.* → Tailwind CSS
• tsconfig.json → TypeScript
• Dockerfile / docker-compose.yml → Docker
• *.tf → Terraform / IaC
• 顶层目录结构 → 架构模式信号（DDD、Clean Architecture 等）

根据发现的内容，仅加载并应用与本项目匹配的技术栈和模式文件。不要评估或报告项目未使用的技术。

API 验证： 在指出库 API 用法错误之前，使用 mcp__plugin_context7_context7__query-docs，针对 package.json 或 composer.json 中检测到的版本，依据实时文档验证语法和最佳实践。避免因训练数据过时而产生误报。

相关时需加载的技术栈文件：

使用相对于此技能文件目录的路径读取这些文件。如果无法读取某个文件，请继续使用上述通用规则。

• ./stacks/laravel.md
• ./stacks/vue.md
• ./stacks/nuxt.md
• ./stacks/react.md
• ./stacks/angular.md
• ./stacks/svelte.md
• ./stacks/typescript.md
• ./stacks/tailwind.md
• ./stacks/node.md
• ./stacks/python.md
• ./stacks/go.md
• ./stacks/java-spring.md
• ./stacks/dotnet.md
• ./stacks/react-native.md
• ./stacks/flutter.md
• ./stacks/docker.md
• ./stacks/terraform.md
• ./stacks/kafka.md
• ./stacks/inertia.md
• ./stacks/pest.md

相关时需加载的模式文件：

使用相对于此技能文件目录的路径读取这些文件。如果无法读取某个文件，请继续使用上述通用规则。

• ./patterns/clean-architecture.md
• ./patterns/ddd.md
• ./patterns/event-driven.md
• ./patterns/microservices.md
• ./patterns/cqrs.md

步骤 1.5 — 一致性检查

在指出任何模式违规之前，先检查代码库中已有的做法。Laravel、Vue 等框架提供了多种有效方案——最佳选择是项目中已确立的方案，即使从理论上看，其他方案更好。不一致比模式不够理想更糟糕。

• 检查同级控制器、服务、组件或测试中已确立的约定
• 如果项目已经持续采用某种非标准模式，就遵循该模式——最多将其报告为建议，而不是阻塞项
• 当尚无既定模式时，这些检查清单规则才是默认做法，不应凌驾于行之有效的约定之上

---

1. 安全性

• 注入漏洞：SQL 注入、命令注入、XSS、LDAP 注入
• 身份验证与授权：进行适当的访问控制检查，不硬编码凭据，不暴露机密
• 输入验证与净化：在系统边界验证所有用户输入
• 敏感数据泄露：日志、响应或源代码中不得包含机密、令牌或个人身份信息
• CSRF 防护：保护会更改状态的操作，防止跨站请求伪造
• 依赖项漏洞：新增或更新的依赖项中不得存在已知的 CVE
• 文件上传处理：正确验证文件类型、大小和存储路径
• 速率限制与滥用防护：面向公众开放的端点应设有适当的限制
• 安全默认设置：加密、HTTPS、安全 Cookie 和正确的 CORS 配置
• 批量赋值防护：对象不得不加区分地接受所有用户输入字段

---

2. 性能

• N+1 查询：数据访问模式应避免不必要的重复查询
• 索引：新查询应有适当的数据库索引作为支持
• 缓存：对开销大或重复执行的操作适当使用缓存
• 分页：对大型数据集进行分页，而不是全部加载到内存中
• 延迟加载与预加载：根据使用场景高效加载关联数据
• 不必要的计算：不得有冗余循环、重复计算或重复渲染
• 内存泄漏：不得遗留未清理的事件监听器、订阅或引用
• 打包体积：不得为了少量功能添加不必要的大型依赖项
• 数据库事务：避免长时间运行的事务，将事务范围控制在最小限度
• 异步操作：在适用的情况下，使用异步模式处理 I/O 密集型工作

---

3. 测试与覆盖率

• 新代码有测试：所有新增的公共方法和端点都应有对应测试
• 覆盖边界情况：空值、空集合、边界条件和错误状态
• 成功与失败路径：同时测试成功和失败场景
• 测试隔离：测试之间不应相互依赖，也不应依赖外部状态
• 模拟：正确模拟外部服务和 I/O；单元测试中不得进行真实的 API 调用
• 断言有意义：测试应断言行为，而不是实现细节
• 覆盖率：测试覆盖率不得显著下降
• 回归测试：修复 Bug 时，应有能够发现该问题的测试

---

4. 架构与设计原则

SOLID

• 单一职责：每个类、模块或函数都应做好一件事
• 开闭原则：无需修改现有行为即可扩展代码
• 里氏替换原则：子类型可以替换其基类型，而不会破坏行为
• 接口隔离原则：接口应小而专注，不能臃肿
• 依赖倒置原则：高层模块应依赖抽象，而不是具体实现

DRY（不要重复自己）

• 不要在文件或方法之间重复逻辑——当重复会带来不一致风险时，应提取共享逻辑

KISS（保持简单）

• 使用能解决问题的最简单方案；避免过度设计
• 不要过早抽象，也不要使用不必要的设计模式

通用

• 关注点分离：业务逻辑、数据访问和表示层清晰分离
• 命名规范：变量、函数和类都使用清晰且具有描述性的名称
• 错误处理：妥善处理错误并提供有意义的消息；不得静默捕获异常
• 代码可读性：代码应具有自解释性；复杂逻辑应添加简短的说明性注释
• 无死代码：删除未使用的导入、变量、函数或已注释掉的代码块
• 模式一致：新代码遵循代码库中已确立的模式
• 不可变性：适当时优先使用不可变数据结构；避免更改共享状态
• 纯函数：隔离副作用并明确说明；尽可能将核心逻辑编写为纯函数

代码与文件大小

• 方法／函数长度：超过 30 行的方法应说明其合理性；超过 50 行的方法必须重构——这类方法承担的职责过多（Clean Code／30 行规则）
• 类长度：超过 200 行的类应检查是否违反单一职责原则；超过 500 行的类必须拆分
• 文件长度：超过 300 行的源文件表明可能承担多项职责；超过 500 行的文件应进行检查并拆分
• 组件长度（Vue／React）：总行数超过 300 行的 SFC 或组件应拆分；尽可能将 <template> 和 <script> 块分别控制在 150 行以内
• Git 中的二进制文件：不得将图像、PDF、视频、数据库转储和编译后的二进制文件提交到代码库；.gitignore 应涵盖这些文件；必须纳入版本管理的大型资源应使用 Git LFS
• 运行时读取文件：如果文件大小没有上限且可能很大，应通过流式方式从磁盘读取文件（而不是将整个文件加载到内存中）

---

5. 潜在 Bug 调查

主动跟踪修改过的代码，查找潜在 Bug——不要只检查风格或结构。对于以下每一项，都应推理变更涉及的代码路径，并报告任何可能导致行为错误、数据损坏或运行时故障的问题。

• 对 null／undefined／0 的解引用：找出变量在使用时可能为 null、undefined、0 或空集合，且未进行防护的路径
• 差一错误：检查循环边界、切片索引、分页偏移，以及使用 < 而非 <= 等比较的情况
• 条件反转或不完整：检查看起来颠倒的逻辑条件（应为 === 却写成了 !==）、缺失的 else 分支，或没有 default 的 switch 分支
• 对状态的隐式假设：检查未经验证便假设记录存在、列表非空、值已设置或上一步已成功的代码
• 与依赖项的契约遭破坏：检查方法签名、返回结构、事件负载或数据库列的变更是否已同步到所有调用方、使用方或下游模块
• 异步流程中的竞态条件：检查多个异步操作是否共享状态，以及它们交错执行是否可能导致结果不一致
• 数据变更副作用：检查函数是否以调用方意料之外的方式修改其输入参数、共享集合或全局状态
• 查询／迁移的数据风险：检查 SQL 变更是否可能静默丢弃数据、导致现有行产生错误结果，或在表为空与非空时表现不同
• 静默成功的错误路径：检查是否存在吞掉异常并返回成功响应的 catch 块、缺少重新抛出异常的情况，或仅记录错误却未向上传递的情况
• 类型强制转换引发的意外结果：检查隐式类型强制转换（PHP 的宽松比较、JavaScript 的 ==、字符串转数字）是否可能在变更代码的边界处导致错误结果
• 不可达或死逻辑：检查永远无法成立的条件、无条件 return 之后的代码，以及与前置防护条件矛盾的分支

---

6. 无障碍 (仅当差异包含前端/UI 更改时)

• 语义化 HTML：正确使用标题、地标、列表、按钮和表单元素
• ARIA 属性：正确使用 aria-label、aria-describedby、role 等属性，且仅在原生语义不足时使用
• 键盘导航：所有交互元素都可通过键盘访问和操作
• 焦点管理：焦点顺序合理；在模态框/对话框中适当使用焦点陷阱
• 颜色对比度：文本和 UI 元素符合 WCAG AA 对比度要求
• 图像和图标：有意义的图像应提供 alt 文本；装饰性图像应使用 alt=""
• 表单标签：所有输入框都应关联 <label> 或 aria-label

---

7. 可观测性

• 结构化日志：日志采用结构化格式（JSON 或 key=value）；生产代码中不留有 console.log / var_dump
• 日志中的敏感数据：不得记录密码、令牌、个人身份信息（PII）或机密信息，即使是部分内容也不行
• 日志级别：使用恰当的日志级别（debug、info、warning、error）；不得将关键事件记录为 debug
• 关联 ID：请求和异步任务在日志中携带贯穿始终的追踪/关联 ID
• 错误报告：捕获异常并将其转发到错误跟踪系统（例如 Sentry、Bugsnag）
• 指标：在适用情况下，为重要的新操作（队列任务、外部调用、缓存命中）添加监控

---

8. API 设计 (仅当差异包含 API 端点或 API 客户端代码时)

• HTTP 方法：使用正确的方法（读取使用 GET，创建使用 POST，更新使用 PUT/PATCH，删除使用 DELETE）
• 状态码：返回正确的 HTTP 状态码（创建时返回 201，无内容时返回 204，验证错误时返回 422，未找到时返回 404 等）
• 版本控制：在 URL 或标头中体现 API 版本；破坏性更改应提升版本号
• 统一的错误响应：所有端点的错误载荷都遵循统一结构
• 分页：采用一致的分页策略（游标或偏移量）；在响应中包含元数据
• 筛选和排序：查询参数遵循既定约定
• 幂等性：PUT/PATCH/DELETE 操作应具备幂等性；适当情况下，POST 操作也应具备幂等性（例如使用幂等键）
• URL 中不得包含敏感数据：通过标头或请求正文传递令牌、密码和个人身份信息（PII），而非查询字符串或路径
• GraphQL (仅当项目使用 GraphQL 时)：使用 DataLoader 避免 N+1 问题，限制查询深度，在生产环境中禁用内省，并验证变更操作的输入

---

9. 弹性与容错 (仅当差异涉及外部调用、队列或关键流程时)

• 超时：所有出站 HTTP 调用、数据库查询和队列操作都应设置明确的超时时间
• 退避重试：对瞬时故障采用带抖动的指数退避重试；不可重试的错误不得重试
• 断路器：对外部依赖的连续失败应触发断路器，防止故障级联
• 优雅降级：非关键依赖不可用时，系统应能优雅降级
• 幂等性：可能重试的操作应具备幂等性（可安全执行多次）
• 舱壁隔离：缓慢或发生故障的依赖不得耗尽共享资源（线程池、连接）

---

10. 零停机数据库迁移 （仅当差异包含迁移时）

• 先进行增量式变更：在应用代码使用新列之前，将其添加为可空列或设置默认值
• 禁止立即添加无默认值的 NOT NULL 列：在大型表中添加无默认值的 NOT NULL 列会导致整张表被锁定
• 列/表重命名安全性：过渡期间保留旧列，并同时使用新列；代码部署完成后，在后续迁移中再重命名
• 列删除安全性：仅在代码不再引用该列且部署稳定后才删除该列
• 创建索引：在大型表上创建索引时使用并发方式（例如 CREATE INDEX CONCURRENTLY），以避免锁定
• 可逆性：down 方法应能正确撤销 up 方法，且不会造成数据丢失

---

11. 并发与线程安全 （仅当差异涉及共享状态、后台任务或并发操作时）

• 竞态条件：对共享状态的操作是原子的，或经过适当同步
• 锁与互斥锁：锁定策略正确；不存在潜在死锁（锁定顺序一致）
• 原子操作：计数器和标志位以原子方式更新（例如数据库原子递增、比较并交换）
• 任务唯一性：必须避免并发运行的后台任务受到唯一锁保护
• 共享可变状态：避免使用全局或静态可变状态；应注入依赖，而不是共享依赖

---

12. 国际化（i18n）（仅当项目支持多种语言或区域设置时）

• 无硬编码字符串：所有面向用户的文本都使用翻译键，而不是内联字符串
• 日期与时间格式：通过支持区域设置的工具格式化日期、时间和时长，而非手动拼接字符串
• 数字与货币格式：根据用户的区域设置格式化数字和货币金额
• 复数形式：通过 i18n 库正确处理复数形式，而不是使用手动条件判断
• RTL 支持：如果支持 RTL，布局在从右到左书写的语言中也不会错乱
• URL 或标头中的区域设置：区域设置应根据用户偏好或 Accept-Language 确定，而非硬编码

---

13. 隐私与数据合规 （仅当差异涉及用户数据、个人身份信息或数据存储时）

• 尽量减少数据收集：仅收集和存储该功能严格必需的数据
• 个人身份信息处理：识别个人数据，在需要时对静态数据加密，并进行访问控制
• 数据保留：根据既定的数据保留政策删除或匿名化数据
• 同意：需要用户同意的数据收集必须以明确的主动选择为前提
• 审计跟踪：记录对敏感数据的访问和修改，以供审计
• 与第三方共享数据：记录与外部服务共享的数据，并将其限制在必要范围内

---

14. 做得好的地方

列出问题之前，先肯定此次变更做得好的方面。指出出色的设计决策、良好的测试覆盖率、清晰的抽象，或任何值得肯定并应继续沿用的做法。

---

15. 输出格式

针对每项发现，按以下格式报告：

### [Category] — [Severity]

**File:** `path/to/file.ext:line`
**Issue:** Brief description of the problem.
**Fix:** Suggested correction or approach.

最后，提供一张涵盖所有已评估类别的摘要表（不适用于此次变更的类别请填写 N/A）：

## Summary

| Category              | Critical | Warning | Suggestion | N/A |
|-----------------------|----------|---------|------------|-----|
| Security              | 0        | 0       | 0          |     |
| Performance           | 0        | 0       | 0          |     |
| Tests/Coverage        | 0        | 0       | 0          |     |
| Architecture          | 0        | 0       | 0          |     |
| Code & File Size      | 0        | 0       | 0          |     |
| Potential Bugs        | 0        | 0       | 0          |     |
| Accessibility         | 0        | 0       | 0          |     |
| Observability         | 0        | 0       | 0          |     |
| API Design            | 0        | 0       | 0          |     |
| Resilience            | 0        | 0       | 0          |     |
| DB Migrations         | 0        | 0       | 0          |     |
| Concurrency           | 0        | 0       | 0          |     |
| i18n                  | 0        | 0       | 0          |     |
| Privacy/Compliance    | 0        | 0       | 0          |     |
| Architecture Patterns | 0        | 0       | 0          |     |
| Stack-Specific        | 0        | 0       | 0          |     |
| **Total**             | **0**    | **0**   | **0**      |     |

如果没有发现问题，请写明：“代码审查通过——未发现问题。”