Go 工具链
强制要求
TypeScript 与 Python 是 AI 辅助开发的默认语言。Go 不是默认选项,仅当项目确实需要以下能力时才选择 Go:
- 对性能敏感的网络服务
- 以独立二进制文件分发的命令行工具
- 单个静态二进制文件的部署目标
- 高并发工作负载
采用 Go 必须给出明确理由、征得用户同意,并在项目 ADR 中记录这些内容。
熟悉 Go 本身不构成采用理由。
适用范围
本文档是 Go 项目的基线标准,不能替代项目级评估。采用 Go 前须确认两点:需求属于上述场景之一,且 TypeScript 或 Python 无法以合理成本满足。
版本策略
使用 mise 管理最新稳定版 Go。
go.mod 中的 toolchain 指令必须与 mise 管理的 Go 版本一致。
除非记录了理由,否则不要锁定旧版 Go。
使用规则
Lint 工具
使用 golangci-lint 作为 Lint 工具。
通过 mise task 提供该工具,确保本地开发和 CI 使用同一份配置。
将配置作为 .golangci.yml 提交到仓库,并根据项目重点调整。不要使用 enable-all:它会启用耗时较长、带有主观风格偏好的检查,使重要问题更难发现。
始终启用的基线规则:
govet——可疑构造检查,大致对应go vet的检查项staticcheck——正确性、简化与风格检查,包括错误消息风格检查(ST1005):错误消息以小写开头,结尾不带标点unused——未使用的常量、变量、函数与类型ineffassign——无效赋值misspell——常见英文拼写错误
在基线之上,根据项目特点增加重点检查组:
- 大量使用 context 的服务:
contextcheck、containedctx、fatcontext、noctx - 以错误处理为重点的项目:在
errcheck基础上增加errorlint与wrapcheck
格式化
使用 gofumpt 作为格式化工具。
将格式检查加入 pre-commit 配置和 CI。
错误处理
添加上下文时,用 %w 包装错误:
return fmt.Errorf("loading config: %w", err)
用 errors.Is 和 errors.As 判断包装后的错误。
不要通过比较错误消息字符串来检查错误。
Context
对于会阻塞或具有请求作用域的函数,必须将 context.Context 作为第一个参数传入。
传递调用方的 context;不要在库代码中创建新的 context.Background 值。
并发
明确每个 goroutine 的归属:每个 goroutine 只能有一个生命周期负责人。
通过 context 显式传递取消信号。
不要泄漏 goroutine。
测试
使用表驱动测试覆盖多组输入下的行为。
CI 中运行 go test -race。
通过 .golangci.yml 中的按路径排除规则,为 _test.go 文件放宽 Lint 要求。测试优先保证可读性和意图清晰,不必遵循生产代码的 Lint 严格度;测试中关闭错误包装和重复代码风格检查:
version: "2"
linters:
exclusions:
rules:
- path: _test\.go
linters:
- wrapcheck
- errorlint
- dupl
panic
库代码中不要使用 panic,改为返回错误。
仅在 cmd/ 入口的启动错误不可恢复时使用 panic。
目录结构
Go 没有官方标准的项目布局。golang-standards/project-layout 仓库是社区参考而非官方标准;官方的 "Organizing a Go module" 指南也是从把基础包放在模块根目录讲起。
- 小型库可以保持根目录扁平:只需
go.mod和包文件。 - 复杂服务应按业务分层设计自己的结构,而不是照搬模板。
cmd/(每个二进制一个入口)与 internal/(由编译器强制限制导入)仍是有用的惯例。只有在它们符合项目设计时才采用,不要把它们当成模板要求。
联动
- mise——版本管理:Go 和 golangci-lint 由 mise 管理,并通过 mise task 提供。
- Go API 技术栈——HTTP 服务使用的 Web 框架和校验技术栈。
- 质量门禁——同一套检查:prek 与 CI 运行相同的 Lint 与格式化配置。
- Git 工作流——提交纪律:Go 变更遵循标准的提交和 pull request 规则。
- 测试策略——测试重点:测什么,在哪一层测。
不采用的替代方案
不要将单独的 gofmt 或 goimports 作为项目的格式化工具。
gofumpt 是 gofmt 的严格超集;导入排序由 gofumpt 配合 golangci-lint 的 gci 或 goimports 规则完成。