go v2+模块路径后缀必须带v2、v3等，且需同步重命名目录、更新go.mod和所有import语句；url path优于accept header承载版本号；go get失败需检查goproxy、缓存与go.sum；v1/v2并存时须显式replace锁定版本。
Go v2+ 模块路径后缀必须带 v2、v3 等，不能只改 go.mod 里的模块名
很多人以为只要在 go.mod 中把模块路径改成 example.com/myapi/v2 就算完成版本升级，其实不够。Go 的模块系统依赖路径后缀做版本识别和导入隔离——import 语句里写的路径，必须和磁盘上实际的目录结构一致。
常见错误现象：go build 报错 cannot find module providing package example.com/myapi/v2，或者 v2 包能 import 但内部引用的 v1 子包仍走旧路径。
- 模块根目录必须重命名为
v2（如从myapi/改为myapi/v2/） -
go.mod中的module行要同步更新为example.com/myapi/v2 - 所有内部
import语句中对同模块其他包的引用，也要加上/v2前缀（例如example.com/myapi/v2/handler） - 如果项目有
go.work，需确保其中包含的是v2目录，而非顶层目录
API 路由版本号该放在 URL path 还是 Accept header？
Go 里用 gorilla/mux、gin 或 net/http 自建路由时，路径级版本（如 /v2/users）比内容协商更可靠、更易调试、更利于网关和 CDN 缓存。
Accept header 方案（如 Accept: application/vnd.myapi.v2+json）理论上更“RESTful”，但实践中容易出问题：
立即学习“go语言免费学习笔记（深入）”；
- 前端 JS fetch 默认不设
Accept，常 fallback 到application/json，导致意外调用 v1 - Postman、curl 测试时容易漏配 header，查问题绕一圈才发现是协商失败
- OpenAPI 文档生成工具（如
swag）对 header 版本支持弱，v2 接口文档常被合并或覆盖 - 反向代理（Nginx、Envoy）按 path 做路由分发更直观，按 header 分发需额外配置且难 audit
所以推荐：URL path 放版本号，Accept 只用于格式协商（json/protobuf），不承载主版本语义。
go get example.com/myapi/v2 失败？检查 GOPROXY 和 go.sum 是否污染
即使代码已按规范组织好 v2 目录和 go.mod，go get 仍可能失败，核心原因是 Go 模块缓存或校验机制对后缀版本敏感。
典型错误信息：unrecognized import path "example.com/myapi/v2": parse https://example.com/myapi/v2?go-get=1: no go-import meta tags，或 verifying example.com/myapi/v2@v2.0.1: checksum mismatch。
- 确认
GOPROXY没被设成私有代理但未支持/v2路径重写（某些老旧 Nexus/Artifactory 配置会丢弃后缀） - 删掉本地
go/pkg/mod/cache/download/example.com/myapi/@v/下所有v2相关缓存再试 - 检查
go.sum中是否混入了v1版本的哈希，手动删掉涉及v2的行，再go mod tidy - 若用私有 Git 仓库，确保 tag 名是
v2.0.1（不是2.0.1），且仓库根路径支持go get的go-import元标签
兼容 v1 和 v2 并存时，别让 go list -m all 拉错版本
当项目同时依赖 example.com/myapi（v1）和 example.com/myapi/v2（v2），Go 工具链默认按主模块声明决定“主版本”，但子依赖可能被升/降级，导致运行时行为不一致。
比如 v2 包里调用了某个工具函数，而该函数在 v1 的 example.com/myapi/internal/util 里定义——此时 Go 不允许跨版本复用 internal 包，但若没显式约束，go list -m all 可能显示 v1 的模块被 v2 替换，引发静默错误。
- 在 v2 模块中，所有原本来自 v1 的公共逻辑，必须复制或重构，不能直接 import v1 的
internal或非版本化路径 - 用
replace在go.mod中显式锁定 v1 版本，防止间接依赖被升级：replace example.com/myapi => example.com/myapi v1.5.2 - CI 中加一步
go list -m all | grep 'example.com/myapi'，确保输出里明确列出v1和v2两个条目，而不是只有一个
路径后缀不是命名习惯，是 Go 模块系统的硬性隔离边界。跨版本共享代码、复用 internal 包、省略目录重命名，都会在某次 go mod tidy 后突然崩掉，而且报错位置和原因常常不直接相关。
