replace是Go模块中用于临时覆盖依赖路径与版本的指令，解决本地修改验证、未发布提交测试、模块不可达或循环引用等问题，仅对当前module构建生效。
模块间引用必须用 replace 做本地开发适配
直接 go get 依赖本地未发布的模块会失败，因为 Go 默认只拉取远程 tag 或 branch。你在本地改了 common/log 模块，但 service/user 还在引用 v1.2.0，构建就报错找不到符号。
- 在
service/user/go.mod中手动加replace github.com/yourorg/common/log => ../common/log - 确保
../common/log下有有效的go.mod（即已执行过go mod init） -
replace只在当前 module 生效，不会被下游自动继承 —— 每个依赖它的模块都得单独配 - CI 环境要删掉
replace行，否则发布时会误打包本地路径
基础库必须定义稳定接口，而非暴露结构体
如果 common/config 直接导出 type Config struct{...}，下游模块就会和字段绑定；一旦你加个新字段或改类型，所有导入方全得同步改，彻底失去“独立演进”能力。
- 对外只暴露接口，比如
type ConfigLoader interface { Load() (map[string]string, error) } - 具体实现放在
config模块内部，不导出结构体 - 提供工厂函数，如
func NewYAMLConfigLoader(path string) ConfigLoader，调用方只依赖返回的接口 - 避免在接口方法中使用基础库自定义类型（如
func Parse(input common.RawData)），否则又把实现细节泄漏出去
版本升级必须靠 go mod edit -require 显式触发
基础库发了 v2.0.0，但下游模块的 go.mod 还卡在 v1.9.9，go get -u 不会自动升主版本 —— Go Modules 对 v2+ 要求路径带 /v2 后缀，这是语义化版本的硬约束。
- 升级命令必须写全：
go mod edit -require=github.com/yourorg/common/log/v2@v2.0.0 - 接着跑
go mod tidy，它会自动处理依赖图并清理冗余项 - 别依赖 IDE 自动提示更新 —— 很多编辑器只显示 patch 版本，对主版本变更无感知
- 升级后立刻运行
go test ./...，接口兼容性破坏往往只在测试里暴露
循环依赖检测要靠 go list -f '{{.Deps}}' ./... 手动查
Go 编译器报错 import cycle not allowed 时，错误信息只显示最外层两个包，实际循环链可能跨三层以上，比如 A → B → C → A，光看报错根本定位不到 C。
立即学习“go语言免费学习笔记（深入）”；
- 在根目录下执行
go list -f '{{.ImportPath}} -> {{.Deps}}' ./...，导出所有包的依赖关系 - 用文本工具搜索
common/metrics出现在哪些Deps列表里，再反查谁 import 它 - 真正解耦点不在删 import，而在把共用逻辑提到上层模块（如新建
shared/types），让A和C都只依赖它，不互相依赖 - 接口定义尽量放调用方模块，而不是被调用方 —— 避免基础库被迫 import 上游业务接口
go.mod 变更和接口文档更新，再多的 replace 和 interface 都只是纸面解耦。 
