Go Modules应禁用vendor，统一启用GO111MODULE=on；go.mod须提交且不改//indirect行；接口定义下沉至独立api模块；日志trace ID须透传并绑定context。
用 Go Modules 管理依赖，别碰 vendor 目录手动同步
跨团队协作时，依赖不一致是最常见的构建失败源头。Go 1.11+ 默认启用 go mod，但很多团队仍保留 vendor 并定期 go mod vendor —— 这反而放大了冲突风险：不同团队提交的 vendor/ 可能含不同版本的同一包，git merge 时极易出错。
实操建议：
- 所有
go.mod文件必须提交，且禁止修改// indirect注释行（它由go mod tidy自动维护） - CI 流水线统一执行
go mod download+go mod verify，验证校验和一致性 - 禁用
GO111MODULE=off，在团队开发机和 CI 中设为环境变量GO111MODULE=on - 若必须锁定间接依赖（如安全审计要求），用
go mod edit -require=example.com/pkg@v1.2.3显式写入，而非靠vendor
统一 go fmt 和 go vet 检查，但别用 gofmt -w 自动改代码
格式不一致会引发无意义的 diff，尤其当多个团队共用一个 repo 时。但强制自动重排可能破坏团队原有风格习惯（比如注释对齐、空行逻辑），反而增加 code review 成本。
推荐做法：
立即学习“go语言免费学习笔记（深入）”；
- 在
.git/hooks/pre-commit或 CI 中运行gofmt -l -s（只列出不合规文件）和go vet ./...，失败即阻断提交 - 用
golines替代默认gofmt处理长行（golines -w .），它更尊重语义换行，避免把一行 if 条件硬拆成三行 - 团队共享一份
.golangci.yml，启用govet、errcheck、staticcheck，但禁用主观风格类 linter（如stylecheck的命名建议）
接口定义下沉到独立 api 模块，避免跨服务直接 import internal
常见错误：A 团队的服务代码里直接 import "github.com/org/project/internal/handler"，B 团队想复用逻辑就 copy-paste，结果 A 升级后 B 的服务静默 panic。
解法是物理隔离契约与实现：
- 新建
github.com/org/project/api仓库（或单仓内api/目录），只放.proto、OpenAPI spec、Go interface 定义（如type UserService interface { GetUser(ctx context.Context, id int) (*User, error) }） - 各服务通过
go get github.com/org/project/api@v1.2.0拉取固定版本，禁止replace指向本地路径 -
internal/下所有实现层代码禁止 export，确保外部只能通过api模块交互
日志和 trace ID 必须透传，别让 context.WithValue 成为黑盒
跨团队调用链中，日志分散在不同服务，trace ID 不一致会导致排查时来回切日志平台。而滥用 context.WithValue 传参（比如塞 map 或 struct）会让上下文膨胀且类型不安全。
关键约束：
- 所有 HTTP/gRPC 入口必须从 header 提取
X-Request-ID或traceparent，并注入context.Context；出站请求必须透传该值 - 自定义 context key 必须是未导出的私有类型（
type ctxKey string; const logIDKey ctxKey = "log_id"），杜绝字符串字面量误用 - 日志库统一用
zerolog或zap，初始化时绑定ctx.Value(logIDKey)为全局字段，避免每个函数都手动log.With().Str("req_id", ...)
真正难的是 trace 上下文在异步任务（如消息队列消费）中的延续——这需要序列化 context 中的 span 和 log ID 到消息 payload，消费端再反序列化重建，容易遗漏。别指望中间件自动处理，得在业务代码显式做。
