Golang 实战多版本 API 共存的路由管理方案

路径前缀式版本路由（/v1、/v2）是 Go 服务中唯一能同时兼顾调试性、性能和长期可维护性的方案。其他方式，在真实项目里逐步暴露出来的成本，往往比想象中大得多。

为什么不能用 version 查询参数或 Accept 请求头做主路由

乍一看，查询参数或 Accept 头确实显得更灵活，但它们对可观测性和运维链路的破坏是实实在在的： - 用 `curl https://api.example.com/users?version=v2` 这种形式，CDN 缓存会陷入困境——同样的 URL 配上不同的 version 值，缓存瞬间被打穿。 - Prometheus 的监控指标 `http_request_duration_seconds{path="/users"}` 会把 v1 和 v2 的流量混为一谈，查慢请求的时候，你根本搞不清是哪个版本出来的问题。 - Swagger UI 没办法按版本生成独立的文档。OpenAPI 的 `components/schemas` 是全局作用域，v1 接口注释里出现 `V2User` 字段，v1 文档直接就把错误字段展示出来了。 - 浏览器直访、Postman 测试、Nginx 日志聚合，全都得额外解析 query 或 header。调试的时候，你总得反复确认是不是漏传了 `X-API-Version`。

用 echo.Group 或 gin.Group 分组注册时的关键细节

分组注册本身不难，但几个边界条件特别容易踩坑： - **中间件必须按组注册**：`v1.Use(authV1Middleware)` 和 `v2.Use(authV2Middleware)` 不能共用同一个中间件实例。v2 可能还要额外加双因素校验逻辑。 - **路径注册要严格对齐**：如果 `v2.GET("/users/:id", handler)` 注册了，那 `v1` 组里绝不能漏掉 `v1.GET("/users/:id", legacyHandler)`，否则 `/v1/users/123` 这种请求就会返回 404。 - **不要在分组里嵌套分组**：`v1.Group("/admin").GET("/users", ...)` 这种写法会导致最终路径变成 `/v1/admin/users`，但你原本只是想复用 `/admin/users` 的权限逻辑。正确做法是抽离中间件，而不是嵌套路由。 - 还有一点：`e.Group("/v1")` 之后，handler 里用 `c.Request().URL.Path` 拿到的已经是完整路径（比如 `/v1/users`），这种情况下别再写 `strings.HasPrefix(c.Request().URL.Path, "/v1")` 来判断版本了——冗余而且容易出错。

DTO 结构体必须按版本隔离，哪怕字段完全一样

Go 的 JSON 序列化没有运行时 schema 校验，共用 struct 是最隐蔽的兼容性冲击波。项目里见过在 User 结构上加个指针字段来处理不同版本的情况，结果几个月后那张线上告警就来了： - 假如给 `UserV2` 加了 `Nickname string `json:"nickname"``，但 v1 的 handler 不小心用了 `UserV2{...}` 来返回数据，v1 客户端的 JSON 解析会直接 panic——字段要么不存在，要么类型不匹配。 - 别想着用指针“模拟可选字段”来凑合老版本。v1 的 `Name string` 是必填字段，就该老老实实写成 `string`；v2 改成 `Name *string` 是它的契约，不能反向污染 v1。 - 数据库模型（比如 GORM 的 `UserModel`）要保持稳定，只负责存储；所有 API 层响应都走显式转换：`return c.JSON(200, UserV1{ID: u.ID, Name: u.Name})`。 - 假如用了 `mapstructure` 做 domain → DTO 转换，要确保每个版本的 DecodeHook 是独立配置的，不然 v2 的 hook 很可能影响到 v1 的字段映射。

灰度发布和旧版下线时最容易忽略的点

版本管理最难的部分其实不在开发阶段，而是后半段的生命周期管理： - 上线 `/v2` 之后，`/v1` 不能马上关掉。要等监控确认所有客户端流量都已经切走才行——通常至少要保留 3 个完整的 App 版本周期（iOS 和 Android 的更新节奏不一样）。 - 不要在代码里写 `if version == "v1"` 这种分支判断。这种写法会让单元测试的覆盖爆炸式增长，而且 v3 上线时，你不得不改遍所有 handler。 - 废弃的接口要返回明确的错误信息：用 `c.JSON(410, map[string]string{"error": "API deprecated since 2026-04-01"})`，而不是 404 或静默失败。 - 日志里必须带上版本标识：`log.Printf("[v1] GET /users: %v", err)`，否则线上出现问题时，连是哪个版本出的问题都得靠猜。