URL路径嵌入版本号（如/v1/users）是最可靠方案，需用Group/Subrouter物理隔离路由、中间件、监控与文档；DTO结构体须按版本拆分；Swagger注释绑定对应Group；版本判断必须在路由层而非handler内。
URL路径嵌入版本号（如/v1/users）是最可靠、最可维护的方案，别在query或header里折腾——调试难、缓存错、网关不认、日志聚合失效。
用Group()或Subrouter()做物理隔离，别手写/v1前缀
路由分组不是语法糖，是隔离中间件、监控、文档和部署单元的唯一手段。手动拼接路径（比如r.GET("/v1/users", handler)）会让v1/v2共享同一组中间件，也导致Swagger无法按版本生成正确schema。
-
gin：必须用v1 := r.Group("/v1")，再在block里注册v1.GET("/users", ...)；别把/v1硬写进每个GET路径 -
chi：用v2 := chi.NewRouter()+r.Mount("/v2", v2)；Mount不继承父中间件，避免v1的日志逻辑污染v2 -
gorilla/mux：用v1 := router.PathPrefix("/v1").Subrouter()；注册handler时路径写/users，不是/v1/users——子路由器已剥离前缀，r.URL.Path拿到的是干净的/users
结构体必须按版本拆开，哪怕字段当前一模一样
共用User struct是埋雷：v2加个Nickname string，v1客户端JSON解析直接panic；v1的Name string改成v2的Name *string，前端判空逻辑全崩。
- 定义
UserV1和UserV2两个独立struct，即使字段名、类型、tag都相同 - 数据库model（如GORM struct）保持稳定，只做存储；API层靠手动赋值或
mapstructure.Decode做domain → DTO转换 - Swagger注释（如
@Success 200 {object} UserV1）必须绑定到对应Group，否则v1文档里混进v2字段
禁止在handler里写if version == "v2"分支
这种写法让灰度发布、单独回滚、独立打监控指标全部失效。版本判断必须落在路由层，而不是业务逻辑里。
立即学习“go语言免费学习笔记（深入）”；
- handler函数名统一叫
GetUsers，靠路由分发，不靠名字暗示行为 - 底层service逻辑一致时，可复用
service.GetUserByID()，但返回后必须转成对应版本DTO再序列化 -
X-API-Version头只作为兜底，且必须由中间件注入context——它不是替代方案，而是给老SDK或无法改URL的客户端留的逃生通道
最容易被忽略的一点：版本不是“加个前缀就完事”，而是从路由、中间件、DTO、文档、监控到日志聚合的全链路切片。v1下线那天，你删掉handlers/v1/目录和r.Group("/v1")注册就行，不需要grep整个代码库找if version == "v1"。
