go-style-guide

Go（Golang）风格指南 Skill

此 Skill 定义了适用于人类、编码 Agent 和生产就绪系统的实用 Go 工程规范。

无论何时处理 Go 工作，都应使用此 Skill：编写新代码、重构、审查、架构决策、包设计或测试策略。

---

TL;DR

• 优先考虑可测试性进行设计；注入依赖，并尽量让逻辑保持纯粹。
• 优先采用 Config 输入、具体结构体输出的模式；验证并设置默认值，同时记录重要的运行时配置项。
• 错误就是契约：使用哨兵错误支持稳定的分支判断；其他错误使用 %w 或 errors.Join 包装。
• 保持包可复用：不使用隐藏的全局变量、默认日志记录或意外的副作用。
• 添加依赖前优先考虑标准库；第三方包必须凭借有意义、维护良好且被广泛采用的抽象体现其价值。
• 覆盖率是参考指标，不是证明；应测试边界情况和误用场景，而不只是正常路径。
• 遵循“接受接口，返回结构体”；通常由使用方定义接口，共享契约包属于特殊情况。
• 保持 main.go 精简；遵循仓库现有的布局约定，不要强行采用某种目录结构。
• 在宣称性能提升前，先对热点路径进行基准测试；并发代码应使用 -race 运行。
• 维护函数签名、配置结构、错误行为和文档注释等契约；它们与代码本身同样重要。

---

风格指南免责声明

本指南有意采用鲜明立场。它优先考虑一致性和长期可维护性，而不是迁就 Go 风格上的所有偏好。如果目标仓库已有明确的本地约定，通常应以这些约定为准。

---

兼容性

示例以现代 Go 为前提，并使用 errors.Join 和 log/slog 等标准库功能。请在目标仓库支持的 Go 版本限制内应用本指南。

---

执行流程

使用此 Skill 实施工作时，请遵循以下工作流：

1. 先检查仓库。 在提出新 API 或移动文件之前，先了解现有的包布局、构造函数、测试和错误约定。

2. 编码前定义契约。 预先确定包边界、配置结构、具体返回类型、哨兵错误、依赖接缝，以及对上下文或关闭行为的预期。

3. 可行时尽早编写或更新测试。 从表驱动单元测试开始；对解析或其他输入密集型代码添加模糊测试；对性能敏感的路径添加基准测试。

4. 实施最小且可维护的改动。 遵循仓库现有布局，保持 main.go 精简，并避免引入缺乏明确边界的新抽象。

5. 完成收尾检查。 使用 gofmt 格式化（如果仓库使用 goimports，也应运行它），运行相关的 go test 目标；涉及并发时运行 go test -race；宣称性能提升时运行基准测试。

6. 核实面向使用者的契约。 确保文档、注释、配置默认值和错误行为与交付的代码一致。

---

快速规则表

主题	规则	参考
可测试性	以建立信心为目标，而非追求覆盖率百分比；测试边界情况和误用情况	references/TESTING.md
构造函数	输入 Config，返回具体结构体；在 New 中验证并设置默认值；配置逻辑变复杂时使用 Config.Validate()	references/CONFIG.md
错误	使用哨兵错误进行稳定分支判断；使用 %w 或 errors.Join 包装；将 recover 保留在应用边界	references/ERRORS.md
日志记录	默认情况下，包不记录日志；热点路径上的日志记录是性能决策	references/LOGGING.md
依赖项	优先使用标准库；仅在第三方包能带来有意义且持续维护的价值时才添加	references/LAYOUT.md
接口	“接受接口，返回结构体”；通常由使用方定义接口	references/INTERFACES.md
文档	编写符合 Go 惯例的 godoc 和长期有效的注释；绝不添加面向 Agent 上下文的注释	references/DOCUMENTATION.md
布局	保持包结构浅显，避免杂物箱式包，并遵循代码库惯例	references/LAYOUT.md
入口点	main.go 只负责组装依赖	references/LAYOUT.md
基准测试	对热点路径进行基准测试；使用 b.ReportAllocs()，并用 benchstat 比较运行结果	references/BENCHMARKS.md
测试	使用表驱动测试、优先使用标准库、防范误用；输入复杂时大量使用模糊测试	references/TESTING.md
并发	每个 goroutine 都需要关闭路径；根据需要使用 context.Context、-race 和抖动	references/CONCURRENCY.md
评审	评审 Go 代码变更时使用检查清单	references/REVIEW-CHECKLIST.md

---

常见陷阱

• 默认返回接口，而不是具体类型。
• 将覆盖率百分比视为正确性的证明。
• 在可复用包中记录日志，而不是返回错误。
• 标准库已经足够清晰时，仍然添加框架或辅助库。
• 在各个包之间传递全局应用配置，而不是使用本地 Config。
• 将关键运行时选项留在危险的默认值上。
• 将固定的目录布局强加给已经有清晰惯例的代码库。
• 尚未确定任务涉及哪个主题，就加载所有参考文档。
• 在没有基准测试的情况下声称性能提升，或在没有 -race 的情况下声称并发安全。

---

核心指导

只有在任务需要相关主题的详细信息时，才加载参考文件。

• 应用包负责依赖组装、生命周期、错误策略、日志记录策略和指标策略。
• 可复用包应返回错误，定义本地 Config 或 Opts，接受已初始化的依赖项，并避免隐藏式日志记录或全局状态。
• 依赖项选择应从标准库开始。只有在第三方包能解决实际问题、得到积极维护且其传递依赖成本合理时，才考虑使用。
• 服务通常应让 cmd/<appname>/main.go 保持精简。遵循已有的代码库布局，不要强行采用 pkg/、internal/ 或任何固定结构。
• 库通常应保持包结构浅显，并聚焦于特定领域。
• 构造函数优先采用 New(cfg Config) (*T, error)，显式设置默认值、进行验证、返回具体类型，并使用不可变的规范化配置。
• 接口应当小巧、围绕边界设计，并通常由使用方定义。
• 测试应采用表驱动方式、优先使用标准库、防范误用；对并发敏感的代码应使用 -race 运行。
• 性能声明需要基准测试作为依据。
• 文档、注释、配置默认值、错误行为和函数签名都是契约的一部分。

---

参考资料加载

仅加载当前任务所需的参考资料：

• 若涉及构造函数、Config 结构体、默认值、验证、降级模式或日志注入，请阅读 references/CONFIG.md。
• 若涉及接口边界、驱动模式、模拟对象/伪对象或具体返回值的选择，请阅读 references/INTERFACES.md。
• 若涉及哨兵错误、错误包装、类型化错误、recover 的放置位置或构造函数失败，请阅读 references/ERRORS.md。
• 若涉及包日志、slog、日志级别、异步错误表面或载荷安全，请阅读 references/LOGGING.md。
• 若涉及表驱动测试、模糊测试、testdata、集成门禁、测试辅助工具或断言选择，请阅读 references/TESTING.md。
• 若涉及 goroutine、上下文传播、优雅关闭、互斥锁/原子操作/通道的选择、抖动或竞态测试，请阅读 references/CONCURRENCY.md。
• 若涉及包布局、文件命名、main.go、依赖管理、结构体字段布局或导出规则，请阅读 references/LAYOUT.md。
• 若涉及包文档、godoc、示例、弃用、内部注释或字段文档，请阅读 references/DOCUMENTATION.md。
• 若涉及基准测试结构、分配报告、并发基准测试、IO 基准测试或 benchstat，请阅读 references/BENCHMARKS.md。
• 若要审查 Go PR 或进行最终自检，请阅读 references/REVIEW-CHECKLIST.md。