Go的internal目录需紧贴根go.mod才生效，接口应独立于实现置于抽象包中，cmd/仅负责初始化和入口调用，pkg/命名体现业务职责而非技术栈，过度拆分小包会降低可维护性与构建性能。

拆分 package 时，别让 internal 变成摆设

Go 的 internal 目录本意是限制包可见性，但很多人只图方便把它当“私有文件夹”用，结果导致跨模块引用失控。真正起作用的前提是：internal 的父目录必须是 module root（即包含 go.mod 的目录），且调用方路径不能与 internal 路径共享同一祖先 module。

• 错误示范：

  myproject/
  ├── go.mod
  ├── cmd/
  │   └── app/
  │       └── main.go  // 这里 import "myproject/internal/db" ✅
  └── internal/
      └── db/

  ——看起来合理，但如果另一个 module github.com/others/project 也依赖了 myproject，它就不能 import myproject/internal/db，这是 Go 编译器强制检查的
• 常见踩坑：把 internal 放在子 module 下（比如 myproject/api/go.mod），此时 myproject/api/internal 对 myproject 根 module 来说已不构成 “internal 限制”，会被绕过
• 建议：所有 internal 必须紧贴根 go.mod，且避免嵌套多层 module；若需复用逻辑，宁可抽成独立 public module，也不要强行暴露 internal

接口定义放哪？别放在实现 package 里

拆 package 时最容易犯的错，是把 interface 和它的 struct 实现塞进同一个 package。这会导致调用方被迫依赖具体实现细节，失去 mock 和替换能力。

• 正确做法：把核心接口提到上层抽象 package，例如 myproject/storage 只放 type BlobStore interface { Put(...); Get(...) }，而 myproject/storage/s3 和 myproject/storage/fs 各自实现
• 好处：测试时可直接 import "myproject/storage"，用 gomock 或手写 fake，完全不碰 s3 或 fs 的 HTTP client、磁盘 IO 等副作用
• 注意：如果接口只被单个实现使用，且无替换计划，那它大概率不该存在——Go 不鼓励为抽象而抽象；接口应出现在“稳定契约”处，而非“未来可能扩展”的假设中

cmd/ 和 pkg/ 的边界到底怎么划？

cmd/ 应该极度轻量，只做三件事：解析 flag、初始化依赖、调用入口函数。其余所有业务逻辑、数据结构、工具函数，都必须移出 cmd/。

• cmd/app/main.go 里不应出现 http.HandleFunc、sql.Open、json.Unmarshal 等具体操作，这些属于 pkg/server、pkg/db、pkg/model
• pkg/ 下的 package 命名要体现职责，而不是技术栈，比如用 pkg/auth 而非 pkg/jwt，用 pkg/order 而非 pkg/pg；后者容易让人误以为只能用于 PostgreSQL
• 警惕“工具包陷阱”：pkg/util 或 pkg/common 会快速膨胀成垃圾场；一旦发现某个函数被两个以上 domain package 使用，才考虑提升到 pkg；否则就留在各自 domain 内，哪怕有轻微重复

什么时候该合并 package，而不是继续拆？

拆分不是目的，可维护性才是。一个 package 如果长期只有 1–2 个导出符号、不到 100 行代码、且从不单独测试，那它大概率不该独立存在。

立即学习“go语言免费学习笔记（深入）”；

• 典型信号：go list -f '{{.Name}}: {{len .Exports}}' ./pkg/... 输出大量 xxx: 1 ——说明抽象粒度太细，增加了 import 链和认知负担
• 合并原则：功能强耦合、生命周期一致、变更频率高度同步的代码，应放在同一 package；比如 user.User 结构体、user.Validate()、user.FromDBRow()、user.ToJSON() 就该共存，而不是拆成 model/validator/mapper
• 性能影响：过多小 package 会略微拖慢 go build（尤其是增量构建），因为每个 package 都要走一遍类型检查和导出分析；这不是瓶颈，但它是“过度工程”的客观副产品

最常被忽略的一点：package 拆分不是一次性设计任务，而是随着测试覆盖率上升、重构频次增加、协作者反馈变多，逐步演进出来的。一开始用一个 pkg/core 没问题，等它长到 3000 行、CI 开始超时、PR review 总卡在“这个函数该放哪”，再动手拆也不迟。