Go 微服务团队协作实践：代码规范、CR 流程和技术债务管理

一、5 个人的 Go 团队写了 3 个月，代码风格有 5 种

这是一个中型团队的真实状态：没有统一的代码规范，A 用errors.New、B 用fmt.Errorf、C 自己封装了一个pkg/errors。变量命名，有人偏爱单字母u，有人用user，有人用usr。错误处理，有人if err != nil { panic(err) }，有人if err != nil { return err }。

Code Review 流于形式——因为没有一个量化的标准来判断"什么是对、什么是错"。

二、团队协作的三层规范体系

三层体系的分工：第一层（自动化）解决"能被工具检查的规则"，不需要人来做；第二层（CR 标准）解决"人类判断力"的事（逻辑正确性、设计合理性）；第三层（债务管理）解决"今天不改但明天要改"的事。

三、落地的关键实践

实践一：Golangci-lint 的"渐进式"配置

不要一上来就开启所有 Linter（团队会抗拒）。分三期上线：

• 第一期（上线当天）：仅开启errcheck、govet、staticcheck、ineffassign（4 个最基础的，零假阳性）
• 第二期（一周后）：增加unused、gosimple、bodyclose
• 第三期（一个月后）：根据团队接受度，逐步增加gocyclo（复杂度 > 15）、dupl（重复代码）

# .golangci.yml（渐进式第三期配置） linters: enable: - errcheck # 检查未处理的 error - govet # Go 官方静态分析 - staticcheck # 高级静态分析 - ineffassign # 无效赋值 - unused # 未使用的变量/函数 - bodyclose # HTTP body 未关闭 - gocyclo # 圈复杂度检查 disable: # 暂不开启（等团队成熟后） - gocritic # 太严格，等三个月后再说 - funlen # 函数长度限制（不强制约定） linters-settings: gocyclo: min-complexity: 15 # 复杂度超过15的标记 errcheck: check-blank: true # 检查 _ 忽略的 error

实践二：Code Review 检查清单

## CR 6 项必查清单（每次 PR 审查时逐项确认） 1. [ ] 错误处理：每个 err 是否被处理或明确忽略(有注释)？ 2. [ ] 并发安全：共享数据是否被正确保护（mutex/channel/atomic）？ 3. [ ] 资源释放：defer 是否正确（文件/HTTP Body/DB连接）？ 4. [ ] 输入校验：对外部输入（用户请求/API参数）是否做了校验？ 5. [ ] 日志适当：关键路径是否有日志？敏感信息是否脱敏？ 6. [ ] 测试覆盖：核心逻辑是否有单元测试？边界是否有用例？

实践三：技术债务的可视化

在代码中标记技术债务的方式：

// ✅ 好的债务标记 // TODO(#TECHDEBT-1234): 当前查询是全表扫描，需要加索引 // 预计影响：日均10万次查询中约有3%出现慢查询（>200ms） // 解决方案：为 user_id + status 建联合索引 // ❌ 差的债务标记 // TODO: 优化这里 // FIXME: 有时候会慢

关键区别：好的标记包含工单号（可追踪）、影响范围量化、和修复建议。有了工单号，就能在 Jira Board 上跟踪技术债务的偿还进度。

四、执行过程中遇到的阻力与应对

阻力一："Lint 规则太多，写个代码改半天"。应对：Lint 规则分阶段上线，每次上线新规则时开一次"Lint 讲解会"，用 10 分钟解释"为什么这条规则重要"。比如解释bodyclose——"不关 HTTP Body 会导致连接池耗尽，线上出过两次 P1 故障。这条规则不是限制你，是保护你。"

阻力二："CR 太慢，PR 挂了两天没人看"。应对：约定 CR SLA——小于 100 行的 PR 必须在 4 工作小时内 Review，大于 500 行的 PR 鼓励拆小。同时在每日站会上报"挂了超过 24h 的 PR"名单，给团队一点进度压力。

阻力三："技术债务越堆越多"。应对：每个 Sprint 强制分配 20% 的容量给技术债务偿还。由 Tech Lead 在 Sprint Planning 时从债务池中挑选优先级最高的 1-2 项，把它们当作正式需求来排期。

五、总结

Go 微服务团队的协作规范需要分三个层次：自动化（Lint/Format/Test）、人审（CR 检查清单）、债务管理（可视化追踪）。关键是"渐进式推进"——不要一次上线 20 条 Lint 规则，团队会反弹。先上 4 条零争议的，大家习惯了再逐步加。CR 检查清单不是用来"卡人"的，是用来"对齐标准"的——当一个新人不知道自己的代码对不对时，这 6 项检查就是参考答案。技术债务的标记必须有工单号，否则就只是一个永远不会被执行的 TODO 注释。