v2+模块必须加/v2后缀，因Go将example.com/pkg与example.com/pkg/v2视为不同模块路径而非版本号；不加后缀会导致import失败，即使有v2.0.0标签也无法加载。
为什么v2+模块必须加/v2后缀
因为Go把example.com/pkg和example.com/pkg/v2当成两个完全不同的模块路径，不是版本号后缀，而是独立导入路径。不加/v2会导致go build报错cannot find module providing package，哪怕你本地有v2.0.0标签也加载不了。
常见错误现象：
- 在
go.mod里写require example.com/pkg v2.1.0，但代码里仍用import "example.com/pkg"—— 编译失败 - 升级到v2后忘记改导入路径，CI构建突然失败，本地却因缓存“侥幸”通过
- 误以为
@latest能跨主版本升级，结果go get -u卡在v1.x不动
真正生效的是路径本身：import "example.com/pkg/v2" → 工具链只认这个路径下的v2系列版本；import "example.com/pkg" → 只匹配v0或v1（无后缀）。
如何安全发布一个v2模块
不是打个git tag就完事。主版本升级意味着API不兼容，必须同步完成三件事：
立即学习“go语言免费学习笔记（深入）”；
- 在模块根目录运行
go mod edit -module example.com/pkg/v2，更新go.mod第一行的模块路径 - 所有
import语句从"example.com/pkg"批量替换成"example.com/pkg/v2"（包括测试文件） - 打tag时必须用
v2.0.0（带v前缀），不能是2.0.0或release/v2
漏掉任意一步，下游用户要么导包失败，要么实际加载的仍是v1代码却声称用了v2——这种“假v2”比没升级还危险。
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
同一项目里能同时用pkg v1和pkg/v2吗
可以，而且这是主版本隔离的设计初衷。Go不认为它们是“同一个包的不同版本”，而是两个独立模块，各自维护自己的require条目。
使用场景举例：
- 迁移过程中保留旧逻辑调用v1，新功能用v2
- 第三方库A依赖
github.com/sirupsen/logrus v1.9.0，而你的代码需要github.com/sirupsen/logrus/v2，两者共存无冲突
注意：go list -m all会显示两行：github.com/sirupsen/logrus v1.9.0和github.com/sirupsen/logrus/v2 v2.3.0 —— 这是正常且预期的行为，不是重复依赖。
伪版本和预发布版本对主版本隔离的影响
伪版本（如v0.0.0-20240512103022-abc123def456）和预发布版（如v2.0.0-beta.1）都遵守路径规则：只要主版本是2，就必须走/v2路径。
但它们默认不会被@latest选中，也不会参与MVS（最小版本选择）算法的自动升级。这意味着：
-
go get example.com/pkg@latest永远拿不到v2.0.0-beta.1，除非显式指定 - 如果你在
go.mod里写了require example.com/pkg/v2 v0.0.0-20240512103022-abc123def456，它只影响当前模块，不影响其他路径
最容易被忽略的一点：主版本隔离只看路径，不看版本字符串是否“正式”。哪怕你用v2.0.0-rc.1，只要导入路径是/v2，它就和v2.0.0处于同一兼容性边界内——但v2.0.0-rc.1和v2.0.0之间依然可能有API差异，不能假设等价。
