最稳妥的API版本控制方案是URL路径嵌入版本号（如/v1/users），通过框架Group()分组路由实现物理隔离，而非query参数或Accept头；需结构体、中间件、文档、监控全版本切片，避免混写逻辑。
URL 路径带版本号是最稳妥的方案，别折腾 query 或 Accept 头——调试难、缓存错、网关不认、日志聚合失效。
用 Group() 分离路由，而不是靠字符串解析
所有主流 Go Web 框架（gin、echo、chi、gorilla/mux）都支持显式分组，这是唯一能天然隔离中间件、文档、监控和部署单元的方式。
-
gin：直接r.Group("/v1")，别写r.GET("/v1/users", ...)—— 后者丢失分组语义，中间件无法按版本启用 -
chi：必须用r.Mount("/v2", v2Router)，Mount不继承父中间件，避免 v1 的日志中间件意外跑到 v2 里 -
gorilla/mux：用r.PathPrefix("/v1").Subrouter()，再注册 handler；别在 handler 里手动strings.HasPrefix(r.URL.Path, "/v1")—— 子路由器已剥离前缀，r.URL.Path是/users，不是/v1/users - 每个
Group或Subrouter应挂专属中间件：比如 v2 加JWT强校验，v1 保留 session 兼容，互不影响
结构体必须按版本拆开，不能共用 User
字段增减、可选性变化、tag 差异（如 omitempty）会让 JSON 序列化崩掉。v1 客户端收到 v2 新字段，前端解析直接报错。
- 定义
UserV1和UserV2两个 struct，即使当前字段一样也分开声明 - v1 的
Name是string，v2 改成*string或加Nickname string—— 别用指针“模拟”旧结构，那只是掩盖问题 - 数据库 model（如 GORM struct）保持稳定，只做存储；API 层靠手动赋值或
mapstructure做 domain → DTO 转换 - Swagger 注释（如
@Success 200 {object} UserV1）必须绑定到对应 Group，否则 v1 文档里混进 v2 字段
别写 getUsersV1() 这种函数名
函数名带版本号会污染业务语义，阻碍重构。v1 下线时你得改所有调用点，IDE 重命名还容易漏。
Golang Uber Dig
下载
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
- 按目录隔离：
handlers/v1/user.go和handlers/v2/user.go，各自 importservice/v1或service/v2 - handler 函数统一叫
GetUsers，靠路由层分发，不是靠名字暗示行为 - 如果底层 service 逻辑一致，可以复用
service.GetUserByID()，但返回后必须转成对应版本的 DTO 再序列化 - 禁止在 handler 里写
if version == "v2" { ... }—— 灰度发布、单独回滚、独立打监控指标全失效
X-API-Version 头只适合兜底，且必须由中间件注入 context
它不是替代方案，而是给老 SDK 或无法改 URL 的客户端留的逃生通道。一旦用了，就得承担代理丢 header、curl 测试失效、CDN 缓存错乱的风险。
立即学习“go语言免费学习笔记（深入）”；
- 中间件里统一解析：
v := c.GetHeader("X-API-Version")，校验白名单（"v1","v2"），非法值直接c.AbortWithStatusJSON(400, ...) - 解析结果必须写入
c.Request.Context()：ctx = context.WithValue(c.Request.Context(), keyVersion, v)，后续 handler 用c.Request.Context().Value(keyVersion)取，别重复解析 - 优先级必须明确定义：比如
Accept>X-API-Version，并在 OpenAPI 文档里写死 - gRPC-Gateway 场景下，需在 gateway 配置中显式声明转发该 header，否则透传不到 gRPC metadata
