Go项目结构无官方强制规范，核心是按业务域（如user、order）分包，每个域内含api/domain/storage等子包；用internal/限制可见性，pkg/放可复用组件；依赖通过接口抽象，避免循环引用；包路径层级≤3层，保持扁平易维护。
Go 项目结构没有官方强制规范，但合理的组织方式能显著提升可维护性、可测试性和团队协作效率。核心原则是：按功能职责分包，避免循环依赖，让 import 路径清晰反映业务逻辑层次，同时兼顾 Go 的包管理机制（尤其是 Go Modules）。
以领域/功能为中心划分顶层包
不要按技术层（如 controller、service、repository）横向切分整个项目，而是先识别业务域（例如 user、order、payment），每个域自包含其完整能力：
- 每个域是一个独立子包（如
internal/user），内部再按需细分api、domain、storage等子包 - 域之间尽量低耦合；跨域调用通过接口（定义在被依赖方）或消息传递，而非直接导入具体实现
- 顶层
cmd/下放可执行入口（如cmd/api、cmd/migrate），明确区分构建产物
善用 internal/ 和 pkg/ 控制可见性
Go 的 internal/ 目录天然限制包导出范围——只有其父目录及祖先目录下的代码可导入它。这是控制封装边界的关键工具：
- 把核心业务逻辑、数据模型、基础设施适配器等放在
internal/下（如internal/user/domain、internal/db），防止外部模块（包括同项目其他服务）误用内部细节 - 将真正需要被外部复用的通用能力（如自定义错误类型、HTTP 工具函数、配置解析器）放在
pkg/，并保证向后兼容 - 避免在
internal/中放置仅用于单元测试的 mock 或 fake 实现；它们应和测试文件放在一起（xxx_test.go）或放入testutil/
模块化依赖与接口抽象
Go Modules 是管理版本和依赖的基础，但结构设计要配合它发挥作用：
立即学习“go语言免费学习笔记（深入）”；
- 一个 Git 仓库可包含多个 module（通过不同
go.mod文件），适合拆分为独立发布的 SDK 或微服务；但多数单体项目只需一个根go.mod - 对数据库、缓存、第三方 API 等外部依赖，定义 interface 在业务包内（如
user.Repository），实现在internal/storage/或internal/adapter/，便于替换和测试 - 避免在
main或 handler 中直接初始化 DB 连接；使用依赖注入（手动或轻量库如wire）统一管理生命周期
保持扁平、避免过深嵌套
Go 鼓励“小而专注”的包，而不是深度嵌套的目录树：
- 包路径层级建议 ≤ 3 层（如
internal/user/api→ 合理；internal/user/api/v1/rest/handler→ 过深，考虑合并或重命名） - 一个包通常只做一件事：
user包负责用户核心逻辑，userapi包负责 HTTP 接口编排，userrepo包负责持久化——名字体现职责，不堆砌术语 - 定期审视包大小：若某包超过 200 行且职责模糊，拆分或重构；若多个包总是一起被导入，可能说明抽象层级不合理
结构不是一成不变的，随着业务演进持续调整。关键是每次新增功能时，先问：它属于哪个业务域？是否需要新接口？依赖谁？是否该放进 internal？答案自然会引导出清晰的组织方式。
