路径前缀式版本路由（/v1、/v2）是唯一能长期稳定维护的方案；其他方式会破坏缓存、监控、调试与文档能力，且DTO必须按版本严格隔离，中间件和路由需分组独立注册。
/v1、/v2）是唯一能长期稳定维护的方案；其他方式在真实项目中会快速暴露可观测性、缓存和调试成本。
为什么不能用 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 或 gorilla/mux.PathPrefix 分组注册的关键细节
分组本身不难，但几个边界条件容易踩坑：
Golang Uber Dig
下载
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
- 中间件必须按组注册：
v1.Use(authV1Middleware)和v2.Use(authV2Middleware)不能共用一个中间件实例，v2可能新增双因素校验逻辑 - 路径注册要严格对齐：如果
v2.GET("/users/:id", handler)，那v1组里就不能漏掉v1.GET("/users/:id", legacyHandler)，否则/v1/users/123会 404 - 不要在分组里嵌套分组：
v1.Group("/admin").GET("/users", )会导致最终路径变成/v1/admin/users，而你实际想复用的是/admin/users的权限逻辑——此时应抽离中间件，而非嵌套路由 -
r.Group("/v1")注册后，handler 中调用c.Request().URL.Path拿到的是完整路径（如/v1/users），别用strings.HasPrefix(c.Request().URL.Path, "/v1")再判断版本，这是冗余且易错的
DTO 结构体必须按版本隔离，哪怕字段完全一样
Go 的 JSON 序列化没有运行时 schema 校验，共用 struct 是最隐蔽的兼容性炸弹：
- 给
UserV2加了Nickname string `json:"nickname"`，如果v1handler 不小心用了UserV2{}返回，v1客户端 JSON 解析就会 panic（字段不存在或类型不匹配） - 别用指针“模拟可选字段”来凑合老版本：
v1的Name string是必填，就该是string；v2改成Name *string是它的契约，不能反向污染v1 - 数据库模型（如
GORMUserModel）保持稳定，只负责存储；所有 API 层响应都必须经由对应版本的 DTO 转换，不能直吐 domain model
omitempty 的误用、一个未更新的 @success 注释，就可能让 v1 客户端在某次发布后静默失败。 
