大版本升级必须改模块路径，否则编译失败；Go 要求 v2+ 模块在 go.mod 中显式包含 /v2 后缀，否则报错 invalid version；导入语句、Git 分支、测试验证、动态路径、接口兼容性、replace 限制、go.work 使用及共存陷阱均需严格遵循规范。
大版本升级必须改模块路径，否则编译失败
Go 要求 v2+ 模块必须在 go.mod 的 module 声明中显式包含 /v2（或更高）后缀，这是硬性规则，不是建议。不改路径会导致 go build 报错：invalid version: module contains a go.mod file, so major version must be compatible: should be v0 or v1, not v2。
- 旧版
go.mod：module example.com/mymodule - 新版
go.mod：module example.com/mymodule/v2 - 路径变更后，所有导入语句也必须同步更新，例如从
import "example.com/mymodule"改为import "example.com/mymodule/v2" - Git 分支建议单独建
v2分支开发，避免污染main（v1）分支
代码迁移不能只靠全局替换，要分层验证
单纯用 IDE 全局替换导入路径，大概率漏掉隐式依赖或内部子包引用。尤其当模块内有 internal/ 或跨子目录调用时，容易出现编译通过但运行 panic 的情况。
- 先确保新路径下所有子包能独立
go test ./...通过 - 检查是否有代码通过反射、字符串拼接等方式动态构造包路径（如
plugin.Open或配置驱动加载） - 若模块提供 HTTP handler 或 CLI 命令，需验证其注册路径、路由前缀、flag 名称是否因版本变更被误改
- 对外暴露的接口类型（如
type Config struct）若被下游直接实例化，字段增删可能引发 silent failure，建议加// +build ignore注释或临时启用-gcflags="-d=checkptr"辅助排查
replace 不是升级手段，而是过渡期临时方案
replace 写在 go.mod 里，只是让当前模块“假装”用了新版本，实际并未发布、也未改变导入路径。它适合本地联调，但绝不能作为正式升级流程的一部分。
Golang Uber Dig
下载
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
- 上线前必须删除所有
replace行，否则下游无法正确拉取真实 v2 版本 - CI 流程中应添加检查：
grep -q "replace" go.mod && exit 1，防止误提交 - 如果依赖链中多个模块都需升级 v2，不要逐个
replace，而应统一推进主模块路径变更，再用go mod tidy自动收敛 -
go.work是更干净的本地协同方案，比replace更易维护，但仅适用于开发阶段，不可提交到生产构建环境
兼容性陷阱：v1 和 v2 可以共存，但别指望自动 fallback
Go 允许 example.com/mymodule（v1）和 example.com/mymodule/v2 同时存在于一个项目中，工具链会按需分别解析。但这不意味着你能“悄悄升级一部分”，反而容易埋下隐性冲突。
立即学习“go语言免费学习笔记（深入）”；
- 两个版本的同名类型（如
v1.User和v2.User）完全不兼容，哪怕结构一致，也不能直接赋值或传参 - 若某中间依赖仍硬编码引用 v1，而你的主模块用了 v2，
go list -m all会显示两套版本并存，但运行时行为取决于具体调用路径，极难调试 - 补丁移植时，别直接 cherry-pick v1 的 commit 到 v2 分支——函数签名、错误类型、上下文传递方式很可能已变，必须人工重审逻辑
go.mod 修改开始，到所有上下游确认兼容为止的一整条链。 
