Go中API版本控制需显式体现SemVer意图：URL路径用/v1、/v2前缀对应主版本号，确保契约兼容；各版本使用独立DTO结构体；模块路径须带/v2后缀以支持共存；禁用查询参数或请求头方式。
Go 本身不提供 API 版本控制的运行时机制，语义化版本（SemVer）在这里主要起两个作用：一是约束模块依赖行为（go.mod 中的 v1.2.3），二是指导你如何设计和演进 HTTP 接口。真正落地 API 版本管理，得靠你在路由、数据结构和发布流程中显式体现 SemVer 意图。
URL 路径前缀必须用 /v1、/v2 这种格式
这是最直接、最可维护的做法。路径里的 v1 不是随便写的字符串，它对应 SemVer 的主版本号 —— 意味着该路径下所有接口契约（请求/响应字段、状态码、错误格式）承诺向下兼容，直到你升级到 /v2。
- 别用
?version=v2：CDN 缓存失效、日志聚合困难、Prometheus metrics 无法按版本切分 - 别用
X-API-Version: v2：curl 测试要加头、浏览器直访不可用、OpenAPI 文档生成器难识别版本边界 - 用
gorilla/mux或chi的子路由注册，例如v1 := router.PathPrefix("/v1").Subrouter()，确保路由树清晰可见 -
/v2不代表“功能更多”，而是“契约变更”——哪怕只改了一个字段类型或删除一个可选字段，就该升 v2
每个版本必须定义独立的 DTO 结构体
共用一个 User struct 给 v1 和 v2 用，是导致 JSON 响应意外泄露字段的根源。v1 客户端解析 {"id":1,"name":"a","created_at":"..."} 会 panic，如果它没定义 CreatedAt 字段且没忽略未知字段。
- 为每个版本声明专属结构体：
V1User、V2User，即使字段名和类型目前完全一样 - 在 handler 末尾做显式转换：
json.NewEncoder(w).Encode(V1User{...})，而不是传 domain model 直接 encode - 避免依赖
json:",omitempty"隐式控制输出 —— v2 新增字段设零值时，v1 响应可能漏掉本该存在的旧字段 - 如果用 Swagger，
components/schemas必须按版本拆开，否则 UI 渲染会混淆字段归属
go.mod 中的模块路径要带 /v2 后缀才能共存
当你把 SDK（比如 user-client）拆成独立模块供其他服务调用时，v1 和 v2 必须能同时存在。Go 不允许同一路径下有两个主版本，所以路径本身就得体现 SemVer。
立即学习“go语言免费学习笔记（深入）”；
- 发布 v2 SDK：打 tag
v2.0.0，并把go.mod中的module改为github.com/yourorg/user-client/v2 - 调用方 import 必须写全：
import "github.com/yourorg/user-client/v2"，不能省略/v2 - Go 工具链会把
/v1和/v2视为完全不同的包，不会冲突，也不强制升级 - 别只打 tag 却不改 import 路径 —— 这样
go get仍会拉取最新版，破坏 v1 调用方
中间件里动态解析路径版本号是反模式
有人想写个通用中间件，从 r.URL.Path 提取 v1 或 v2，再塞进 context，最后让 handler 自己判断逻辑分支。这看似灵活，实则埋雷。
- 路由注册变得不可见：
router.Walk()看不到实际绑定路径，调试和文档生成失效 - 无法做路径级灰度 —— 比如只放行
/v2/users的流量，而/v2/orders还走 v1 逻辑 - 中间件和 handler 耦合加深，测试成本上升；一个版本的 bug 可能污染另一个版本的上下文
- 真有老客户端不能改 URL？用 Envoy/Nginx 在入口层 rewrite，保持 Go 服务内部路由干净
最易被忽略的一点：版本升级不是代码改完就结束，而是要同步更新 OpenAPI 文档、验证旧客户端是否真的不受影响、确认 go.sum 中依赖项的 SemVer 兼容性 —— 尤其当你的服务又依赖了其他带 /v2 路径的模块时。
