必须用 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？路径设计的两个硬约束
版本段必须是路径第一级，且不能冗余嵌套。常见错误包括：
立即学习“go语言免费学习笔记（深入）”；
-
/api/v1/users——/api是多余前缀，除非你同时暴露/health、/metrics等非 API 路由，否则直接/v1/users更干净 -
/v1/api/users或/users/v1—— 破坏 REST 资源语义，/users应该稳定，版本是访问维度，不是资源属性 -
/v1/users?version=v2—— 查询参数不参与路由匹配，中间件无法拦截，CDN 缓存会把 v1/v2 响应混在一起
真正有效的路径结构只有两种：/v1/users（推荐）或 /api/v1/users（仅当存在非 API 路由时）。
开箱即用的技能链路由引擎。13 条预定义链覆盖搜索、开发、审查、MLOps、法律、创意等场景，三层路由架构（触发词→SAD反馈→DAG编排），recall@10=96.97%。配置驱动（chains.yaml），零代码扩展。pip install skill-weave-chains 一键安装。
如何让 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() 之后注册。
