golang-master

Golang Master

适用于任何 Go 代码库的 Go 1.21+ 语言级准则（Go 1.22–1.26 的特性会在文中标注）。本技能是通用底线；如果与项目自身的指南技能冲突，以项目指南为准；项目未说明的内容则由本技能规定。

针对具体的 Go 问题，请阅读对应的参考章节。复用当前上下文；不要仅仅因为任务涉及 Go 就加载所有参考内容。是否适用取决于项目约定和支持的 Go 版本。

底线

适用于 Go 代码每一行的不可妥协要求，不受分支影响：

1. 每个错误都必须处理，或在丢弃错误的位置附上书面说明——绝不能直接使用 _。
2. 错误必须使用 fmt.Errorf("context: %w", err) 包装，并通过 errors.Is/errors.As 匹配——绝不能比较字符串。
3. 任何执行 I/O、会阻塞或跨越 API 边界的函数，都必须将 ctx context.Context 作为第一个参数，并传递调用方的 ctx——绝不能在调用链中途新建 context.Background()。
4. 每个 goroutine 都必须有负责人、退出路径，以及等待其完成的方式。
5. panic 仅用于不可能发生的状态；预期内的失败应返回错误。
6. 对不确定的类型断言进行检查。写入前初始化 map；如果语义符合契约，则使用 nil 或零值切片。
7. 对有意实现的契约使用编译时接口断言；不要仅为添加断言而凭空创建接口。
8. 测试应验证其所负责的不变量。多个用例使用表格；并发场景或项目有要求时执行竞态检查。
9. 应用 gofmt，并通过项目对应的 lint/test 门禁；复用当前已有的验证结果，不要每次编辑都运行整个仓库的 vet。
10. 运行时参数（超时、限制、地址）必须来自配置或选项——绝不能硬编码。

分支

任务涉及……	阅读
创建、包装、匹配、记录或合并错误；panic/recover 策略	references/errors.md
Goroutine、通道、select、sync 原语、errgroup、工作池、竞态	references/concurrency.md
取消、超时、截止时间、上下文值、脱离调用链的后台任务	references/context.md
nil 陷阱、append 别名、map 访问、数值转换、循环中的 defer、零值	references/safety.md
设计结构体、接口、嵌入、接收者、字段标签、泛型	references/interfaces-generics.md
命名、控制流结构、构造函数、函数式选项、init()	references/style-naming.md
编写或审查测试、基准测试、模糊测试、集成构建标签	references/testing.md
性能分析、内存分配排查、GC 调优、基准测试比较	references/performance.md
旧式模式、已弃用 API、Go 版本升级	references/modernize.md
新建模块、目录布局、cmd/internal/pkg、工作区	references/layout.md

会取消任务的并发工作，需同时阅读 concurrency.md 和 context.md。代码审查时，应阅读评估变更行为所需的相关章节。

需要留意的情况

当这些信号出现在变更路径中时，应进行调查；它们并不一定属于缺陷：

• 启动了一个没有 ctx.Done()、通道关闭或 WaitGroup 路径的 goroutine —— 它的生命周期会超出调用者。
• 在循环中使用 time.After —— 每次迭代都会分配一个计时器；请改用 time.NewTimer 和 Reset。
• 将类型化的 nil 指针作为接口返回 —— 结果满足 != nil。
• 保留 append 的结果，同时保留原始切片 —— 两者共享底层数组，可能静默地相互修改。
• 在循环体内使用 defer —— 资源会一直累积到函数退出；请将循环体提取出来。
• 缩窄整数类型转换时没有进行边界检查 —— 可能静默溢出。
• 一个错误既被记录又被返回 —— 会导致上游重复报告；只能选择其中一种。
• 构造函数返回接口，或者接口定义在其实现旁边，而不是使用者旁边。
• 测试存在未说明的共享可变状态，或并发行为没有竞态覆盖。
• 已知类型参数或具体类型时，仍使用 any。