路径前缀式分组注册是Go实现API版本路由的唯一可靠方式，因它天然支持路由隔离、CDN缓存识别、监控指标按版本聚合、文档生成准确及调试直观；而query或header方案会破坏缓存、混淆监控、错乱文档并增加调试成本。
路径前缀式分组注册（gin.Group("/v1") 或 mux.PathPrefix("/v2").Subrouter()）是 Go 实现 API 版本路由的唯一可靠方式，其他方案会在缓存、监控、文档生成和调试中持续制造问题。
为什么不能用 version 查询参数或 Accept 头做主路由
看似灵活，实则破坏可观测性与运维链路：
-
curl https://api.example.com/users?version=v2无法被 CDN 缓存识别，同一 URL 下不同version值会打穿缓存 - Prometheus 指标
http_request_duration_seconds{path="/users"}会把 v1/v2 流量混在一起，查慢请求时根本分不清是哪个版本的问题 - Swagger UI 无法按版本生成独立文档——OpenAPI 的
components/schemas是全局作用域，v1 接口注释里一写V2User字段，v1 文档就直接显示错字段 - 浏览器直访、Postman 测试、Nginx 日志聚合全要额外解析 query 或 header，调试时得反复确认是不是漏传了
X-API-Version
gin.Group() 和 mux.PathPrefix().Subrouter() 的正确用法
分组本身不难，但几个边界条件容易踩坑：
Golang Uber Dig
下载
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
- 必须用
v1 := r.Group("/v1")，而不是r.GET("/v1/users", handler)——后者丢失分组语义，中间件无法按版本启用，router.Walk()也查不到真实结构 - gorilla/mux 下对应
v1 := r.PathPrefix("/v1").Subrouter()，不是r.HandleFunc("/v1/users", ...)；子路由器已剥离前缀，r.URL.Path在 handler 中是/users，不是/v1/users - 别在 handler 里手动
strings.HasPrefix(c.Request().URL.Path, "/v1")判断版本——这是冗余且易错的，路由树已不可见，CI 自动化检测就失灵 - 路径注册要严格对齐：如果
v2.GET("/users/:id", handler)存在，v1组里也得显式注册v1.GET("/users/:id", legacyHandler)，否则/v1/users/123直接 404
DTO 结构体必须按版本隔离，哪怕字段完全一样
Go 的 JSON 序列化没有运行时 schema 校验，共用 struct 是最隐蔽的兼容性炸弹：
立即学习“go语言免费学习笔记（深入）”；
- 给
UserV2加了Nickname string `json:"nickname"`，如果 v1 handler 不小心用了UserV2{}返回，v1 客户端 JSON 解析就会 panic - 别用指针“模拟可选字段”来凑合老版本：
v1的Name string是必填，就该是string；v2改成Name *string是它的契约，不能反向污染v1 - 数据库 model（如 GORM struct）保持稳定，只负责存储；API 层靠手动赋值或
mapstructure做 domain → DTO 转换 - handler 中必须显式转换：
c.JSON(200, V1User{})，不能传 domain model 直接 encode
最容易被忽略的是：版本号只用 v1、v2，不用 v1.2.3 或 v1.2——API 版本是契约变更，不是软件发布；而 Accept 头或 X-API-Version 只适合兜底，且必须由中间件统一注入 context，绝不能作为主路由逻辑。
