模块拆分前必须先初始化 go.mod，运行 go mod init example.com/myapp 是前提；模块路径需真实唯一，目录应按业务域（如 /internal/user）而非技术层组织；接口定义在调用方，实现放在被调方，测试文件与源码同目录。
模块拆分前先确认 go.mod 已初始化
没初始化 go.mod 就谈模块化，等于在泥地里搭积木。运行 go mod init example.com/myapp 是所有后续操作的前提。注意模块路径（module 声明）应体现真实域名或组织名，避免用 main 或本地路径——否则 go get 会失败，内部子模块也无法被正确引用。
常见错误：在项目根目录外执行 go mod init，或反复执行导致 go.mod 被覆盖重写。一旦模块路径定下，就别轻易改；若真要迁移，需同步更新所有 import 路径和 CI 中的依赖解析逻辑。
按职责边界切分目录，不是按技术类型
别建 /controllers、/handlers、/services 这类“MVC 遗留分类”。Go 项目更推荐按业务域（Domain）或功能流（Feature）组织，例如用户注册流程涉及输入校验、密码哈希、数据库写入、邮件发送，这些应尽量收在 /internal/user 下，而非散落在不同技术层目录中。
internal/
├── user/
│ ├── user.go // User 结构体、核心方法
│ ├── register.go // RegisterUser() 及其依赖的校验、存储、通知
│ └── register_test.go
├── payment/
│ └── ...
└── shared/ // 真正跨域复用的工具（非通用 utils）
└── idgen.go
-
/cmd只放main.go，每条命令一个子目录（如/cmd/api、/cmd/migrate） -
/internal外的包（如/pkg）只导出稳定接口，供外部项目依赖；内部实现全锁在/internal下 - 避免
internal/foo/internal/bar这种嵌套——Go 不允许跨internal目录导入
接口定义优先放在调用方，而非实现方
比如 user.RegisterUser() 需要发邮件，它不该依赖具体邮件服务实现，而应依赖一个 mailer.Sender 接口。这个接口应定义在 /internal/user 里，由调用方声明，再由 /internal/email 提供实现。这样既解耦，又避免循环导入。
错误做法：/internal/email 定义 Sender，然后 /internal/user import 它——看似合理，实则把用户逻辑绑定死了邮件实现，测试时无法 mock，换短信通道也得改 user 包。
正确做法：
// internal/user/interface.go
type Mailer interface {
Send(to, subject, body string) error
}
// internal/user/register.go
func RegisterUser(m Mailer, ...) error {
...
return m.Send(...)
}再让 /internal/email 实现该接口，主程序组装时传入。
测试文件与生产代码放同一目录，不隔离
Go 的测试惯例是 xxx_test.go 和 xxx.go 同目录。不要建单独的 /test 或 /e2e 目录来放单元测试——那会让测试难以维护，且 IDE 很难自动关联。
集成测试（如需要启动 DB 或 HTTP server）可放 /internal/user/integration_test.go，但必须用 //go:build integration 标签隔离，防止日常 go test 执行。CI 中显式运行：go test -tags=integration ./internal/user。
容易忽略的一点：如果模块间有强依赖（比如 user 依赖 db），测试时别直接 new 一个真实 DB 连接。用接口 + 内存 mock（如 sqlmock）或临时 SQLite 文件，否则测试会变慢、不稳定、污染环境。
