go module replace 是本地基础库解耦的最快路径：通过在主模块中用 replace 指向本地路径实现临时依赖重写，要求被替换模块有合法 go.mod、接口定义独立于实现、禁止业务/基础设施强依赖、杜绝循环引用与隐式依赖。
Go Module replace 是本地基础库解耦的最快路径
当你在多模块项目中想把通用工具、错误定义或配置结构抽成独立基础库，又不想立刻发布到远程仓库或推送到私有代理，replace 是唯一能绕过版本校验、直接指向本地路径的机制。它不改变模块语义，只临时重写 import 路径解析规则。
- 必须在主模块（即
go.mod所在根目录）中声明，子模块的go.mod无法覆盖上级依赖 - 路径必须是绝对路径或相对于主模块的相对路径，例如：
replace github.com/yourorg/utils => ./internal/utils - 被 replace 的模块自身也必须有合法
go.mod，且module声明与 import 路径严格一致 - 执行
go mod tidy后，go.sum会记录本地路径的校验和——这意味着该替换不是“临时调试”，而是可复现的构建状态
基础库接口定义必须放在调用方或独立 contract 包
常见错误是把 ConnPoolInterface 或 UserRepository 定义在具体实现包（如 mysqlrepo 或 redisclient）里，导致其他模块为使用接口而被迫导入实现包，引发隐式依赖和循环风险。
- 正确做法：新建
interfaces/或contract/目录，只放.go文件，不放任何实现逻辑 - 接口命名应体现契约而非技术，例如
Notifier比SMSClient更适合作为抽象层 - 若基础库本身需提供默认实现（如内存缓存），应通过单独子包暴露，例如
interfaces/memorycache，而非混在接口定义中 - 测试时直接
import interfaces+import mocks，完全隔离生产实现
避免在基础库中引入业务逻辑或基础设施强依赖
基础库一旦开始 import github.com/gin-gonic/gin、gorm.io/gorm 或 go.uber.org/zap，它就不再是“基础”了——它变成了一个绑定特定生态的中间层，后续替换成本陡增。
- 日志、HTTP 客户端、数据库操作等，统一抽象为接口传入，例如
Logger接口只含Infof/Errorf方法，不暴露*zap.Logger - 禁止在基础库中调用
os.Getenv、flag.Parse或初始化全局变量，这些行为应下沉到main或cmd层 - 如果某个工具函数必须依赖 HTTP 客户端，应接收
http.Client作为参数，而不是内部构造 - 基础库的
go.mod中不应出现业务相关 module，仅保留golang.org/x/...等标准扩展
模块间引用必须单向：从上到下，不可回流
基础库（如 types、errors）可以被任意模块 import，但它自己绝不能 import 业务模块（service）、应用层（handler）或基础设施（mysqlrepo）。这是编译器报 import cycle 的根本原因。
- 检查循环的最快方式：
go list -f '{{.Deps}}' your-module-path，观察输出中是否出现反向路径 - 若发现
types里用了service.User，说明职责错位——应把User移到types，或拆出types.UserRef这类轻量引用结构 - 跨模块共享错误码时，不要用
errors.New("user not found")，而应定义var ErrUserNotFound = errors.New("user not found")并导出，由调用方判断而非拼字符串 - 所有跨模块传递的数据结构，应为值类型（struct）或接口，避免指针穿透导致隐式依赖
NewXXXClient() 或 MustLoadConfig()，你就已经把它拖进了业务泥潭。golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
