Go项目包结构核心原则是按功能职责而非技术分层组织，用internal严格隔离非导出API，模块根目录即主go.mod位置；按业务域（如order/、payment/）而非MVC分层；命令、配置、第三方适配器需分离以保持核心逻辑纯净。
Go 项目内部包结构的核心原则是：以功能职责划分，而非技术分层；用 internal 严格隔离非导出API；模块根目录即主模块声明点，避免嵌套多层 go.mod。
用 internal 包限制跨模块访问
internal/ 是 Go 官方支持的私有包机制——任何位于 internal/ 子目录下的包，**仅能被其父目录（或祖先目录）中同一模块的代码导入**。这是控制内部实现暴露范围最可靠的方式。
- 把不希望被外部模块直接依赖的工具、领域模型、中间件等放进去，例如：
internal/domain、internal/handler、internal/repo - 避免在
internal下再建internal（如internal/foo/internal/bar），Go 不会递归识别，且语义混乱 - 若需共享部分能力给其他内部子模块，可将公共逻辑提到上一级
internal/common或internal/pkg，并确保调用方与被调用方同属一个模块
按业务域组织，而非 MVC 或技术层
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）。
立即学习“go语言免费学习笔记（深入）”；
- 子模块应具备明确的契约（稳定 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？
