1. Go项目结构概述：为什么需要标准项目结构、常见Go项目布局模式、接口契约在项目中的角色
1.1 为什么需要标准项目结构
Go 语言在诞生之初并未强制规定项目目录布局，社区早期项目结构五花八门。随着微服务、云原生和大型团队协作的普及，标准项目结构成为工程化落地的第一道门槛。缺乏统一结构会带来以下问题：
| 问题 | 典型表现 | 后果 |
|---|---|---|
| 包循环依赖 | internal 与 pkg 混用，A 包引用 B 包，B 包又反向引用 A 包 | 编译失败，重构成本剧增 |
| 职责边界模糊 | 业务逻辑、数据库操作、HTTP 处理混在同一个包内 | 难以测试、难以复用、难以替换实现 |
| 新人上手成本高 | 每个项目目录风格不同，需要重新理解代码组织 | 团队效率下降，代码审查困难 |
| 接口与实现耦合 | 接口定义在实现包中，导致消费者必须依赖具体实现 | 违反依赖倒置原则，无法进行 mock 测试 |
核心原则：标准项目结构不是“银弹”，而是团队协作的最小公约数。它让代码可读、可测、可替换，是接口契约设计能够落地的物理基础。
1.2 常见Go项目布局模式
Go 社区经过多年实践，形成了三种主流布局模式。每种模式适用于不同的项目规模和团队结构：
- 扁平布局（Flat Layout） —— 适用于小型工具、CLI 或单文件服务。所有代码放在根目录，包数量不超过 3~5 个。
- 分层布局（Layered Layout） —— 适用于标准 Web 服务。按技术职责分层：handler / service / repository / model。
- 模块化布局（Modular Layout） —— 适用于中大型微服务或领域驱动设计（DDD）。按业务领域拆分为独立模块，每个模块内部再分层。
以下表格对比三种模式的关键差异：
| 维度 | 扁平布局 | 分层布局 | 模块化布局 |
|---|---|---|---|
| 包数量 | ≤5 | 5~15 | 15+ |
| 团队规模 | 1~2 人 | 3~8 人 | 8 人以上 |
| 接口契约位置 | 定义在使用处 | 定义在 service 层 | 定义在独立 contract 包 |
| 典型目录 | main.go, util.go |
handler/, service/, repository/ |
order/, payment/, contract/ |
| 适用场景 | CLI 工具、快速原型 | 标准 CRUD 服务 | 微服务、DDD 项目 |
推荐：本课程后续章节均以模块化布局为基线展开。模块化布局天然支持接口契约的独立定义与版本管理，是大型 Go 项目的最佳实践。
1.3 接口契约在项目中的角色
接口契约（Interface Contract）是 Go 语言中 interface 类型在项目结构层面的系统化运用。它不仅仅是语法层面的抽象，更是架构层面的边界定义。
接口契约在项目结构中承担三个核心角色：
- 依赖倒置的支点 —— 高层模块（业务逻辑）依赖接口，低层模块（数据库、外部 API）实现接口。项目结构中的
contract/或port/目录就是支点的物理位置。 - 模块间通信的协议 —— 不同模块（如 order 模块与 payment 模块）之间通过接口契约交互，而非直接调用具体类型。契约定义在独立的共享包中，避免循环依赖。
- 测试替身的生成边界 —— 接口契约明确划出了“可 mock 的边界”。在单元测试中，只需 mock 接口，无需启动真实依赖（数据库、RPC 服务）。
下图展示了接口契约在模块化布局中的核心位置：
1.4 接口契约的物理位置约定
在模块化布局中，接口契约的存放位置有明确的社区约定。以下是最常见的两种模式：
| 模式 | 目录路径 | 适用场景 | 优点 | 缺点 |
|---|---|---|---|---|
| 独立 contract 包 | internal/contract/ |
多模块间共享接口 | 接口集中管理，版本清晰 | 需要额外维护 contract 包 |
| 消费者侧定义 | 接口定义在使用它的模块内 | 单模块或小型项目 | 减少间接层，快速迭代 | 接口分散，难以复用 |
避坑提示：不要将接口定义在实现包中（如
repository/mysql/repository.go 中定义接口）。这会导致消费者必须 import 具体实现包，破坏依赖倒置原则。接口契约应该定义在消费者或独立的 contract 包中。
1.5 接口契约与项目结构的演进关系
项目结构不是一成不变的。随着业务复杂度增长，接口契约的角色也会随之演进：
- 阶段一（原型期）：扁平布局，接口定义在使用处，甚至不使用接口。快速验证业务可行性。
- 阶段二（成长期）：分层布局，接口定义在 service 层。开始出现 mock 测试，接口契约初步形成。
- 阶段三（成熟期）：模块化布局，接口契约独立为 contract 包。支持多实现切换、多版本共存、领域事件驱动。
下图展示了这种演进路径：
1.6 本章小结
- 标准项目结构解决循环依赖、职责模糊、新人上手慢等工程问题，是接口契约落地的物理基础。
- 三种主流布局（扁平、分层、模块化）各有适用场景，本课程以模块化布局为基线。
- 接口契约在项目中扮演依赖倒置支点、模块通信协议、测试替身边界三个核心角色。
- 接口契约应定义在消费者侧或独立 contract 包中，绝不能定义在实现包中。
- 项目结构随业务演进，接口契约的独立程度也应随之提升。