Go项目模块化拆分实战教程

有志者，事竟成！如果你在学习Golang，那么本文《Go项目模块化拆分实战指南》，就很适合你！文章讲解的知识点主要包括，若是你对本文感兴趣，或者是想搞懂其中某个知识点，就请你继续往下看吧~

模块拆分前必须先初始化 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(...)
}

测试文件与生产代码放同一目录，不隔离

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 文件，否则测试会变慢、不稳定、污染环境。

今天带大家了解了的相关知识，希望对你有所帮助；关于Golang的技术知识我们会一点点深入介绍，欢迎大家关注golang学习网公众号，一起学习编程~