Go项目中如何复用公共包_Go公共模块设计方案

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 下来第一行就报错 —— 那就不是公共包，只是你硬盘里的一个文件夹。