Go 惯用法指南

解决的问题

Go 代码常见分歧不是语法，而是约定：错误如何包装、日志在哪个层处理、接口应定义在使用方还是实现方、goroutine 与 channel 是否形成可取消、可关闭、可等待的协作结构。对中小模块来说，这些细节会让调用方难以判断错误语义，也会让测试和重构成本上升。

技能如何工作

该技能提供一组 Go 惯用法规则，可用作代码审查提示、生成约束或工程规范：

• 错误处理：用 fmt.Errorf("context: %w", err) 增加上下文，并用 %w 保留 errors.Is / errors.As 可判定性；对预期条件使用 sentinel errors；同一错误不要既打日志又继续返回。
• 接口设计：优先在 consumer side 定义接口，倾向小而可组合的接口；复用 io.Reader、io.Writer、fmt.Stringer；单方法接口按方法名加 er 后缀命名。
• 并发模式：围绕 worker pool、channel 方向等模式约束 goroutine 与 channel 的使用，例如 jobs <-chan Job 这类输入通道语义。

适用边界

适合 Go 服务、CLI、内部框架等在 review 或代码生成阶段需要统一风格的项目。它不替代项目架构决策；对于已有历史错误码、业务接口或遗留并发模型，应结合团队规范裁剪，避免把通用惯用法直接套到性能敏感路径。