replace用于在go.mod中通过路径重定向实现模块“虚拟拆分”，不改变运行时行为，仅调整导入解析；需在require块后声明伪模块路径、确保目标含go.mod、避免循环依赖并用interface解耦，测试须区分开发态与发布态。
用 replace 在 go.mod 中做模块“虚拟拆分”
单体项目还没到拆仓库阶段，但代码已经难维护？别急着建新 repo，先在现有 go.mod 里用 replace 划出逻辑边界。这一步不改任何运行时行为，只改导入路径的解析方式。
常见错误是直接把子目录当成模块导入，比如 import "./internal/user" —— Go 不允许相对路径导入，会报 invalid import path。
- 在根
go.mod中声明伪模块路径：replace example.com/myapp/user => ./internal/domain/user - 让其他包（如
order）通过import "example.com/myapp/user"引用，而非硬编码路径 - 确保
internal/domain/user/go.mod存在（哪怕只含module example.com/myapp/user），否则go test会失败 - 所有
replace行必须放在require块之后，否则go mod tidy会清掉
重构时如何避免循环依赖和 import cycle 错误
一旦开始按功能域拆包，import cycle not allowed 就成了高频报错。根本原因不是“谁先引用谁”，而是模块间存在隐式双向契约——比如 user 包直接调用了 order 的实现函数，反过来也一样。
真实场景中，这种循环往往藏在日志、错误码或工具函数里：一个包偷偷 import 了另一个包的 pkg/log，而后者又依赖前者的模型。
立即学习“go语言免费学习笔记（深入）”；
- 禁止跨模块直接引用
struct或func，只允许通过interface通信 - 把共享类型（如
ErrorResponse）上提到api/或pkg/error，不放在任一业务模块内 - 用
go mod graph | grep -E "(user|order)"快速定位双向边，比肉眼扫 import 更可靠 -
internal/pkg/下的工具包只能被上层依赖，自身绝不能 importinternal/domain/里的任何东西
什么时候该把 replace 升级为独立 Git 仓库
不是所有模块都值得独立成仓。判断标准只有一个：是否出现「多团队协作」或「独立发布节奏」。比如支付模块要对接三方 SDK，版本升级周期和主系统完全不一致，这时才需要真实拆仓。
过早拆仓反而增加 CI/CD 复杂度，且容易因 tag 管理混乱导致 go get 拉错版本。
- 先在原 repo 内完成接口定义和测试覆盖，确保
user.Interface稳定 - 新建仓库后，打第一个
v0.1.0tag，然后把原replace改成require example.com/myapp/user v0.1.0 - 旧 repo 的
go.mod中删掉对应replace行，再go mod tidy - 务必同步更新所有调用方的
go.mod，否则本地能跑，CI 可能因缓存拉不到新 tag
重构过程中最易被忽略的测试陷阱
很多人以为加了 go test 就算安全，但模块化重构真正危险的是「测试范围漂移」：原来在 cmd/api 里写的集成测试，现在因为 replace 生效，实际跑的是 ./internal/domain/user 的本地代码，而不是未来上线的独立模块版本。
这意味着你测的其实是「开发态」，不是「发布态」。
- 每个业务模块的
_test.go文件必须只 import 本模块路径，禁止跨模块 import 实现 - 对
user.Service的单元测试，应 mockuser.Repository接口，而不是 new 一个真实 repo - 集成测试放到
cmd/api层，用require拉取真实版本，验证模块间契约 - 每次
go mod vendor后检查vendor/目录下是否有意外的子模块代码混入
