/v1路径比Accept头更可靠，因Go路由层不解析Accept头做路由分发，需手动解析导致路由树不可见、调试困难、日志聚合失效；而路径前缀天然支持反向代理分流、Prometheus精确指标、cURL直观测试及Swagger独立文档生成。
URL路径前缀（如/v1、/v2）是Go接口版本控制最稳妥的选择，Header方案只适合补充场景，不能替代路径隔离。
为什么/v1路径比Accept头更可靠
Go的HTTP路由层（net/http、gin、chi、gorilla/mux）本身不解析Accept头做路由分发，必须手动解析+条件跳转——这会让路由树不可见、调试困难、日志聚合失效。而路径前缀天然支持：
- 反向代理（Nginx/Envoy）按
location /v1/直接分流 - Prometheus指标中
http_request_duration_seconds{path="/v1/users"}可精确归因 - cURL测试直观：
curl https://api.example.com/v2/users一眼确认版本 - Swagger文档生成工具（如
swaggo/swag）能为每个Group独立打@version标签
硬用Accept: application/vnd.myapi.v2+json还会踩坑：浏览器不带该头、curl默认不带、CDN可能忽略、mime.ParseMediaType若没处理参数（如charset=utf-8）会导致匹配失败。
gin.Group("/v1")和chi.Router.Group怎么避免路由冲突
用路由组隔离版本是最小侵入、最易维护的方式，但要注意注册细节：
立即学习“go语言免费学习笔记（深入）”；
- 版本前缀必须是固定字符串，禁用正则（如
/v{version}/users），否则chi.Walk()或gin.Engine.Routes()查不到真实路径 -
router.Group("/v1")后注册的GET("/users")，实际匹配路径是/v1/users，不是/users；别在handler里再手动截掉/v1，否则r.URL.Path被改写后中间件逻辑错乱 - 不要把版本号写死在handler名里（如
getUsersV1Handler），而是让v1.GET("/users", getUsers)和v2.GET("/users", getUsers)指向不同函数 - 如果用
http.ServeMux，它不支持Group，得自己用http.StripPrefix("/v1", handler)，否则r.URL.Path仍含/v1，后续json.Unmarshal可能因路径字段解析失败
X-API-Version头只能当补充，不能当主路由依据
如果必须支持Header版本（比如老客户端无法改URL），请严格限制使用范围：
- 只在中间件里统一提取并注入
context.Context，后续handler用ctx.Value("api_version")读取，别每个handler都重复调c.GetHeader("X-API-Version") - 必须显式校验值合法性：
switch v { case "v1", "v2", "v3":，不能只判空或用strings.HasPrefix - HTTP/2下某些Ingress（如Traefik 2.x）默认丢弃自定义头，需在配置里显式透传
X-API-Version - 别用
Accept头做版本协商——它语义上是content negotiation，跟API契约升级无关，且浏览器、Postman默认不设，测试时总要手动补，极易漏传导致fallback到v1
DTO结构体怎么隔离才不翻车
版本兼容性崩溃点往往不在路由，而在JSON序列化层：
- 每个版本必须定义独立DTO（如
V1User、V2User），即使字段完全一样也分开声明，禁止共用struct - 新增字段一律加
json:",omitempty"，并设合理零值（string默认""，int默认0） - 废弃字段不能删，改成未导出字段+注释标记
// deprecated: use FullName instead - 重命名字段时，双写旧名和新名（
Name string `json:"name"`+FullName string `json:"full_name"`），靠UnmarshalJSON方法过渡
最易被忽略的是：v1 handler返回json.Marshal(domain.User{})时，如果domain.User结构体里新加了字段，v1客户端会收到不该有的字段，JSON解析直接panic——这不是bug，是契约破坏。
