应使用路径前缀（如/v1、/v2）实现api版本控制，通过gorilla/mux或chi的pathprefix分组注册路由，隔离各版本的dto与序列化契约，避免查询参数或header传版本号。
用 gorilla/mux 或 chi 实现路径前缀式版本控制
Go 的主流路由库不内置版本管理，得靠路径设计把版本信息显式暴露出来。这是最直观、客户端最易理解的方式，也方便 Nginx 或 API 网关做分流。
常见错误是把版本号塞进查询参数（如 /users?id=123&v=2）——缓存失效、日志难聚合、OpenAPI 文档没法按版本生成。
- 用
router.PathPrefix("/v1")分组注册 v1 路由，再用router.PathPrefix("/v2")注册新版本，互不干扰 - v1 和 v2 的 handler 可以共用底层 service 层，但 request/response 结构必须隔离，避免字段冲突导致 JSON 解析 panic
- 别在中间件里动态解析
r.URL.Path提取版本号再跳转——这会让路由树不可见，调试时router.Walk看不到实际注册路径
如何让 v1 和 v2 共享同一套 handler 逻辑但返回不同结构
硬写两套 handler 会重复维护，但直接复用又容易因 struct 字段增减引发 v1 客户端解析失败。关键不是“复用代码”，而是“隔离序列化契约”。
典型翻车场景：给 v2 的 User struct 加了 CreatedAt 字段，结果 v1 的 JSON 响应里也冒出来，前端报错。
立即学习“go语言免费学习笔记（深入）”；
- 为每个版本定义独立的 DTO（如
V1User、V2User），即使字段一样也分开声明 - 在 handler 末尾用
json.Marshal(v1User)显式转换，而不是传入原始 domain model 直接 encode - 如果用
encoding/json的 tag 控制输出，切记 v1 的 struct 不要依赖omitempty隐式过滤——v2 新增字段设为零值时，v1 响应可能意外漏掉旧字段
使用 URL 查询参数 version=2 是不是更灵活
看起来灵活，实则破坏 RESTful 约定，且带来一连串运维和调试问题。
你无法用 curl -I https://api.example.com/v1/users 直观确认服务是否就绪；CI/CD 发布 v2 时，没法通过路径自动拦截旧流量做灰度；Prometheus metrics 里的 http_request_duration_seconds{path="/users"} 会把所有版本混在一起，查慢请求时根本分不清是哪个版本拖慢的。
- HTTP 头
X-API-Version: 2同样不可取——curl 测试麻烦，浏览器直访失效，CDN 缓存策略难配置 - 如果真有兼容性极差的老客户端不能改 URL，宁可用反向代理（如 Envoy）在入口层把
version=2重写成/v2/...，保持 Go 服务内部干净 - OpenAPI 3.0 的
components/schemas按版本拆开后，Swagger UI 才能正确渲染不同版本的字段差异
中间件里做版本路由分发的风险点
有人写个中间件读取路径或 header，然后 ctx.Value("version") 透传，最后在 handler 里 if-else 分支处理——这会让业务逻辑和版本耦合，单元测试成本陡增，而且无法利用 Go 的类型系统做编译期校验。
更隐蔽的问题：当 v1 接口需要加一个新字段但 v2 不需要时，你不得不再加一层条件判断，很快变成 if version == "v1" && user.Type == "premium" && req.FromMobile 这种面条代码。
- 路由注册阶段就该决定 handler 绑定关系，而不是运行时靠 if 切换
- 如果多个版本共享大量逻辑，抽成纯函数（无 HTTP context、无 net/http.ResponseWriter），输入输出都是明确 struct，这样测试和复用才可靠
- 别为了“减少重复代码”牺牲可维护性——多几行
router.Get("/v1/users", v1ListUsers)和router.Get("/v2/users", v2ListUsers)是值得的
版本控制最难的不是怎么写路由，而是怎么让团队达成共识：v1 接口一旦发布，它的输入输出契约就冻结了。任何改动都必须走 v2，哪怕只是改个字段名。这点在 code review 里比在代码里更难 enforce。
