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/——看起来合理，但如果另一个 modulegithub.com/others/project也依赖了myproject，它就不能 importmyproject/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/。
Conventional Git
下载
Conventional Commits v1.0.0 分支、工作树命名及提交信息规范，适用于 GitHub 与 GitLab 项目，用于创建分支和命名工作树等场景。
-
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 总卡在“这个函数该放哪”，再动手拆也不迟。
