关于 go-best-practices
面向 Go 开发者的实践指南，涵盖程序结构、并发、配置、测试、日志和静态检查，并提供规则及代码示例参考。
主要功能
- 01精简 main 与统一初始化
- 02有序关闭与非阻塞分发
- 03确定性并发及泄漏测试
- 04分层配置与平台路径
- 05调试日志中的密钥脱敏
- 06黄金测试与精简检查器
适用场景
- 01规划新的 Go 二进制程序
- 02管理长期运行服务的关闭流程
- 03测试 goroutine 与通道行为
- 04确定多来源配置优先级
安装
复制下面的命令，在终端中运行。
npx skills add https:/安装后在 Claude Code 中输入/go-best-practices确认已加载。
附带文件references/patterns.md
详细介绍
Go 最佳实践
| 模式 | 适用场景 |
|---|---|
| 精简的 main | 新二进制程序 |
| 单一引导流程 | 跨运行模式的应用接线 |
| 有序关闭 | 长时间运行的进程 |
| 非阻塞扇出 | 基于通道的事件系统 |
| 并发测试 | 任何使用 goroutine 的代码 |
| 分层配置 | 多来源配置 |
| 跨平台路径 | 文件／配置路径解析 |
| 安全的调试日志 | HTTP 客户端插桩 |
| Golden 测试矩阵 | 渲染／输出组件 |
| 精简的 linter | CI 流水线设置 |
请参阅 references/patterns.md 获取代码示例。
规则
-
main.go 是一个存根。 只调用
cmd.Execute()，不做其他事。通过环境变量控制是否启用诊断功能（pprof）。 -
使用单一引导流程。 所有模式（交互式、无头、测试）共用同一个初始化函数。两条路径会逐渐偏离。
-
有序关闭。 先取消依赖项，再取消其依赖对象，然后在超时上下文中并行执行独立的清理任务。并行阶段使用 WaitGroup 等待完成。
-
绝不阻塞发送方。 使用非阻塞通道发送，并明确丢弃策略。在 debug 级别记录丢弃情况，并说明该策略。
-
以机械化方式测试并发。 使用
testing/synctest实现确定性计时，使用goleak.VerifyNone检测泄漏，并针对计时器／通道死锁编写专门的回归测试。 -
明确配置优先级。 全局配置 → 项目配置 → 标志。向上遍历 CWD 以发现项目配置，反转顺序以确保最近的配置优先，并进行深度合并。
-
集中管理平台路径。 每种用途使用一个函数。解析顺序：环境变量覆盖 → XDG → 平台默认值 → 回退值。
-
在调试日志中脱敏机密信息。 包装
http.RoundTripper。过滤名称匹配 authorization、api-key、token、secret 的标头。在 debug 级别控制是否启用，以便在生产环境中跳过内存分配。 -
使用覆盖矩阵的 Golden 测试。 将多个维度（布局 × 主题 × 尺寸）组合为并行子测试。遍历连续范围以捕获差一错误。
-
使用精简的 linter，而非全部 linter。 启用能捕获实际错误的检查项（bodyclose、noctx、tparallel）。禁用噪声较大的默认项。通过脚本添加项目专用检查。测试时始终使用
-race。