主版本号递增意味着API不向后兼容，需重签契约：module路径必须改为/v2，所有import语句同步更新为带/v2的完整路径，否则go get失败或降级伪版本，且类型签名等隐性变更将引发编译或运行时错误。
主版本号递增意味着什么
主版本号递增（比如从 v1 升到 v2）不是“升级”，而是 Go 模块系统强制你承认：现有 API 不再向后兼容。这会触发整个导入路径变更，所有下游代码必须显式适配——它本质上是一次契约重签，不是补丁修复。
go.mod 中 module 路径必须改
不改路径就升 v2，Go 工具链会直接拒绝或降级为伪版本（如 v0.0.0-20260803120000-abc123），导致 go get @latest 失效、CI 构建不稳定。
- 旧：
module example.com/mylib - 新：
module example.com/mylib/v2
注意：路径末尾的 /v2 是硬性要求，不能写成 /v2.0.0 或 /V2；大小写敏感，且必须与 Git tag 的 v2 前缀一致。
所有 import 语句必须批量更新
Go 不提供自动重写 import 的工具，go fix 对模块路径变更无作用。手动或脚本处理时容易漏掉以下位置：
Golang Uber Dig
下载
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
立即学习“go语言免费学习笔记（深入）”；
- 普通
import块中的路径，如import "example.com/mylib"→"example.com/mylib/v2" -
replace指令里指向本地路径的引用（例如replace example.com/mylib => ./local-fix），也要同步加/v2 - 测试文件里的
import，尤其是xxx_test.go和集成测试中跨模块引用 - Go 文件顶部的
//go:generate注释里硬编码的路径（如生成 mock 的命令）
接口/结构体变更带来的隐性重构成本
主版本升级常伴随类型签名修改，但真正烧时间的是那些“看起来没变却失效”的地方：
- 函数参数从值类型改为指针（
func Do(x Config)→func Do(x *Config)），调用方需补&，编译器报错但不易定位上下文 - 返回错误类型从
error改为自定义 error 类型（如*ValidationError），原有errors.Is(err, xxx)判断全部失效 - 结构体字段名小写（导出性变化）或类型变更（
int→int64），JSON 反序列化静默失败或 panic - 中间件、HTTP handler 等依赖 context 或中间层抽象的代码，若内部 interface 方法签名变动，即使没直接 import 该模块，也会在构建时报错
这类问题不会出现在 diff 里，只有运行时或深度测试才暴露，是重构中最难预估的时间黑洞。
