Go 代码审查

审查工作流

请严格按以下**顺序**执行。在满足下方所有 **“通过（Pass）”** 条件前，**不得输出任何问题发现（findings）**。

1. 基线 go.mod — 打开 go.mod 文件，读取其中的 go 指令。
   通过条件：你能在审查前言或工作笔记中明确陈述该模块所声明的精确 go X.YY 版本号（例如 go 1.21）。仅当当前基线版本匹配时，才可应用对应版本限定的建议（如：Go < 1.22 时需注意循环变量捕获问题；Go 1.21+ 可用 slog/结构化日志；Go 1.20+ 可用 errors.Join）。

2. 阅读上下文代码 — 对每个被修改的 .go 文件，须通读包含变更的完整函数或逻辑单元，而不仅限于 diff 片段。
   通过条件：对每个被修改的文件，至少通读一个完整封闭的函数（或包级 init 函数 / 变量块），且该函数/块必须包含本次变更。

3. 划定检查清单范围 — 判断哪些《审查检查清单》模块适用于本次 diff（如：错误处理、并发、接口/类型、资源、命名）。为适用模块加载对应参考文档；跳过与 diff 完全无关的模块。
   通过条件：审查报告或工作笔记中须列出已应用的检查清单模块；对不适用模块，须标注 “N/A” 并附上一句紧扣 diff 的简要理由（例如：“变更中无任何并发逻辑”）。

4. 报告前验证 — 加载并严格执行 review-verification-protocol（审查验证协议）。
   通过条件：对拟报告的每一项问题，均须满足该协议中的报告前验证检查清单（包括：实际阅读了相关代码、核查了上下文、区分了“错误”与“风格差异”，等等）。

硬性关卡（相同顺序，精简版）

输出格式

请按如下格式报告问题发现：

[FILE:LINE] ISSUE_TITLE
Severity: Critical | Major | Minor | Informational
问题描述及影响说明。

速查参考

审查检查清单

错误处理

• 所有错误均已检查（禁止出现无注释说明的 _ = err）
• 错误已通过上下文进行包装（例如 fmt.Errorf("...: %w", err)）
• 使用 errors.Is/errors.As 替代字符串匹配进行错误判断
• 多个错误聚合时使用 errors.Join（Go 1.20+）
• 错误返回时同步返回零值

并发

• 无 goroutine 泄漏（存在 context 取消机制或明确的关闭信号）
• 通道仅由发送方关闭，且仅关闭一次
• 共享状态受互斥锁（mutex）或 sync 类型保护
• 使用 WaitGroup 等待 goroutine 完成
• Context 在调用链中正确传递
• 循环变量捕获问题已妥善处理（仅适用于 Go < 1.22 的代码库）

接口与类型

• 接口由消费者定义，而非生产者定义
• 接口名称遵循 -er 命名惯例（如 Reader, Closer）
• 接口定义保持最小化（1–3 个方法）
• 构造函数返回具体类型（而非接口）
• Go 1.18+ 代码库中优先使用 any 而非 interface{}
• 在合适场景下使用泛型，替代 any 或代码生成

资源与生命周期

• 资源创建后立即用 defer 关闭
• HTTP 响应体始终被关闭
• 循环内不使用未包裹闭包的 defer
• 避免使用 init() 函数，改用显式初始化逻辑

命名与风格

• 导出标识符均有文档注释
• 无冗余命名（如 user.UserService → 应为 user.Service）
• 函数长度超过 5 行时禁用裸返回（naked return）
• Context 作为第一个参数传入
• Go 1.21+ 代码库中，结构化日志应使用 slog 而非 log

严重程度校准

Critical（阻断合并）

• I/O、网络或数据库操作中未检查错误
• goroutine 泄漏（无关闭路径）
• 共享状态存在竞态条件（如未加同步的并发 map 访问）
• 资源无限累积（如循环内 defer、连接未关闭）

Major（建议修复）

• 错误返回缺少上下文（如直接 return err）
• 启动 goroutine 后未使用 WaitGroup 等机制等待完成
• 对可恢复错误使用 panic
• Context 未向下游调用传递

Minor（酌情修复）

• Go 1.18+ 代码库中仍使用 interface{} 而非 any
• 导出标识符缺失文档注释
• 存在冗余命名
• 已知切片大小却未预分配容量

Informational（仅作提示）

• 建议在存在代码生成的位置引入泛型
• 关于接口设计的重构思路
• 未经实测验证的性能优化建议

何时加载参考文档

• 审查错误返回模式 → error-handling.md
• 审查 goroutine、通道或 sync 类型 → concurrency.md
• 审查类型定义、接口或泛型 → interfaces.md
• 常规审查（资源、命名、init、性能等） → common-mistakes.md

有效模式（请勿标记）

以下均为合法的 Go 模式，标记它们将浪费开发者时间：

• _ = err 并附带说明性注释 — 明确忽略错误且提供合理解释
• 空接口 / any — 用于真正泛型场景或与无类型 API 交互
• 短函数中的裸返回 — 函数长度 < 5 行且具有命名返回值时可接受
• 未关闭的通道 — 当消费者通过 context 取消而非通道关闭来终止时
• 互斥锁保护结构体字段 — 即使字段仅通过方法访问，此封装方式亦属正确
• //nolint 指令附带原因说明 — 有解释说明时视为合理
• 循环内使用 defer — 当意图是清理函数作用域资源时（如分批处理文件）
• 函数式选项模式（Functional Options Pattern） — type Option func(*T) 配合 With* 构造函数属于惯用法
• sync.Pool 用于热点路径 — 在性能关键代码中减少内存分配压力时可接受
• context.Background() 用于 main 函数或测试中 — 顶层调用的有效根 Context
• select 中含 default 分支 — 非阻塞通道操作，属有意为之的模式
• 小作用域内的短变量名 — i、err、ctx、ok 等为 Go 惯用写法

上下文敏感规则

仅当满足下列特定条件时，方可标记对应问题：

提交问题前

务必满足审查工作流中的第 4 步：加载 review-verification-protocol，并对每一项拟报告的问题，完整执行其“报告前验证检查清单”。