本系列回答一个具体的问题:一个成熟的 Go 团队,日常遵循哪些工程约定? 系列不讲解语法,不转述官方文档,28 篇文章全部面向工程实践:每篇提供可直接纳入代码评审清单的条目。
每篇的结构一致:开篇给出问题陈述,主体为规则、代码示例与机制解释,结尾附一张速查清单。全系列可顺序阅读,也可按条目检索。
优先阅读建议
- 并发编程规范——多数并发缺陷源于 goroutine 退出路径设计缺失
- 防御式编程——零值语义与切片别名是高频缺陷来源
- 错误处理规范——错误处理质量直接决定日志与排障效率
- 项目布局规范——新仓库初始化阶段应先确定目录约定
第一部分:语言核心
| # | 文章 | 内容 |
|---|---|---|
| 1 | 切片、map 与泛型:内存机制与使用规范 | 切片与 map 的内存模型、边界行为及泛型的适用边界 |
| 2 | 结构体与接口:组合优于继承的 Go 实践 | 零值设计、嵌入语义、接收者选择与类型断言安全 |
| 3 | 防御式编程:规避 nil panic 与切片别名陷阱 | 零值语义、接口 nil 判定、防御性拷贝、数值边界与 panic/error 分界 |
第二部分:并发与上下文
| # | 文章 | 内容 |
|---|---|---|
| 4 | 并发编程规范:goroutine、channel 与 sync 的纪律 | goroutine 退出路径、channel 所有权与关闭、sync 原语选型与泄漏检测 |
| 5 | context 使用规范:取消、超时与请求级数据 | context 传递、取消与超时机制,消除 goroutine 泄漏与超时失效 |
第三部分:工程规范
| # | 文章 | 内容 |
|---|---|---|
| 6 | 错误处理规范:创建、包装与终结处理 | 哨兵错误、错误包装与错误链、单一处理原则、日志集中于顶层边界 |
| 7 | 命名与代码风格:写出地道的 Go | 导出规则、MixedCaps 惯例、包名与函数命名、格式化要求 |
| 8 | 项目布局规范:标准 Go 项目该长什么样 | 目录结构约定:cmd、internal、pkg 的职责边界与多模块工作区 |
| 9 | 依赖管理规范:go.mod 的正确用法 | 最小版本选择机制,依赖增删升级、replace/retract 与漏洞扫描 |
第四部分:测试与质量
| # | 文章 | 内容 |
|---|---|---|
| 10 | 单元测试规范:表驱动、覆盖率与 HTTP 测试 | 测试文件组织、表驱动与子测试、httptest 测试、集成隔离与覆盖率解读 |
| 11 | testify 实战:断言与 Mock 的正确姿势 | assert/require 断言、mock 打桩与 suite 用法,参数顺序等高频错误 |
| 12 | 静态检查规范:golangci-lint 与 nolint 的克制使用 | golangci-lint 分档配置、linter 选型与 nolint 豁免纪律 |
| 13 | 重构与现代化:安全演进你的 Go 代码 | 行为保持重构:回归保障、PR 纪律、gopls 手法、改写工具与版本升级 |
| 14 | 基准测试规范:benchstat 与性能回归防线 | b.Loop 写法、多次采样与 benchstat 显著性判定、CI 性能门禁 |
| 15 | 故障排查方法论:从 Bug 到根因的系统路径 | 复现—定位—修复—验证流程,race 检测器、pprof 与核心转储的使用 |
第五部分:服务端开发
| # | 文章 | 内容 |
|---|---|---|
| 16 | 数据库访问规范:连接、事务与扫描 | 连接池配置、参数化查询、事务隔离与错误分流 |
| 17 | gRPC 服务开发规范 | proto 兼容性约束、buf 工具链、错误码契约与截止时间传播 |
| 18 | GraphQL 与 API 文档:gqlgen 与 swag 实践 | gqlgen 与 swag 两条契约路线的选型:工作流、解析器边界与数据加载器 |
| 19 | 可观测性规范:日志、指标、追踪与告警 | 结构化日志、标签基数控制、采样策略与症状类告警 |
| 20 | 性能优化规范:CPU、内存、GC 与网络 | profile 先行定位,分配、GC、CPU、I/O 与缓存的优化规范 |
| 21 | 安全实践规范:从注入到密钥管理 | 注入防护、路径校验、密钥管理、密码学与依赖安全,附上线检查清单 |
第六部分:生态与工具链
| # | 文章 | 内容 |
|---|---|---|
| 22 | CLI 与配置管理:flag、cobra 与 viper | 命令树设计、退出码约定、标准流分离与配置绑定时机 |
| 23 | 依赖注入:手工装配与 wire/dig/fx/do | 构造函数注入与组合根原则,wire/dig/fx/do 四方案选型与测试替换 |
| 24 | 函数式工具箱:samber/lo、mo、hot 与 ro | lo 集合变换、mo 错误管道、hot 进程内缓存、ro 响应式流的选型规范 |
| 25 | Go 生态盘点:标准库、流行库与常用工具 | 依赖选型原则、标准库新包与分领域流行库速查表 |
| 26 | CI/CD 规范:测试、lint、发布与供应链安全 | 流水线阶段排序、门禁设计、发布流程、权限最小化与依赖固定 |
| 27 | 文档写作规范:注释、README 与 CHANGELOG | godoc 注释惯例、README 骨架与 CHANGELOG 分类规范 |
| 28 | 工具链与持续更新:gopls、pkg.go.dev 与版本跟进 | gopls 与 pkg.go.dev 的分工、配置管理及 Go 版本升级规范 |
使用方式
**作为评审手册:**每篇结尾的速查清单即为结论,可逐条对照评审。
**作为系统教材:**顺序阅读约需 6~8 小时,可建立对 Go 工程规范的完整认知。
**作为团队约定底稿:**汇总 28 张速查清单,裁剪不适用条目,即可形成团队规范的初稿。
系列内容基于 samber/cc-skills-golang 的 46 份技能文档重写与重组,并修正了原始材料中若干不准确的技术表述。