如何在Golang模块中管理内部包结构_Golang项目目录最佳实践_技术教程

Go项目包结构核心原则是按功能职责而非技术分层组织，用internal严格隔离非导出API，模块根目录即主go.mod位置；按业务域（如order/、payment/）而非MVC分层；命令、配置、第三方适配器需分离以保持核心逻辑纯净。

Go 项目内部包结构的核心原则是：以功能职责划分，而非技术分层；用 internal 严格隔离非导出API；模块根目录即主模块声明点，避免嵌套多层 go.mod。

internal/ 是 Go 官方支持的私有包机制——任何位于 internal/ 子目录下的包，**仅能被其父目录（或祖先目录）中同一模块的代码导入**。这是控制内部实现暴露范围最可靠的方式。

把不希望被外部模块直接依赖的工具、领域模型、中间件等放进去，例如：internal/domain、internal/handler、internal/repo
避免在 internal 下再建 internal（如 internal/foo/internal/bar），Go 不会递归识别，且语义混乱
若需共享部分能力给其他内部子模块，可将公共逻辑提到上一级 internal/common 或 internal/pkg，并确保调用方与被调用方同属一个模块

Go 不鼓励强制分层（如 controller/service/repository 目录平铺）。更自然的做法是按“业务上下文”组织，每个子目录代表一个高内聚的功能单元。

例如电商项目可设：cmd/（入口）、api/（HTTP/gRPC 接口定义）、order/（订单领域）、payment/（支付领域）、internal/config（配置加载）、internal/db（数据库驱动封装）
每个业务目录（如 order/）内部可包含自己的 model.go、service.go、repository.go，无需跨目录跳转
接口定义（interface）优先放在调用方所在包（如 order/service.go 中定义 PaymentClient 接口），实现放在被依赖方（如 payment/client.go），体现“依赖倒置”

一个 Git 仓库通常对应一个主模块（go.mod 在根目录）。只有当确实需要独立版本、独立发布、或被多个项目复用时，才考虑拆分子模块（如 /pkg/xxx 下再放 go.mod）。

子模块应具备明确的契约（稳定 API + 文档 + 单元测试），不能只是代码搬家
避免“为拆而拆”：比如把所有 utils/ 提成子模块，反而增加维护成本和版本同步负担
主模块通过 replace 或本地路径临时引用子模块，上线前改用语义化版本（如 github.com/your/project/pkg/log v0.2.0）

保持核心逻辑纯净，把环境相关、I/O 密集或易变的部分显式剥离。

cmd/ 下只保留极简的 main.go：解析 flag、初始化 config、构造 root 依赖图、启动服务。不写业务逻辑
config/ 或 internal/config/ 负责加载 YAML/TOML/Env，并映射为强类型 struct；校验放在这里，不在 service 层重复判断
第三方 SDK 封装统一进 internal/adapter/（如 adapter/aws/s3.go、adapter/postgres/repo.go），对外暴露 domain 层接口，隐藏 SDK 细节

基本上就这些。Go 的目录结构没有银弹，关键是让新成员一眼看懂“哪块代码负责什么”，并且能快速定位修改点。不复杂但容易忽略：每次新增包前，先问一句——它会被谁用？会不会被误引？要不要进 internal？