4.3 代码组织与项目结构

4.3 代码组织与项目结构

本节摘要：项目结构决定半年后的维护成本。本节讲 Go 社区沉淀的布局惯例——命令入口、internal 私有边界、pkg 可复用库的争议、按业务域分层的取舍，包设计的内聚原则，vendor 与依赖策略，以及测试文件与源码同放的约定。读完你能为一个中型服务画出合理的目录树，并知道每一层为什么存在。

你能学到什么

阅读完本节，你应当能够：

1. 画出中小型服务的推荐目录结构并解释各层职责；
2. 用 internal 建立编译器强制的私有边界；
3. 按"高内聚低耦合"划分包，避免工具包垃圾场；
4. 制定依赖与 vendor 策略；
5. 组织测试文件与子测试目录；
6. 判断项目何时需要演进结构而不是重构。

一、为什么结构重要

代码的组织方式有三种成本：找东西的成本（这个逻辑在哪）、改东西的成本（改这里会波及哪）、信心的成本（我能不能只测这一块）。结构好的项目三项都低。Go 官方刻意不提供强制布局——语言只给"包"这个单元，布局是社区惯例与团队约定的产物，这既是自由也是陷阱：没有惯例的团队会长出"utils 大黑洞"。

二、推荐布局：一张主流共识的树

myapp/
  go.mod
  main.go            或 cmd/ 下多个入口
  internal/
    handler/          HTTP入口层
    service/          业务逻辑层
    repo/             数据访问层
    config/           配置加载
  pkg/               可被外部复用的通用库（有争议）
  api/               接口定义：协议与契约文件
  web/ 或 static/     前端静态资源
  scripts/           构建、部署、数据库迁移等运维脚本
  test/              端到端与集成测试
​

逐层说职责。cmd 目录放多个 main 入口：同一代码库要产出服务端、命令行工具、迁移任务等多个二进制时，每个入口一个小目录，里面只有薄薄的启动胶水。internal 是 Go 的杀手锏——其下包只允许父目录树内导入，外部模块想 import 也编译不过，等于免费的访问控制。pkg 名字暗示"公开可复用"，但社区对它有争议：只有真会被别的模块导入的代码才值得放，为放而放只是多一层无意义嵌套。

api 目录放协议定义（接口描述、数据契约），它是对外承诺，变更要走评审。scripts 放让新人一天跑通环境的所有脚本——环境搭建脚本化是结构的一部分。

三、分层：依赖只能向下

经典三层：handler（解析请求、校验、组装响应）→ service（业务规则、事务边界）→ repo（数据库与外部调用）。依赖箭头单向向下，下层不知道上层的存在。判断标准很硬：repo 包的 import 列表里出现 HTTP 框架的名字，就是越层。

⚠️ 常见坑：把结构当教条。小工具一个 main 加两三个文件足够，硬套四层目录是官僚主义。结构的复杂度应该跟着"人数乘以代码量"走，不是跟着简历走。

四、包设计三原则

按变化聚包：会一起修改的东西放一个包。订单的校验、状态机、金额计算都在 order 包里，而不是散在 validator、statemachine、money 三个"功能包"——后者每次改需求要跨三个包。

拒绝垃圾场：utils、common、helper 这类包没有主题，只会单向变胖。一个函数找不到家，说明缺的是一个有名字的概念，不是缺一个垃圾抽屉。

接口放消费者侧：第 3 章讲过隐式实现，推论是"service 需要 repo 什么样，接口写在 service 包里"，而不是 repo 包里写个大而全的接口再让 service 依赖它——依赖倒置在 Go 的成本极低，用就是了。

五、依赖与 vendor 策略

延续第 4.1 节：go.mod 与 go.sum 必入库；CI 走模块缓存加速；需要供应链强管控或气隙环境时启用 vendor。团队规约建议写明：引入新依赖要过评审（一个 HTTP 框架值不值得三十个间接依赖）、能用标准库不引第三方、升级用 go get 显式操作并跑全量测试。

六、测试的组织

Go 的约定是测试文件与被测源码同目录同名加 _test 后缀，这一条约定消灭了"测试放哪"的会议。集成测试与端到端测试放顶层 test 目录或用构建标签区分；测试辅助函数以 exported 与否控制复用范围。详细实践（表格驱动、基准、mock）见第 6 章测试专节。

七、结构的演进

结构不是一次画对的，是跟着痛点长的：第二个人的加入、第一个外部使用者、第一次拆微服务，都是演进信号。原则是" Pain 驱动"——只有当当前的痛（改一处波及五处、测试慢得没人跑）真实出现，才引入新的目录或层。每次演进保持 import 单向，internal 边界干净，就永远不会烂到不可收拾。

💡 关键直觉：项目结构像城市分区——住宅、商业、工业各有其位，货流（依赖）单向行驶；最怕的是"什么都卖一点"的杂货铺街区，也就是 utils 包。

八、目录布局一览图

演进问答。什么时候拆库？ 当两个团队发布节奏互相拖累时，先拆模块边界再谈拆仓。internal 太深怎么办？ 那是功能域在求独立——提升为顶层 internal 子树，保持单向依赖即可。脚手架工具值得用吗？ 值得，但先用一遍"手搓最小结构"理解每层职责，再用工具省键盘。

核心回顾

• cmd 多入口、internal 强私、pkg 谨慎用：布局三支柱。
• internal 是编译器保证的边界，外部导入直接失败。
• 三层单向依赖：handler → service → repo，下层不识上层。
• 按变化聚包，拒绝 utils 垃圾场。
• 接口放消费者侧，隐式实现让依赖倒置零成本。
• 测试同目录约定，集成测试独立目录或构建标签。
• 演进由痛点驱动，别为结构而结构。

下一章进入 Go 的主场：并发编程。