URL路径嵌入版本号（如/v1/users）是Gin项目唯一推荐方案，因RouterGroup("/v1")确保路由前缀继承、监控打标准确、OpenAPI文档可分组；需物理隔离v1/v2 handler、结构体与service，正确挂载中间件，并通过响应头、410状态码及监控联动下线v1。
URL 路径嵌入版本号（如 /v1/users）是 Gin 项目里唯一值得默认采用的方案，其他方式在真实部署中都容易出运维、缓存或调试问题。
为什么必须用 RouterGroup("/v1") 而不是解析 Accept 头
HTTP header 方案表面简洁，实际在 CDN、Ingress、gRPC-gateway 或浏览器直调时会静默失效。比如 Nginx 默认不透传 X-API-Version，curl http://localhost:8080/users 不带 header 就直接 fallback 到未知版本；OpenAPI 工具也无法按 header 自动分组生成文档。而 r.Group("/v1") 注册后，所有子路由天然继承前缀，router.Walk() 能清晰看到路径树，Prometheus 的 http_request_duration_seconds{path="/v1/users"} 也能准确打标。
GET("/v1/users") 和 GET("/v2/users") 的 handler 必须物理隔离
别写一个 GetUsers(c *gin.Context, version string) 然后 if-else 分流——这会让单元测试难覆盖、灰度发布无法单独切流、v1 下线时还得全局 grep 函数名。应该：
- 目录结构按版本拆：
handlers/v1/user.go和handlers/v2/user.go - 每个 handler 只 import 对应版本的 service 包，如
service/v1或service/v2 - 响应结构体完全独立：
UserRespV1和UserRespV2，字段增减互不影响 JSON 序列化 - 共用逻辑下沉到 domain 层，比如
userDomain := svc.GetUser(id)返回领域模型，再由各自 toResponseV1()/toResponseV2() 转换
中间件挂载顺序错位会导致 v1/v2 权限失控
Gin 的中间件只作用于其所属 Group 及子路由。常见错误：
立即学习“go语言免费学习笔记（深入）”；
- 把鉴权中间件只注册在
v2 := r.Group("/v2")里，结果/v1/请求完全绕过校验 - 在
r.GET("/v1/:id", handler)这种根路由上提前注册了通配 handler，导致v1.Group("/users")下的所有子路由全部 404 - 日志或 trace 中间件没挂到根
r上，v1/v2 指标就无法聚合对比
正确做法：通用中间件（如 logger、recovery）一律注册在根 r.Use(...)；版本专属中间件（如 v2 强制 JWT、v1 兼容 session）才挂到对应 Group 内部。
废弃 v1 接口不能只靠文档，得靠响应头和监控联动
下线前必须让客户端可感知、服务端可追踪：
- 在 v1 handler 开头加
c.Header("X-API-Deprecated", "true")和c.Header("X-API-Deprecation-Date", "2026-12-01") - 配合 Prometheus 抓取
http_request_total{path=~"/v1/.*", status="200"}，观察调用量是否归零 - 返回 410 Gone（而非 404）明确表示资源永久不可用，避免客户端无限重试
最易被忽略的是：v1 handler 里用了 v2 的 DTO 结构体，或 JSON tag 里混用 omitempty 控制字段输出——这会让 v1 响应意外包含 v2 字段，前端解析直接 panic。
