学习目标
- 理解 Go 项目结构设计的核心原则
- 掌握常见的 Go 项目目录布局方案
- 学会合理划分 package 边界
- 避免循环依赖，设计可演进的工程结构
一、为什么项目结构如此重要
在 Go 项目中，结构问题往往不会立刻暴露，但会在项目变大后集中爆发：
- 依赖关系混乱
- 循环 import 无法拆解
- 代码“能用但不敢改”
工程认知：
项目结构不是“整理文件夹”，而是对系统边界的明确表达。
二、Go 官方的态度
Go 官方并没有强制的项目结构规范，但给出了几个重要信号：
- package 是 Go 的核心组织单元
- 目录结构应服务于 package 设计
- 避免过度抽象和“Java 化分层”
工程结论：先设计 package，再考虑目录。
三、最小可行项目结构（单模块）
适合：
- 小型工具
- 单一服务
myapp/
├── go.mod
├── main.go
├── config.go
├── handler.go
└── service.go
特点：
- 全部在一个 package（main 或 app）
- 简单直接
工程建议：项目初期，结构越简单越好。
四、常见的标准项目结构（推荐）
myapp/
├── cmd/
│ └── myapp/
│ └── main.go
├── internal/
│ ├── config/
│ ├── service/
│ └── repository/
├── pkg/
│ └── client/
├── go.mod
各目录含义：
- cmd/：程序入口（可有多个二进制）
- internal/：仅供本项目使用的代码
- pkg/：可被外部项目复用的库
工程意义：
- 清晰的边界
- 防止内部实现被误用
五、internal 的真实价值
internal 是 Go 提供的语言级访问控制机制。
规则：
- internal 下的 package
- 只能被同一模块内的代码 import
工程结论：
internal 不是“私有代码垃圾桶”，而是边界声明。
六、如何划分 package 边界
package 划分的核心问题不是“放哪”，而是：
- 谁依赖谁
- 谁对谁负责
推荐原则：
- 一个 package 只负责一个领域概念
- 避免“utils 大杂烩”
- 通过接口解耦，而不是层级拆分
反例：
utils/
├── string.go
├── time.go
├── file.go
说明：
- 概念混乱
- 依赖不可控
七、避免循环依赖的设计技巧
Go 不允许循环 import，这是优点而不是限制。
常见成因：
- 双向依赖的业务模型
- 过度分层
解决思路：
- 提取公共接口到上层 package
- 依赖接口，而不是具体实现
- 反转依赖方向（依赖倒置）
八、面向演进的结构设计
好的项目结构应该支持：
- 新增功能而不大规模重构
- 替换实现而不影响调用方
- 单元测试与 mock
工程建议：
- 不要一开始就“设计到位”
- 但要避免明显的结构死路
九、Go 项目结构的常见误区
- 照搬 Java / Spring 的分层结构
- package 粒度过细
- 过早拆分 microservice
- internal / pkg 使用混乱
工程结论：Go 更偏好“扁平 + 清晰边界”。
十、项目结构总结
- 结构服务于 package
- package 表达领域边界
- internal 是边界工具
一句话总结：
好的结构，让代码自己解释自己。
预告：Day 26｜依赖管理与 Go Modules 最佳实践
下一天将系统讲解：
- Go Modules 的工作原理
- 版本选择与依赖冲突
- replace / retract 的工程用法
- 可维护的依赖管理策略