go-code-review

Go 代码审查

面向 Go 的结构化代码审查流程。审查意见应具有建设性、具体明确，并引用每项问题背后的相关原则。

操作模式

开始前，选择与请求相符的模式：

• Diff 审查（默认）——仅审查发生变更的行，以及判断这些变更所需的上下文。适用于 PR 和工作树变更。
• 文件／包审查——完整审查指定文件或包，包括其测试。
• 全面审计——扫描整个代码库。采用下文“审计大型代码库”中的策略，并将所有结果汇总为一份报告。

审查流程

按顺序执行以下步骤。对每项问题进行严重程度分类：

• 🔴 阻断——合并前必须修复。涉及正确性、数据丢失或安全性。
• 🟡 警告——建议修复。涉及可维护性、Go 惯用写法或清晰度。
• 🟢 建议——可考虑改进。涉及风格、命名或文档。

0. 先运行工具链

手动阅读代码前，先让工具检查机械性问题 （跳过未安装的工具，并在报告中注明）：

go build ./...          # it must compile
go vet ./...            # suspicious constructs
golangci-lint run       # if the repo has a config
go test -race ./...     # tests pass, no data races

将工具发现的问题与手动审查发现的问题一并报告——go vet 检查失败自动视为 🔴 阻断。工具已证明不存在的问题，绝不要报告。

1. 正确性与安全性

错误处理

• 检查每个错误。不得使用空白标识符 _ 静默丢弃错误。
• 为错误添加上下文包装：fmt.Errorf("fetch user %d: %w", id, err)。
• 使用 errors.Is() / errors.As() 比较错误值，不得使用 ==。
• 除 init() 或确实无法恢复的情况外，不得使用 panic。
• 每个错误只处理一次——不得采用先记录再返回的模式。

Nil 安全性

• 当 nil 是有效状态时，解引用前先检查指针接收者。
• 对 map 读取进行防护，或使用逗号 ok 惯用法。
• 通道操作需考虑已关闭或 nil 通道。
• 在相关情况下，对切片操作检查边界。

并发

• 使用 sync.Mutex 或通道保护共享可变状态。
• 不得泄漏 goroutine——每个 goroutine 都应有明确的终止路径。
• 传播 Context：所有阻塞调用都应接收并遵循 context.Context。
• 使用 sync.WaitGroup 或 errgroup.Group 管理 goroutine 生命周期。

2. API 设计

• 导出函数应有以函数名开头的文档注释。
• 接收接口，返回具体类型。
• 对可选参数使用函数式选项（WithTimeout(d)），而不是配置结构体。
• Context 始终是第一个参数：func Foo(ctx context.Context, ...)。
• 将 error 作为最后一个返回值。
• 避免使用 bool 参数——优先使用具名类型或选项。

3. Go 惯用写法

• 局部变量使用 :=，表示有意采用零值时使用 var。
• return、continue 或 break 之后不需要再写 else。
• 使用保护子句和提前返回减少嵌套。
• 使用 defer 清理资源，并在获取资源后立即放置。
• 在适当情况下，使用 range 而不是手动按索引迭代。
• 结构体字面量使用字段名。
• 在使用方定义接口，而不是在提供方定义。

4. 包结构

• 包名应简短、小写，并使用单数名词。
• 包之间不得存在循环依赖。
• 对非公开包使用 internal/。
• cmd/ 存放主包，每个二进制文件对应一个。
• 职责应清晰分离——不得创建臃肿的万能包。

5. 测试

• 测试函数遵循 TestXxx 命名约定。
• 对多组输入／输出组合使用表驱动测试。
• 测试辅助函数使用 t.Helper()，以获得清晰的堆栈跟踪。
• 不得在 init() 中编写测试逻辑——需要时使用 TestMain。
• 测试应统一使用 testify/assert 或 testify/require，或者仅使用标准库。
• 覆盖边界情况：空输入、nil、零值、最大值。
• 在安全的情况下使用 t.Parallel()。

6. 文档

• 所有导出的类型、函数和常量都应有文档注释。
• 文档注释以实体名称开头。
• 对于非简单的包，在 doc.go 中编写包级文档注释。
• 对于复杂算法或业务逻辑，添加行内注释解释其原因。

7. 依赖项

• 已提交的代码中，go.mod 不包含 replace 指令（单体仓库除外）。
• 不存在未使用的依赖项。
• 依赖项来自维护良好、信誉可靠的来源。
• 已了解并认可间接依赖项。

审查大型代码库

当审查范围超过约 20 个文件时，不要一次线性读完所有内容。请将审查拆分为独立的环节：

1. 枚举软件包（go list ./...），并按层分组（处理程序、服务、存储、共享库）。
2. 针对第 1 至 7 节中的每项关注点，分别进行一次专项审查（正确性、API 设计、惯用写法、结构、测试、文档、依赖项）。
3. 如果环境支持将工作委派给并行子 Agent 或任务，请为每个环节分配一个——这些环节在设计上彼此独立。否则，按顺序逐项审查。
4. 要求每项发现都标注 file.go:line 和严重性，以便机械化汇总最终结果：合并、去重，并按严重性排序。

审查输出格式

## Code Review Summary

**Files reviewed:** <list>
**Overall assessment:** APPROVE | REQUEST CHANGES | COMMENT

### Findings

#### 🔴 BLOCKER: <title>
- **File:** `path/to/file.go:42`
- **Issue:** <what is wrong>
- **Why:** <which principle or guideline>
- **Fix:** <concrete suggestion>

#### 🟡 WARNING: <title>
...

#### 🟢 SUGGESTION: <title>
...

### What's Done Well
<genuine positive observations — always include at least one>