必须用 r.Group() 而非硬编码路径。因其能显式声明版本边界，使工具链（如 OpenAPI、Prometheus）、Nginx 配置、中间件作用域和路由匹配正确生效，并支持清晰的版本升级与共享逻辑。

为什么必须用 r.Group() 而不是手写 /v1/users 路径

把路径直接写成 r.GET("/users/v1", handler)，表面上确实省事，但代价也很直接：路由的结构语义会被抹平。

像 Gin 的 router.Walk()、OpenAPI 生成器、Prometheus metrics 标签，这些能力都建立在真实的分组层级之上。可它们根本没法判断“/users/v1”里的 v1 到底是不是版本的一部分。

更棘手的是，Nginx 里的 location /v1/ 规则会因此失效，因为实际的路径前缀压根不一致。

一旦到了 v2 需要接入新的鉴权逻辑，也没法只给 /v2 单独挂中间件。最后往往只能退回到每个 handler 里反复做判断。

正确做法是让框架明确知道“这是一个版本边界”。

v1 := r.Group("/v1")
v1.GET("/users", getUsersV1)
v1.POST("/users", createUserV1)

v2 := r.Group("/v2")
v2.GET("/users", getUsersV2)
v2.POST("/users", createUserV2)

这样所有工具链才能按 /v1 和 /v2 自动聚合日志、指标、文档。

/v1 还是 /api/v1？路径设计的两个硬约束

版本段必须是路径第一级，且不能冗余嵌套。

常见错误包括：

• /api/v1/users —— /api 是多余前缀，除非你同时暴露 /health、/metrics 等非 API 路由，否则直接 /v1/users 更干净
• /v1/api/users 或 /users/v1 —— 破坏 REST 资源语义，/users 应该稳定，版本是访问维度，不是资源属性
• /v1/usersversion=v2 —— 查询参数不参与路由匹配，中间件无法拦截，CDN 缓存会把 v1/v2 响应混在一起

真正有效的路径结构只有两种：

• /v1/users（推荐）
• /api/v1/users（仅当存在非 API 路由时）

如何让 v1 和 v2 共享逻辑但隔离响应结构

版本升级时，常会遇到“行为一致、字段不同”的场景。

直接复制 handler，会导致维护失控。共用 handler 却硬塞 json:"name,omitempty"，又无法表达“v1 不返回、v2 必须返回”的语义。

推荐用「同一 handler + 版本感知的响应构造器」。

• 定义各自版本的输出结构体：UserRespV1 和 UserRespV2，字段按需裁剪或重命名
• handler 内统一调用领域层获取原始数据（如 userDomain := svc.GetUser(id)），再传给对应转换函数：c.JSON(200, toResponseV1(userDomain))
• 避免在结构体上加动态 json tag，把版本差异收口到 toResponseV1() / toResponseV2() 函数里

这样业务逻辑复用，响应契约清晰。升级 v3 时，只需新增 toResponseV3()，无需改 handler。

路由注册顺序和中间件作用域容易踩的坑

Gin 匹配路由是顺序优先，不是最长前缀优先。

如果 r.GET("/v1/:id", handler) 写在 v1 := r.Group("/v1") 之前，它会截获所有 /v1/xxx 请求，导致 v1.Group("/users") 下的子路由失效。

中间件也严格按组作用域生效：

• v1.Use(AuthMiddleware) 不会影响 v2 组
• 跨版本通用中间件（如日志、trace ID 注入）必须注册在根 r 上，或显式传入每个 Group
• 别以为父组挂了中间件，子组就自动继承——v1.Group("/admin").Use(PermissionCheck) 只作用于 admin 子路由，不影响 v1.Group("/user")

最隐蔽的问题是：v1 下线后，若没在根路由注册 fallback 逻辑，客户端访问 /v1/xxx 就直接 404，而不是返回 410 或跳转提示。

这需要手动补一层兜底路由，且必须放在所有 Group() 之后注册。

《夸克》非常好用的免费AI浏览器

下载APP查看