应使用 gorilla/mux 的 PathPrefix().Subrouter() 创建版本子路由，注入版本中间件至 context，避免路径硬编码、Accept 头分发及 latest 别名；chi 的 Mount 不继承父中间件且易路径错配。
用 gorilla/mux 做版本路由分组，别硬塞在路径开头
版本控制不是把 v1 往 URL 里一扔就完事。硬编码成 /v1/users 会导致后续升级时所有 handler、中间件、测试都得跟着改路径前缀，耦合太重。
正确做法是用 gorilla/mux 的子路由器（subrouter）隔离版本逻辑，让同一组 handler 可复用，仅通过父级路由控制入口：
- 主路由注册一个带前缀的子路由器：
r.PathPrefix("/v1").Subrouter() - 所有 v1 接口在这个 subrouter 上挂载，比如
sub.HandleFunc("/users", listUsers).Methods("GET") - v2 可另起一个 subrouter，handler 函数甚至可以复用（只要逻辑没变），只需换验证逻辑或序列化方式
注意：别用 r.Headers("Accept", "application/vnd.myapi.v1+json") 做版本分发——客户端不总发这个头，调试困难，且 OpenAPI 文档难对齐。
URI 设计要避开 Accept 头歧义和缓存陷阱
用请求头做版本控制看似“RESTful”，但实际踩坑多：curl -H "Accept: application/vnd.myapi.v1+json" 看似优雅，可 CDN、反向代理、浏览器预检都可能忽略或覆盖该头；HTTP 缓存也常按路径缓存，导致 v1/v2 响应混用。
立即学习“go语言免费学习笔记（深入）”；
URI 路径版本是最直白、最可控的选择，但要注意两点：
- 版本号必须是路径第一段，且不可省略，如
/v1/users✅，/users?version=v1❌（GET 参数不参与路由匹配，无法用中间件统一拦截） - 避免语义重复，如
/api/v1/users中的api是冗余前缀，除非你真有非 API 路由共存（比如/health），否则直接/v1/...更干净 - 不要用
latest或stable这类动态别名——它们破坏幂等性，让文档、监控、日志难以追踪真实版本
net/http 中间件如何精准识别当前版本
你不能靠解析 r.URL.Path 字符串来判断版本，因为子路由器已剥离前缀，r.URL.Path 拿到的是去前缀后的路径（如 /users），原始版本信息丢了。
正确方式是在子路由器挂载时注入版本标识：
- 用
sub := r.PathPrefix("/v1").Subrouter()后，立刻调用sub.Use(versionMiddleware("v1")) -
versionMiddleware把版本写进context.WithValue(r.Context(), versionKey, ver) - 后续 handler 用
ver := r.Context().Value(versionKey).(string)安全取值，不依赖字符串匹配
这样做的好处是：中间件可统一处理版本兼容逻辑（比如 v1 返回 user.Name，v2 改为 user.FullName），且不会被路径重写或代理转发干扰。
为什么不用 chi 的 Mount？它比 Subrouter 少了什么
chi 的 r.Mount("/v1", v1Router) 看似更简洁，但它默认不传递父路径的中间件，且子 router 的 NotFoundHandler 和错误恢复行为与父级隔离——这意味着你得在每个子 router 里重复注册 recover、logging、CORS。
而 gorilla/mux 的 Subrouter 天然继承父级中间件链，且 NotFoundHandler 可统一配置。如果你用 chi，务必显式调用 v1Router.Use(parentMiddlewares...)，否则 v1 接口会漏掉鉴权或日志。
另一个隐性差异：chi.Mount 对路径拼接更严格，/v1 + /users 会变成 /v1/users，但若子 router 内部又写 /v1/users，就会错配成 /v1/v1/users——这种错误 runtime 不报，只返回 404，排查时容易卡在路由树构造环节。
版本路由真正的复杂点不在怎么写，而在怎么下线旧版：你得同时维护多套 validator、DTO、数据库查询逻辑，还要确保 OpenAPI spec 每个版本独立生成。这些没法靠路由库自动解决，得从项目结构上隔离，比如按版本建包：internal/v1、internal/v2，而不是把所有 handler 堆在一个文件里用 if 切版本。
