Go API变更对module版本的影响

Go包API不兼容变更必须升主版本并更新模块路径，如v1→v2且路径变为github.com/user/lib/v2；不兼容变更包括函数签名、返回值、导出字段、接口方法及未文档化行为改动。

Go包的API变更直接触发module主版本升级，这是语义化版本（SemVer）的核心约束。只要出现不兼容的修改——比如函数签名变更、结构体字段删除、方法移除或行为逻辑调整——就必须升主版本（如 v1 → v2），并同步更新模块路径（如 github.com/user/lib → github.com/user/lib/v2）。否则编译会失败，或运行时出现静默错误。

哪些API变更算“不兼容”

不是所有代码改动都会影响兼容性。关键看是否破坏已有调用方的正常使用：

• 函数参数类型或数量变化（如 Do(x int) → Do(x string)）
• 返回值类型或个数变更（如从 func Get() int 改为 func Get() (int, error)）
• 导出结构体字段被删、重命名，或类型不兼容（如 ID int → ID string）
• 接口方法被移除或签名变更（实现该接口的类型将无法满足新定义）
• 公开函数/方法的行为发生非文档化改变（如原本空输入返回 nil，现在 panic）

如何提前发现API变更影响

升级前别只看版本号，要主动验证实际影响：

• 用 go list -m -u all 查出可升级项，再结合 go list -m -versions github.com/example/lib 看具体有哪些稳定版可选
• 读目标版本的 CHANGELOG 或 UPGRADE.md，重点关注 “Breaking Changes” 和 “Migration Guide”
• 运行 go doc github.com/example/lib@v2.0.0 对比旧版文档，快速定位导出符号增减
• 在干净分支上执行 go get github.com/example/lib@v2.0.0 && go mod tidy，再跑 go test ./...，观察编译错误和测试失败点

主版本升级后的正确导入方式

v2+ 模块不是“升级”，而是“新增一个独立模块”。必须显式使用带版本后缀的路径导入：

• ❌ 错误：仍写 import "github.com/user/lib"（这只会拉 v0/v1）
• ✅ 正确：改写为 import "github.com/user/lib/v2"，且 go.mod 中 require 行也必须含 /v2
• 共存没问题：项目里可以同时有 github.com/user/lib（v1）和 github.com/user/lib/v2，Go 会分别加载
• 注意：v2 模块内部仍应保持自身语义化版本演进，比如后续发 v2.1.0 不需改路径

临时绕过兼容问题的方法

当升级卡在某个依赖的API变更上，又不能立刻改业务代码，可用以下方式争取时间：

• 用 replace 锁定旧版（仅限临时调试）：
  replace github.com/user/lib => github.com/user/lib v1.9.0
• 若已升级但部分代码还没适配，可分批迁移：保留老 import 路径 + replace 指向兼容分支，新功能用新路径
• 避免长期依赖 replace 或 fork 修复，它会让构建不可重现，CI 可能失效

基本上就这些。API变更本身不可怕，可怕的是忽略它的版本含义。盯住 SemVer 规则、看清路径变化、验证导入行为，就能把升级变成一次可控演进。