/v1路径前缀是最稳妥的api版本控制方式，因其在nginx、envoy等基础设施中表现一致；需为每版定义独立dto结构体并物理隔离handler，避免共用struct或if分支逻辑；header方案仅作兜底且须严格校验。
Go 微服务中 API 版本控制的“优雅”不在于理论多漂亮，而在于上线后日志能分清、灰度能切走、旧客户端不崩、新字段不漏——/v1 路径前缀是目前最可靠的选择，不是因为它最 RESTful，而是它在 Nginx、Envoy、Prometheus、Swagger 和 curl 里都表现一致。
用 /v1 和 /v2 做路径前缀是最稳妥的落地方式
所有主流 Go 路由器（gin、echo、chi、gorilla/mux）都原生支持按路径分组，无需额外解析逻辑。版本信息直接暴露在 URL 中，意味着：
- 反向代理（如 Nginx）可基于
location /v1/精确分流，无需重写或 header 透传 - CDN 和浏览器缓存能天然区分
/v1/users与/v2/users，避免 v1 客户端意外收到 v2 缓存 - 日志和监控（如 Prometheus 的
http_request_duration_seconds{path="/v1/users"}）可按版本聚合，慢请求定位不跨版本混淆 -
curl -v https://api.example.com/v2/users一行命令就能验证接口是否就绪，无需构造 header 或 query
别用 router.Get("/users", handler) 再靠中间件动态提取路径里的 v1——这会让 router.Walk() 看不到真实路由树，调试时查不到注册了哪些路径。
每个版本必须有独立的 DTO 结构体，不能共用 struct
版本差异最终落在 JSON 字段上：v1 的 User.Name 是必填字符串，v2 加了 Nickname 且 Name 变成可选。如果共用一个 type User struct，就会出现两种翻车：
- v2 新增字段被序列化进 v1 响应，前端 JSON 解析失败
- v1 的
json:"name"tag 被 v2 的json:"name,omitempty"覆盖，导致 v1 响应里name字段消失
正确做法是为每版定义专属 DTO：
type UserV1 struct {
ID int `json:"id"`
Name string `json:"name"` // 必填，无 omitempty
}
type UserV2 struct {
ID int `json:"id"`
Name *string `json:"name,omitempty"` // 指针显式表达可选
Nickname string `json:"nickname"`
}
handler 末尾必须显式调用 json.Marshal(UserV1{...})，而不是传 domain model 直接 encode。
别在 handler 里写 if version == "v2" 分支逻辑
这种写法短期省事，长期难维护：
- 单元测试要覆盖所有
version组合，用例爆炸 - v2 新增数据库查询或缓存策略，会把 v1 的性能拖垮
- 无法对 v2 单独启用新 middleware（比如 v2 要加 rate limit，v1 不需要）
应让路由层彻底隔离：
v1 := r.Group("/v1")
v1.GET("/users", getUserV1Handler) // 纯 v1 逻辑，只查 users 表
v2 := r.Group("/v2")
v2.GET("/users", getUserV2Handler) // 可连 users + profiles 表，加 redis 缓存
即使底层 service 层复用，API 层的 handler、DTO、验证规则、错误码也必须物理分离。
Header 方案（Accept 或 X-API-Version）仅限兜底场景
如果你的客户端 SDK 无法修改 URL（比如嵌入式设备固件、老 iOS App），才考虑 header 方案，但必须满足：
- 只作为 fallback，优先级低于路径版本（即
/v2/users永远走 v2，无视 header） - 在 gateway 或入口 middleware 统一校验，拒绝非法值（如
X-API-Version: v99），返回400 Bad Request - 禁止在 handler 里重复调用
r.Header.Get("X-API-Version")——应由中间件注入context.Context，后续通过ctx.Value(keyVersion)获取 - HTTP/2 环境下确认 ingress（如 Envoy）已显式配置透传该 header，否则会被静默丢弃
真正容易被忽略的是：OpenAPI 文档生成工具（如 swaggo）必须为每个路由 group 单独打标签，否则 @version 注释会失效，v1 文档里混进 v2 字段。
大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！
