单体应用拆模块核心在于解耦依赖与定义接口边界，而非单纯物理目录迁移；应先通过包级封装、接口抽象和依赖注入实现逻辑模块化，仅当需独立发版、跨项目复用或团队隔离CI/CD时，才渐进升级为多go.mod。
单体应用拆模块，不是把代码挪进不同目录就完事；真正要动的是依赖关系和接口边界。多数项目卡在“物理拆分”这一步，结果包路径变了，耦合还在。
先确认是否真需要多 module
Go 单体项目里，90% 的“模块化需求”其实用包（package）+ 接口就能解决。只有当出现以下情况时，才值得引入多个 go.mod：
- 某个子系统（如支付、搜索）要被其他项目直接
require，且需独立发版 - 团队按模块划分，不同组对
user和order有完全隔离的 CI/CD 流程 - 构建时间过长，想通过
go build ./service/user单独编译验证 - 需要为不同模块设置不同
GOOS/GOARCH构建目标
如果只是想“看着更清晰”，别建新 go.mod——internal/user 和 internal/order 放在同一主模块下，靠包路径和接口约束已足够支撑 2–3 年演进。
拆之前必须清理 main.go 的职责
重构第一步不是建目录，是把 main.go 削成一张皮：它只该做三件事——读配置、启日志、调 app.Run()。所有业务逻辑、DB 初始化、路由注册全得移出去。
立即学习“go语言免费学习笔记（深入）”；
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
- 路由注册统一收口到
internal/route，导出RegisterRoutes(*gin.Engine)或SetupRouter() *http.ServeMux - 数据库连接放进
internal/infra/db，导出NewDB()，不暴露 driver 细节 -
main.go不得直接import internal/handler/user，只依赖internal/app这类抽象层 - 中间件统一放在
internal/middleware，用函数选项模式（如AuthMiddleware(roles ...string)）传参
常见错误是 main.go 里还留着 db, _ := sql.Open(...) 或 r.POST("/user", userHandler) —— 这说明拆分还没真正开始。
用接口定义跨模块契约，而非直接 import 包
模块之间不能靠 “import internal/user/service” 来通信。真正的边界是接口：一个模块只依赖另一个模块声明的接口，具体实现由启动时注入。
- 在
internal/user/port定义UserRepository接口（注意路径名含port，表明它是对外契约） - 实现放在
internal/user/adapter/gorm或internal/user/adapter/memory，不被其他模块 import - 调用方（比如
internal/order）只 importinternal/user/port，并接收UserRepository作为参数 - 运行时由
cmd/main.go组合：传gormRepo给orderService，测试时换mockRepo
如果 internal/order 直接调用了 user.NewUserService() 或用了 user.User 结构体字段，说明接口没立住，还是紧耦合。
本地开发时用 replace 而非硬路径引用
一旦决定拆多 module，比如 service/user/go.mod 模块路径为 example.com/myproject/service/user，其他模块不能写 import "./service/user" —— Go 不认这种相对路径。
- 在调用方模块（如
cmd/app/go.mod）里加replace example.com/myproject/service/user => ../service/user - 确保
go mod tidy后能成功解析，且go list -m all显示本地路径被正确映射 - CI 环境中去掉
replace，改用require example.com/myproject/service/user v0.1.0+ tag 发布 - 避免在多个
go.mod中重复声明相同依赖版本，容易引发go mod graph冲突
最常被忽略的是：跨 module 调用失去编译期接口实现检查。比如 user 模块更新了 UserRepository 方法签名，order 模块不会报错，直到运行时 panic —— 必须靠集成测试覆盖。
