17370845950

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 是管理版本和依赖的基础，但结构设计要配合它发挥作用：

• 一个 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？答案自然会引导出清晰的组织方式。