必须锁死Go版本于.go-version文件，统一用1.21.6；工具链通过tools.go声明并go install ./tools安装；import由goimports严格分组（标准库→第三方→本地包）；golangci-lint配置提交为.golangci.yml且禁用非共识规则。

go version 必须锁死在 .go-version 文件里

不锁 Go 版本，团队里有人用 go1.21.6，有人还在跑 go1.22.4，go mod tidy 解出来的依赖树就可能不同，go vet 对未使用变量的判定边界也会变——这不是“环境差异”，是构建不可重复的硬伤。

所有项目根目录必须有 .go-version 文件，内容只有一行：1.21.6（按团队共识定）。

• 开发者本地用 asdf 或 goenv 自动读取该文件切换版本，不依赖系统 PATH 里的全局 go
• CI 流程（如 GitHub Actions）必须显式传 go-version-file: '.go-version'，禁止写死 1.22 这类模糊值
• 验证方式：运行 go version，输出应为 go version go1.21.6 linux/amd64（或对应平台）

工具链必须通过 tools.go 声明并 go install ./tools

直接 go install golangci-lint@latest 看似省事，实则让每个人装的版本、CI 装的版本、甚至同一个人今天和明天装的版本都可能不一致。更麻烦的是，.golangci.yml 里配了 revive 的命名检查，但实际跑的是旧版 binary，规则压根没生效。

正确做法是在项目根目录建 tools.go，内容仅含：

立即学习“go语言免费学习笔记（深入）”；

Golang Uber Dig

使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等

下载

package tools

import (
	_ "golang.org/x/tools/cmd/goimports"
	_ "honnef.co/go/tools/cmd/staticcheck"
	_ "github.com/golangci/golangci-lint/cmd/golangci-lint"
)

之后统一执行：go install ./tools —— 这会精准安装 go.mod 里声明的版本，且带 //go:build tools 标签，不影响主程序构建。

import 分组和格式必须由 goimports 控制

手写 import 并手动排序，不出三天就会乱。标准库、第三方包、本地包三者顺序错位、混在一起，goimports 一跑全崩，还容易误删关键依赖。

• 必须禁用编辑器自带的 import 排序插件，只信任 goimports
• 分组逻辑固定为：标准库 → 第三方包（域名开头）→ 本地包（当前模块路径开头），组间空一行
• 禁止用相对路径导入，比如 "../net"；必须写完整模块路径，如 "yourcompany.com/project/net"
• 包名冲突时用别名，别名遵循小驼峰，如 nettrace "golang.net/x/trace"

golangci-lint 配置必须提交为 .golangci.yml 且禁用非共识规则

配置文件不提交、或只在 CI 里硬编码，等于没配。本地没跑 lint，等 PR 提交后 CI 报错才改，问题已经扩散到代码评审环节，修复成本翻倍。

.golangci.yml 必须进 Git，并满足：

• 禁用 golint（已废弃，且与 revive 冲突）
• 启用 revive 的命名检查（如 exported-name、var-naming）
• 关闭所有未被团队明确讨论并同意的规则，比如 error-naming 或 deep-copy，避免“为 lint 而 lint”
• 配合 pre-commit + Makefile，把 make lint 和 make fmt 绑定到提交前钩子，不通过就阻断提交

真正难的不是写规范，而是让每条规则在每个开发者的机器上行为一致——版本锁死、工具声明、配置落地、执行自动化，四者缺一不可。漏掉任意一环，规范就只剩文档价值。