Go项目公共包复用依赖go mod路径语义、import可寻址性及显式模块边界；必须发布为独立module，禁用internal/跨模块引用，遵循严格版本语义（v0.x不兼容、v1+向后兼容），重大变更需升MAJOR并更新module路径。
Go 项目中复用公共包不是靠“设计模式”堆出来的，而是靠 go mod 的路径语义、import 路径的可寻址性，以及模块边界的显式声明来落地的。只要路径能被 go build 正确解析，且版本可控，复用就成立；否则就是“伪复用”，迟早出问题。
公共包必须发布为独立 go module
很多团队把公共代码放在主项目下的 internal/pkg 或 lib/ 目录里，然后用相对路径 import —— 这不是复用，是硬耦合。Go 不支持子目录级 module 复用，go mod 只认根目录下的 go.mod 文件。
- 每个公共包必须有自己的仓库（如
git@github.com:org/utils.git），且根目录含go.mod，module 名与仓库 HTTPS/SSH 地址一致（如module github.com/org/utils） - 不能用本地相对路径或
replace长期绕过版本管理；replace仅用于临时调试，上线前必须删掉 - 主项目
go.mod中通过require github.com/org/utils v0.3.1声明依赖，而非复制源码
如何避免循环依赖和隐式版本冲突
常见错误是：A 项目依赖 B 包，B 包又间接依赖 A 的某个内部工具函数 —— 这在 Go 里直接报错 import cycle not allowed。根本解法是把真正通用的逻辑抽到第三模块 C，A 和 B 都依赖 C。
- 禁止跨 module 使用
internal/：一旦模块拆分，internal就不可见，强行暴露会导致编译失败 - 所有跨模块接口应定义在公共包内，而非调用方；例如日志抽象不放在业务模块，而放在
github.com/org/log中提供Logger接口 - 用
go list -m all | grep utils检查实际加载的版本；多个子模块各自require不同版本时，go mod会自动升级到最高兼容版，但可能引入意料外的行为变更
版本号不是摆设：v0.x 和 v1+ 的语义差异直接影响复用安全
Go 的版本语义非常严格：v0.x 表示不稳定 API，任意小版本都可破坏兼容性；v1.0.0+ 才承诺向后兼容。很多团队卡在 v0.9.5 多年不升，结果下游不敢升级，最终形成“版本黑洞”。
- 新公共包起步建议直接发
v1.0.0，哪怕功能简单；若需快速迭代，可用v0.1.0，但必须同步文档注明“API 尚未冻结” - 重大变更（如函数签名改、结构体字段删）必须升
MAJOR版本，如从v2.0.0开始，module 路径末尾要加/v2（module github.com/org/utils/v2），否则go mod无法区分 - 用
go get github.com/org/utils@v2.1.0显式升级，并检查go.mod中是否已更新路径和版本
module github.com/org/utils/v2 go 1.21 // 注意：v2 版本路径必须带 /v2 后缀 // 否则 go mod 会当作 v1 处理，导致版本混乱
最常被忽略的一点：公共包的 go.mod 里不要写死主项目的 replace 或本地路径；它必须是“自包含”的，能在任何干净环境里 go build 通过。否则别人 clone 下来第一行就报错 —— 那就不是公共包，只是你硬盘里的一个文件夹。
