Gin路由分级本质是前缀拼接与中间件作用域控制:Group嵌套实现路径叠加(如/api/v1)和中间件继承,需显式赋值+{}包裹子路由,兄弟Group中间件隔离,路径拼接需避免双斜杠,通配符须置于分组末尾。

路由分级管理在Gin中本质是前缀拼接 + 中间件作用域
所谓“分级”,Gin 并不提供类似树形深度或层级编号的抽象,而是靠 Group() 的嵌套调用实现路径前缀叠加和中间件继承。比如 r.Group("/api").Group("/v1") 生成的最终路径是 /api/v1/xxx,且内层 Group 自动继承外层注册的中间件(洋葱模型里更靠近 handler)。
嵌套 Group 必须显式赋值并用 {} 包裹子路由
常见错误是写成 r.Group("/api").Group("/v1").GET("/users", h)——这行代码实际注册的是 /users,因为 Go 会忽略链式调用中未被接收的返回值,.GET() 最终绑定到根 *gin.Engine 上。
- 正确写法必须分步赋值:
api := r.Group("/api"); v1 := api.Group("/v1"); { v1.GET("/users", h) } - 或者用嵌套块:
api := r.Group("/api"); { v1 := api.Group("/v1"); { v1.GET("/users", h) } } - 所有子路由必须写在对应 Group 的
{}块内,否则脱离作用域
分级 ≠ 独立路由树,中间件不会自动穿透兄弟组
admin := r.Group("/admin") 和 api := r.Group("/api") 是两个平行分组,彼此中间件完全隔离。你在 admin.Use(auth()) 注册的鉴权中间件,对 api 下任何路由都无效。
开箱即用的技能链路由引擎。13 条预定义链覆盖搜索、开发、审查、MLOps、法律、创意等场景,三层路由架构(触发词→SAD反馈→DAG编排),recall@10=96.97%。配置驱动(chains.yaml),零代码扩展。pip install skill-weave-chains 一键安装。
- 全局中间件(
r.Use())作用于所有路由,最外层 - 父 Group 的
Use()对其所有子 Group 生效,但不影响兄弟 Group - 子 Group 再调用
Use(),只叠加在自身及后代上,不会覆盖或干扰父级 - 若需跨分级复用逻辑,应抽成函数,而非依赖“自动继承”
分级配置容易忽略的路径拼接细节
前缀拼接是纯字符串操作,不自动处理斜杠。比如 r.Group("/api") + Group("v1") → /api/v1;但 r.Group("/api/") + Group("/v1") → /api//v1(双斜杠),多数 HTTP 客户端会自动归一化,但某些代理或测试工具可能报 404。
- 推荐统一约定:Group 前缀末尾不加
/,子路径开头也不加/(如v1.GET("users", h)) - 通配符路由(
*path)必须放在分组最末端,且只能出现在一个 Group 的最后一级,否则匹配失败 - 分级越深,路由树节点越多,但 Gin 的基数树查找性能几乎不受影响——关键在注册阶段静态构建,不是运行时解析










