应使用 Accept-Version 字段命名API版本，因其符合RFC 7231语义、中间件友好且避免Nginx等代理丢弃；X-API-Version易被静默过滤，version类无前缀名称易冲突。
Header 中的 API 版本字段怎么命名才不踩坑
直接用 X-API-Version 或 Accept-Version 是常见选择，但实际部署时容易和反向代理（如 Nginx、Envoy）或网关（如 Kong、APISIX）的 Header 过滤规则冲突。Nginx 默认会 strip 掉下划线开头或含下划线的 Header，X-API-Version 就可能被静默丢弃；Kong 的默认策略则对 Accept-* 类 Header 更友好。
推荐统一用 Accept-Version，它符合 RFC 7231 对 Accept 系列 Header 的语义约定，且多数中间件默认放行。避免用 version、api-version 这类无前缀的名称——Gin 的 c.GetHeader() 对大小写不敏感，但某些负载均衡器会强制小写化，导致匹配失败。
-
Accept-Version: v1✅ 明确、兼容性好、中间件友好 -
X-API-Version: 1.0⚠️ Nginx 可能丢弃，需额外配置underscores_in_headers on -
version: v2❌ 无命名空间，易被覆盖或误匹配
Gin 路由层如何按 Header 版本分流
别在每个 handler 里重复写 c.GetHeader("Accept-Version") 判断——既难维护，又无法做统一版本降级或拒绝旧版逻辑。正确做法是用 Gin 的 RouterGroup + 中间件提前解析并挂载版本上下文。
示例：注册一个全局中间件，在请求进入路由前就提取并验证版本，非法版本直接返回 400 或 406 Not Acceptable：
立即学习“go语言免费学习笔记（深入）”；
func versionMiddleware() gin.HandlerFunc {
return func(c *gin.Context) {
version := c.GetHeader("Accept-Version")
switch version {
case "v1":
c.Set("api_version", "v1")
case "v2":
c.Set("api_version", "v2")
default:
c.AbortWithStatusJSON(406, gin.H{"error": "unsupported version"})
return
}
c.Next()
}
}
后续 handler 只需 c.GetString("api_version") 获取，无需重复解析。注意：不要用 c.Param 或 c.Query 混合版本标识——Header 是语义更准确的协商方式，Query 参数更适合调试或临时绕过。
v1 和 v2 的 handler 怎么组织才利于长期维护
别把 v1 和 v2 的逻辑硬塞进同一个函数里靠 if/else 分支处理。随着版本增多，分支爆炸、测试覆盖难、回滚成本高。Gin 本身不提供“版本路由组”，但可以用子 router + 命名空间模拟：
apiV1 := r.Group("/api")
apiV1.Use(versionMiddlewareFor("v1")) // 专用中间件只放行 v1
{
apiV1.GET("/users", v1.GetUserList)
apiV1.POST("/users", v1.CreateUser)
}
apiV2 := r.Group("/api")
apiV2.Use(versionMiddlewareFor("v2"))
{
apiV2.GET("/users", v2.GetUserList)
apiV2.POST("/users", v2.CreateUser)
}
关键点：
- 每个版本对应独立的 handler 包（如
v1/和v2/目录），结构隔离 - 共用模型尽量抽到
shared/或model/，但绝不复用 handler 层逻辑 - 版本中间件必须严格校验值，不能 fallback 到默认版本——显式拒绝比隐式降级更安全
测试不同版本请求时最容易漏掉的兼容性问题
本地用 curl 测试 curl -H "Accept-Version: v2" http://localhost:8080/api/users 成功，不代表线上没问题。真实环境常因以下原因失效：
- Nginx 配置未开启
underscores_in_headers on，导致X-API-Version被丢弃，Gin 收不到任何值 - Kubernetes Ingress 控制器（如 nginx-ingress）默认 strip 非标准 Header，需显式配置
nginx.ingress.kubernetes.io/configuration-snippet - 前端 Axios/Fetch 默认不发送自定义 Header，需设置
credentials: 'include'或显式headers: { 'Accept-Version': 'v2' } - Gin 的
engine.NoRoutehandler 未检查版本上下文，导致 404 错误掩盖了版本不匹配问题
真正可靠的测试方式：在 CI 中用 net/http 构造带 Header 的请求，断言响应状态码和 body 结构，而不是只测单个 handler 函数。
