嵌套路由依靠Group()父子嵌套而非字符串拼接，每层Group仅继承直接父级前缀，需逐层声明并用花括号包裹子路由，中间件不自动继承，必须显式绑定到目标组。
嵌套路由不是靠拼字符串，而是靠 Group() 的父子嵌套关系实现分层；漏掉 Use() 或错用 Subrouter() 会导致中间件不生效、路径注册丢失。
嵌套路由必须用 Group() 链式调用，不能手动拼接路径
很多人写 r.Group("/api").Group("/v1").Group("/user") 看似分层，但实际只注册了 /user（最内层前缀覆盖外层），这是 Gin 的设计机制：每个 Group() 只继承**直接父级**的前缀，不会累积多层。
正确做法是逐层声明并立即使用花括号包裹子路由：
v1 := r.Group("/api/v1")
{
user := v1.Group("/users")
{
user.GET("", listUsers)
user.POST("", createUser)
user.GET("/:id", getUser)
user.PUT("/:id", updateUser)
}
order := v1.Group("/orders")
{
order.GET("", listOrders)
order.POST("", createOrder)
}
}
- 每层
Group()对应一个业务域（如/users），天然隔离 handler 和中间件 - 嵌套层级建议 ≤3 层，过深会增加调试难度（比如
/api/v1/admin/reports/export/csv应考虑扁平化或抽象为独立模块） - 不要在嵌套组里重复写完整路径，例如
user.GET("/api/v1/users/:id", ...)—— 这会注册到根路径，破坏分层逻辑
中间件作用域必须绑定到具体 Group，不能“挂”在父级上等子组继承
Gin 的中间件**不会自动向下继承**。写 api.Use(AuthMiddleware())，再定义 v1 := api.Group("/v1")，这个 v1 组默认**不带任何中间件**。
常见错误：把鉴权中间件只加在顶层 api 组，结果 /api/v1/users 能被未登录用户访问。
- 权限类中间件（如 JWT 校验）必须显式加在需要保护的组上：
v1.Use(middleware.JwtAuth()) - 日志、CORS、GZIP 等通用中间件可加在顶层
r或api组，但需确认是否真要全局生效 - 如果某组下部分路由需跳过中间件（如
/healthz），得单独建一个无中间件的组，而不是在带中间件的组里“绕过”
避免和 gorilla/mux 的 Subrouter() 混淆
Gin 没有 Subrouter() 方法，也**不支持 PathPrefix().Subrouter() 这种嵌套方式**。这是 gorilla/mux 的 API，强行套用会导致编译失败或静默失效。
开箱即用的技能链路由引擎。13 条预定义链覆盖搜索、开发、审查、MLOps、法律、创意等场景，三层路由架构（触发词→SAD反馈→DAG编排），recall@10=96.97%。配置驱动（chains.yaml），零代码扩展。pip install skill-weave-chains 一键安装。
如果你看到类似代码：
api := r.PathPrefix("/api").Subrouter() // ❌ Gin 中不存在此方法
说明你正在混用框架，或者复制了其他库的示例。Gin 唯一合法的嵌套入口就是 Engine.Group() 或 RouterGroup.Group()。
-
r.Group()返回的是*gin.RouterGroup，它本身又支持继续调用.Group()，形成链式嵌套 - 所有路由注册（
GET/POST等）必须在Group()的花括号块内，或显式赋值后调用 - 别试图用
strings.TrimPrefix()手动处理路径前缀——这会让router.Walk()、Swagger 自动生成、Prometheus metrics 标签全部失效
嵌套深度影响路由树匹配性能，但日常项目无需过度优化
Gin 底层用 Radix 树匹配路径，嵌套本身不增加时间复杂度，但过深的分组会让节点优先级（priority）计算变复杂，极端情况下（>5 层）可能略微拖慢热路径匹配速度。
更实际的问题是可维护性：
- 三层以内（如
/api/v1/users）完全安全，也是社区事实标准 - 四层（如
/api/v1/admin/roles/permissions）需评估是否该拆成独立微服务或 SDK 包 - 五层及以上几乎必然意味着职责混乱，应重构为组合式 handler 或提取公共逻辑到 service 层
真正容易被忽略的是：嵌套路由的错误不会报错，而是静默注册到错误路径——比如本该是 /api/v1/users/:id，却因少写一个 Group() 变成 /users/:id，上线后前端 404，排查时得用 r.Walk() 打印整棵树才能发现。
