URL路径嵌入版本号（如/v1/users）是Gin项目唯一值得默认采用的方案，因r.Group("/v1")确保路由可读、中间件按组启用、反向代理匹配准确、OpenAPI文档自动生成、物理隔离版本逻辑、中间件挂载正确、废弃接口可监控追踪且数据库变更需兼容。
URL路径嵌入版本号（如/v1/users）是 Gin 项目里唯一值得默认采用的方案，其他方式在真实部署中容易出运维、缓存或调试问题。
为什么r.Group("/v1")比硬拼路径更可靠
直接写r.GET("/v1/users", handler)看似省事，但会导致路由树不可读、中间件无法按组启用、反向代理前缀匹配失效。用r.Group("/v1")能确保整个子路由天然继承前缀，router.Walk()可清晰看到分组结构，Prometheus指标也能准确打标http_request_duration_seconds{path="/v1/users"}。
- 硬编码路径时，
/v1不是“边界”，只是字符串；Group让框架明确知道这是版本隔离单元 - Nginx 的
location /v1/规则只对真实路径前缀生效，不会匹配/users/v1 - OpenAPI 工具（如 swaggo）依赖 Group 结构生成分组文档，否则
@version注释会失效
GetUserV1()和GetUserV2()必须物理隔离
别写一个GetUser(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，字段增减互不影响 - 共用逻辑下沉到 domain 层，比如
userDomain := svc.GetUser(id)返回领域模型，再由各自toResponseV1()/toResponseV2()转换
中间件挂载顺序错位会导致/v1裸奔
Gin 的中间件只作用于其所属 Group 及子路由。常见错误是把鉴权中间件只注册在 v2 := r.Group("/v2") 里，结果 /v1/ 请求完全绕过校验；或者在 r.GET("/v1/:id", handler) 这种根路由上提前注册通配 handler，导致 v1.Group("/users") 下的所有子路由全部 404。
- 通用中间件（如
logger、recovery）一律注册在根r.Use() - 版本专属中间件（如 v2 强制 JWT、v1 兼容 session）才挂到对应 Group 内部
- 日志或 trace 中间件没挂到根
r上，v1/v2指标就无法聚合对比
下线/v1不能只靠文档，得靠410和监控联动
废弃接口必须让客户端可感知、服务端可追踪。只改文档或删代码，旧客户端会静默失败或返回 500。
- 在
v1handler 开头加c.Header("X-API-Deprecated", "true")和c.Header("X-API-Deprecation-Date", "2026-12-01") - 配合 Prometheus 抓取
http_request_total{path=~"/v1/.*"}，观察调用量衰减趋势 - 正式下线时返回
410 Gone（不是404），并附带迁移指引链接
最易被忽略的是：版本升级后，数据库 schema 变更必须对齐——比如 v2 加了 NOT NULL 字段，v1 接口不能因此返回 500，得在 service 层兜底或做兼容转换。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
