路由组嵌套时前缀逐级拼接，如/v1/admin/logs；版本段必须为URL第一级或统一/api/v1模式；Header版本分发需用中间件校验并注入context，而非依赖Group路径。
路由组嵌套时前缀如何叠加
嵌套的 Group 会逐级拼接路径前缀，不是覆盖也不是合并。比如 v1 := r.Group("/v1")，再写 admin := v1.Group("/admin")，那么 admin.GET("/logs") 对应的完整路径是 /v1/admin/logs，不是 /admin/logs 或 /v1/logs。
常见错误是以为内层 Group 会“重置”前缀，结果注册出错位路由；或者手动重复写全路径（如 v1.GET("/v1/users")），导致双份 /v1。
- 每级
Group只负责自己那一段前缀，层级越深，路径越长 - 嵌套深度建议控制在 2–3 层以内，否则路径冗长、调试困难
- 不要在子组里用绝对路径（如
"/users"），必须用相对路径（如"users"）
URL 路径版本控制的硬约束
用路径分版本（如 /v1/users）时，版本段必须是 URL 的第一级路径，且不能嵌套在其他前缀之后。例如 /api/v1/users 是错的，/v1/api/users 也不推荐——它破坏了“版本即语义边界”的一致性。
正确结构只有两种：直接 /v1/users，或统一加 /api 前缀后仍保持版本为第二段，如 /api/v1/users（此时需确保所有版本都走这个模式，且 /api 本身不承载业务逻辑）。
开箱即用的技能链路由引擎。13 条预定义链覆盖搜索、开发、审查、MLOps、法律、创意等场景，三层路由架构（触发词→SAD反馈→DAG编排），recall@10=96.97%。配置驱动（chains.yaml），零代码扩展。pip install skill-weave-chains 一键安装。
-
/v1必须是router.Group()的第一个参数，不能是子路径的一部分 - 不同版本组之间不能共享中间件配置，除非你明确需要（比如所有版本都要鉴权）
- Gin 不会自动识别
v1和v2的语义关系，它们就是两个完全独立的路由树分支
Header 版本分发为何不能靠 Group 实现
想用 X-API-Version 头切换行为，却还去注册 v1.Group("/users") 和 v2.Group("/users")，这是典型误用。Gin 的 Group 是静态路由注册机制，不感知请求头；它只管“谁匹配这个路径”，不管“这次请求带什么头”。
真实需求是同一路径（如 /users）根据 header 返回不同逻辑，而不是靠路径区分。这时候 Group 不该承担分发职责，而应退居为组织工具——比如把所有 v1 handler 放进一个文件，v2 放另一个，但注册时共用同一个 r.GET("/users", ...)。
- 别在 middleware 里调用
c.Abort()中断流程，否则全局错误处理中间件收不到 panic 或自定义错误 - 版本校验必须在最外层中间件完成，并用
c.Set("api_version", "v1")注入 context - handler 内部用
c.GetString("api_version")分支，或直接调用预定义函数如handleUsersV1(c)
多版本共存时中间件和错误处理的隔离点
版本差异不仅在业务逻辑，也体现在中间件选择上。比如 v1 需要兼容旧客户端，得加 Content-Type 自动补全；v2 要求严格 JSON，就得拦截非 application/json 请求。这些不能堆在全局中间件里 if-else 判断，而应在版本注册阶段就绑定。
最稳妥的做法是：每个版本组使用独立中间件链。例如 v1.Use(jsonCompatMiddleware())，v2.Use(strictJSONMiddleware())，再分别挂载 handler。这样即使某个版本的中间件 panic，也不会影响其他版本。
- 全局中间件（如日志、recover）可以保留，但业务相关中间件必须按版本显式注册
- 错误响应格式也要按版本约定，v1 返回
{"code":0,"msg":"ok"}，v2 就不该突然改成 RFC 7807 格式 - 别依赖 Gin 的
AbortWithStatusJSON统一出口——不同版本的错误码映射可能完全不同
