模块路径必须稳定，拆分时子模块需独立 go.mod 且 module 名不能为主模块子路径；用 replace 本地验证后须改用真实版本号；避免 internal 被意外导出，应通过接口抽象隔离；伪版本需替换为正式 tag。
拆分前必须确认 go.mod 的 module path 是否已稳定
模块路径不是随便写的字符串，它会成为所有子模块导入语句的根前缀。一旦发布到公共仓库或被其他项目依赖，修改 module github.com/yourorg/project 会导致 import 路径失效、go get 失败、版本解析混乱。
- 尚未对外提供 API？可先用临时域名（如
module example.com/project），但需确保团队内部统一 - 已发布 v1.x？必须保持
module声明不变，哪怕只是把代码挪到新目录 - 想按功能拆出
auth、payment等子模块？它们各自要有独立的go.mod，且module名不能是主模块的子路径（例如github.com/yourorg/project/auth是错的）
用 replace 在本地验证子模块依赖关系
直接推送到远程再 go get 太慢，也容易污染主干。在主模块的 go.mod 中临时加 replace 指向本地路径，能绕过版本校验，快速测试接口兼容性。
replace github.com/yourorg/payment => ./modules/payment-
./modules/payment必须包含合法的go.mod，且module名与replace左侧完全一致 - 执行
go mod tidy后，go.sum里会出现// indirect标记，说明该模块未被直接 require，而是通过 replace 注入 - 上线前务必删掉
replace行，并改用真实版本号（如github.com/yourorg/payment v0.2.0）
避免 internal 包被意外暴露为公共接口
很多人把重构中的过渡代码扔进 internal/ 目录，以为“只要不 export 就安全”。但 Go 的 internal 机制只检查 import 路径，不检查调用链——如果某个导出函数返回了 internal 类型的指针或结构体字段，外部模块就能拿到并使用它。
- 运行
go list -f '{{.ImportPath}}: {{.Deps}}' ./……可扫描哪些包间接依赖了internal - 真正隔离应靠接口抽象：把
internal/auth/service.go里的逻辑抽成auth.Service接口，放在auth/根目录下导出，实现放internal - CI 中加入
grep -r 'import.*internal' ./防止误提交
版本升级时小心 go.sum 中的伪版本（pseudo-version）残留
模块刚拆出来还没打 tag，go mod tidy 会自动生成类似 v0.0.0-20240520123456-abcdef123456 的伪版本。这些哈希值绑定的是 commit，不是语义化版本，一旦重写历史（rebase/force push），下游 go build 就会失败。
立即学习 “go 语言免费学习笔记（深入）”；
- 开发阶段可用
go mod edit -require=github.com/yourorg/storage@v0.0.0-00010101000000-000000000000占位，等正式发布再替换 - 发布首版前必须打 Git tag：
git tag v0.1.0 && git push origin v0.1.0，否则go list -m -versions查不到可用版本 -
go.sum里同一模块出现多行不同伪版本？说明有间接依赖拉取了旧 commit，需用go mod graph | grep定位来源
重构模块不是把代码剪开再粘回去，关键在于让每个 go.mod 的边界同时满足：编译可独立、依赖可锁定、接口可演进。最容易被忽略的是——模块名一旦写进 go.mod，它就不再是文件路径，而是一个需要长期维护的契约。
