/v1路径前缀是go微服务api版本控制最稳妥方案，因其在nginx、envoy等基础设施中表现一致，支持路由隔离、缓存友好、调试直观；header或query方式易导致中间件丢弃、缓存污染与灰度失控。
不推荐用自定义请求头管理 API 版本，除非你已明确接受它带来的调试、网关、缓存和灰度风险。 它看起来“更 RESTful”，但实际落地时，X-API-Version 或 Accept 头方式在 Go 微服务中容易出问题，且修复成本远高于路径前缀方案。
为什么 X-API-Version 头在生产环境容易失效
自定义 header 最常被丢弃的环节不是你的 Go 代码，而是中间链路：
- Nginx 默认不透传未显式声明的 header，
underscores_in_headers off还可能让X_Api_Version直接被忽略 - Kubernetes Ingress（尤其是 nginx-ingress）需手动配置
nginx.ingress.kubernetes.io/configuration-snippet才能透传X-API-Version - Envoy 或 APISIX 网关默认只透传白名单 header，
X-API-Version不在其中 - HTTP/2 下某些代理会静默剥离未知 header，连 400 错误都不报
- cURL、浏览器开发者工具、Postman 默认不带该 header，测试时永远 fallback 到 v1
如果必须用 X-API-Version，Go 里怎么写才不至于线上崩
不能靠一个中间件全局解析后塞进 context 就完事。每个 endpoint 的版本支持范围可能不同（比如 /health 只有 v1，/orders 已上线 v3），必须按路由粒度校验：
- 用
c.GetHeader("X-API-Version")获取值，别用c.Request.Header.Get()—— gin 的GetHeader会自动 normalize 大小写 - 必须
switch显式枚举合法值，禁止if strings.HasPrefix(v, "v")这类宽松判断 - 对不支持的版本，返回
406 Not Acceptable（不是 400），符合 RFC 7231 对 version negotiation 的语义 - 在 handler 开头做校验，不要依赖 middleware 统一处理 —— 否则 /v1/orders 和 /v3/orders 共享同一中间件时逻辑会错乱
func ordersHandler(c *gin.Context) {
v := c.GetHeader("X-API-Version")
switch v {
case "v1":
handleOrdersV1(c)
case "v3":
handleOrdersV3(c)
default:
c.AbortWithStatusJSON(406, gin.H{"error": "version not supported"})
return
}
}
Accept: application/vnd.myapi.v2+json 比 X-API-Version 更坑在哪
这个方案名义上“标准”，但实际更难维护：
- 浏览器地址栏直接访问
/users时，Accept是text/html,*/*，永远触发 fallback - Swagger UI 默认不发该 header，文档里点 “Try it out” 调用的其实是 v1
- Go 标准库
net/http的ParseAccept不支持 vendor type 解析，得自己写正则或用第三方包（如go-restful/v3） - CDN 和反向代理通常忽略
Accept做缓存键，导致 v1 和 v2 响应互相污染 - 客户端 SDK 必须强制封装 header 设置，漏传一次就回归旧版，而你日志里根本看不出是哪个 client 漏了
真正需要 header 方案的场景极少：比如已有千万级存量客户端无法改 URL，且你有能力控制全部中间链路透传、监控 header 丢失率、为每个 endpoint 单独写版本路由逻辑。否则，老老实实用 /v1/users —— 路径里的版本号，debug 时一眼可见，curl 时一加就生效，网关配置时一条正则就能路由，这才是工程上没废话的解法。
大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！
