路径前缀式版本控制（/v1/、/v2/）是Go服务中最可靠、最易落地的方案，因其天然支持路由隔离、O(1)匹配、客户端可感知、CDN/缓存友好；Header或query方式易致缓存污染、调试困难、性能下降且违反HTTP缓存规范。
路径前缀分组是唯一可靠起点，别绕开它去搞 header 或 query 参数解析
为什么必须用 /v1 和 /v2 路径前缀
URL 路径版本号不是“可选风格”，而是 Go Web 框架路由机制的硬性适配点。所有主流框架（gin、echo、chi、gorilla/mux）的 Group 或 Mount 功能都依赖前缀做 O(1) 路由匹配——这意味着不走字符串 strings.HasPrefix 或正则，性能无损耗。
- CDN、Nginx、API 网关能直接按路径分流，
X-API-Version头在大多数网关里被忽略或需额外配置 Vary - OpenAPI 文档生成工具（如
swag）靠路由路径识别版本切片，header 版本会导致 v1/v2 接口混在同一文档页 - 移动端 SDK 日志聚合、监控打标、灰度发布都依赖 URL 可见字段；query 参数（如
?version=v2）无法被 CDN 缓存，且易被客户端误删
gin.Group 和 chi.Mount 的关键差异与陷阱
不同框架的“分组”语义不等价，错用会引发中间件污染或路由丢失。
Golang Uber Dig
下载
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
-
gin.Group("/v1")：子路由注册后，r.GET("/users", handler)实际匹配的是/v1/users，handler 内c.Request.URL.Path仍是完整路径；中间件自动继承，适合统一日志/panic recover -
chi.Mount("/v2", v2Router)：v2Router是独立路由器，其内部r.Get("/users", ...)匹配的是/v2/users，但 handler 中r.URL.Path已剥离前缀（即/users），且父 router 的中间件默认不继承——这是故意设计，避免 v1 的 JWT 校验逻辑意外跑到 v2 里 - 常见错误：在
chi中写r.Get("/v1/users", ...)而非用Mount，这会让路由树失去层级，v1/v2 中间件无法隔离，后续加 v3 时重构成本爆炸
结构体不能共用，哪怕字段一模一样
Go 的 JSON 序列化对字段标签（json:）、零值行为、指针可空性极其敏感。v1 客户端收到 v2 新增字段会直接解析失败，尤其前端用 JSON.parse() 时静默丢数据。
立即学习“go语言免费学习笔记（深入）”；
- 必须定义
UserV1和UserV2两个 struct，即使当前字段名和类型相同 - 字段变更示例：
UserV1.Name string→UserV2.Name *string，不能靠omitempty“模拟兼容”，因为 v1 客户端不理解null字段 - 数据库 model 层（如 GORM struct）保持稳定，API 层用
mapstructure.Decode或手动赋值做 domain → DTO 转换，禁止 handler 里直接return dbUser - Swagger 注释必须绑定到对应 Group：在
v1.Group下写// @Success 200 {object} UserV1，否则swag init会把 v2 字段也塞进 v1 文档
版本下线时最常被忽略的三件事
下线不是删代码，而是留出缓冲期让客户端自然过渡。很多团队卡在这一步导致线上报错激增。
- HTTP 响应头加
Deprecation: true和Link: <https:>; rel="successor-version"</https:>，主流 HTTP 客户端（如 axios、OkHttp）可自动捕获并告警 - 在 v1 handler 开头加统计埋点：
metrics.Inc("api.v1.users.deprecated")，当调用量周环比下降 >95% 时才真正删路由 - 禁止删除
handlers/v1/目录——保留空 handler 返回410 Gone并带迁移指引，比404更明确告诉客户端“此路已废”
