模块升级必须显式指定/vN路径，因v2+被视为全新模块；go get -u默认不跨主版本，需用go get github.com/example/lib/v2@latest等命令；不同主版本路径隔离，可共存并独立维护。
模块升级必须显式指定/vN路径，否则不会跨主版本
Go 模块语义化版本规定：v2+ 被视为全新模块，不是旧模块的“升级版”。go get -u 默认只升到当前主版本内最新次版本（如 v1.9.3 → v1.10.0），绝不会自动跳到 v2.x。如果你强行运行 go get -u github.com/example/lib，它永远卡在 v1.x，哪怕 v2.0.0 已发布。
真正要启用新版本，必须显式写全路径：
-
go get github.com/example/lib/v2@latest—— 升级到 v2 最新 tag -
go get github.com/example/lib/v3@v3.2.1—— 锁定具体小版本 -
go mod edit -replace github.com/example/lib=../local-fork—— 临时替换调试用，上线前务必删掉
漏写 /v2 是最常见失败原因：编译能过，但 import 语句仍指向旧版，实际没生效。
旧接口保留靠包隔离，不是靠 if version == "v2"
同一模块不同主版本在 Go 中是完全独立的导入路径：github.com/example/lib 和 github.com/example/lib/v2 是两个包，可共存、可同时 import。这才是平滑升级的基础设施。
立即学习“go语言免费学习笔记（深入）”；
不要试图在一个包里用条件分支支持多版本逻辑：
初始化并管理阿里云SDK Go 客户端，涵盖 sync.Once 单例、goroutine 安全、endpoint 与 region 配置、VPC 端点及调试。
- ❌
if cfg.Version == "v2" { ... }—— 部署、灰度、回滚全部失效 - ✅ 正确做法：v1 接口由
github.com/example/lib提供，v2 接口由github.com/example/lib/v2提供，各自独立维护、测试、部署 - v2 包内可复用 v1 的底层工具函数（通过 internal 或 utils 子包），但对外 API 必须全新设计
这种隔离让客户端能自主选择升级节奏：部分服务用 v1，新服务直接上 v2，互不干扰。
兼容性验证不能只靠编译通过
即使 v2 模块编译成功、单元测试全绿，也不代表平滑升级完成。关键风险在序列化/反序列化和运行时行为变更：
- Protobuf 升级后，若未保留
json_name或字段编号，旧客户端解析 JSON 响应会 panic - HTTP handler 返回结构体字段类型从
int改为int64，前端 JavaScript 可能误判为undefined - v2 新增必填字段，但旧客户端未传，导致 400 或静默丢数据
必须做契约测试（Contract Test）：用 v1 客户端请求 v2 服务，验证响应格式、状态码、字段存在性；反过来也跑一遍。工具可用 go-swagger 生成 client SDK + ginkgo 写断言，或直接用 Postman + Newman 脚本化。
go.mod 中的 replace 和 exclude 是临时止血，不是长期方案
开发中常用 replace 指向本地修改版，或 exclude 屏蔽有冲突的间接依赖。但这些只是过渡手段：
-
replace不会被下游模块继承 —— 你的模块发布后，别人go get到的仍是原始版本 -
exclude可能掩盖真实兼容问题，比如某依赖 v1.5.0 与你代码冲突，但 v1.6.0 已修复，你却一直 exclude 而没升级 - 上线前必须删掉所有
replace和exclude，运行go mod tidy确认依赖树干净
真正稳定的升级，是让所有依赖都落在官方发布的、带 semver tag 的版本上。临时 hack 多留一天，线上就多一分不可控风险。
平滑升级最难的不是技术动作，而是确认「旧客户端是否真能无感消费新服务」——这需要接口契约、数据格式、错误码、超时策略全部对齐，而不是仅仅把 go.mod 里的数字改大一点。
