编辑“︁Gin嵌套路由”︁

{{DISPLAYTITLE:Gin嵌套路由}}

'''Gin嵌套路由'''是[[Gin框架]]中用于组织复杂路由结构的核心功能，允许开发者通过分组机制构建层次化的API端点。本文将从基础概念到高级应用全面解析该特性，适合从初学者到进阶开发者阅读。

== 概念介绍 ==
嵌套路由（Nested Routing）是指将多个具有共同前缀或中间件的路由组织为逻辑分组的模式。在Gin中通过<code>RouterGroup</code>实现，其核心优势包括：
* '''路径复用'''：避免重复书写相同URL前缀
* '''中间件共享'''：统一管理一组路由的预处理逻辑
* '''代码模块化'''：提升大型项目的可维护性

数学表达上，嵌套路由形成树状结构：
<math>
G = (V, E) \quad \text{其中} \quad V = \{v_1,...,v_n\}, E \subseteq V \times V
</math>

== 基础语法 ==
Gin通过<code>Group()</code>方法创建路由组：

<syntaxhighlight lang="go">
router := gin.Default()

// 基础路由组
api := router.Group("/api")
{
    api.GET("/users", listUsers)      // 实际路径: /api/users
    api.POST("/login", authHandler)  // 实际路径: /api/login
}
</syntaxhighlight>

=== 路径组合规则 ===
|+ 路径解析规则
! 分组路径 !! 子路径 !! 最终路径
|-
| <code>/api</code> | <code>/v1</code> | <code>/api/v1</code>
|-
| <code>/admin</code> | <code>/users/:id</code> | <code>/admin/users/:id</code>

== 多级嵌套实例 ==
三级嵌套路由的典型实现：

<syntaxhighlight lang="go">
func main() {
    r := gin.Default()

    // 一级分组
    v1 := r.Group("/v1")
    {
        // 二级分组
        admin := v1.Group("/admin")
        admin.Use(AdminRequired()) // 分组专属中间件
        {
            // 三级分组
            users := admin.Group("/users")
            {
                users.GET("", listAllUsers)       // GET /v1/admin/users
                users.DELETE("/:id", deleteUser)  // DELETE /v1/admin/users/123
            }
        }
    }
    r.Run(":8080")
}
</syntaxhighlight>

<mermaid>
graph TD
    A[Root /] --> B[v1/]
    B --> C[admin/]
    C --> D[users/]
    D --> E[GET '']
    D --> F[DELETE :id]
</mermaid>

== 中间件作用域 ==
嵌套路由支持精确的中间件控制：
* '''全局中间件'''：通过<code>router.Use()</code>应用
* '''分组中间件'''：在<code>Group()</code>后调用<code>Use()</code>
* '''路由级中间件'''：作为参数传入<code>GET()</code>/<code>POST()</code>等

<syntaxhighlight lang="go">
// 全局中间件
router.Use(gin.Logger())

// 分组中间件
authGroup := router.Group("/auth")
authGroup.Use(AuthMiddleware())
{
    // 路由级中间件
    authGroup.GET("/profile", RateLimit(), getProfile)
}
</syntaxhighlight>

== 实际应用案例 ==
=== RESTful API 版本控制 ===
<syntaxhighlight lang="go">
api := router.Group("/api")
{
    v1 := api.Group("/v1")
    {
        v1.GET("/products", getProductsV1)
    }

    v2 := api.Group("/v2")
    {
        v2.GET("/products", getProductsV2)
    }
}
</syntaxhighlight>

=== 管理后台路由 ===
<mermaid>
flowchart LR
    admin[/admin\] --> dashboard
    admin --> users[/users\]
    users --> list
    users --> create
    admin --> posts[/posts\]
    posts --> audit
</mermaid>

对应实现：
<syntaxhighlight lang="go">
admin := router.Group("/admin")
admin.Use(AdminCheck())
{
    admin.GET("/dashboard", showDashboard)
    
    users := admin.Group("/users")
    {
        users.GET("", userList)
        users.POST("", createUser)
    }

    posts := admin.Group("/posts")
    {
        posts.GET("/pending", pendingReviews)
    }
}
</syntaxhighlight>

== 高级技巧 ==
=== 动态分组前缀 ===
通过闭包实现动态路径生成：
<syntaxhighlight lang="go">
func createGroup(router *gin.Engine, prefix string) *gin.RouterGroup {
    return router.Group(fmt.Sprintf("/%s", prefix))
}

func main() {
    r := gin.Default()
    api := createGroup(r, "dynamic-api")
    {
        api.GET("/status", checkStatus)
    }
}
</syntaxhighlight>

=== 自动OPTIONS处理 ===
为嵌套路由启用自动OPTIONS响应：
<syntaxhighlight lang="go">
api := router.Group("/api")
api.OPTIONS("/*any", func(c *gin.Context) {
    c.Header("Allow", "GET,POST,PUT,DELETE")
    c.Status(200)
})
</syntaxhighlight>

== 常见问题 ==
{{Warning|1=避免路由冲突}}
以下路由会产生歧义：
<syntaxhighlight lang="go">
group.GET("/users/:id", getUser)   // 1
group.GET("/users/create", createUser) // 2 - 永远不会匹配
</syntaxhighlight>

解决方案：调整路由顺序或使用明确前缀：
<syntaxhighlight lang="go">
group.GET("/users/create", createUser) // 应先定义
group.GET("/users/:id", getUser)      // 后定义
</syntaxhighlight>

== 最佳实践 ==
# 嵌套层级建议不超过3层
# 按业务功能而非技术维度分组
# 对公共中间件进行性能优化
# 使用<code>c.FullPath()</code>调试路由

{{Tip|可通过<code>gin.DebugPrintRouteFunc</code>自定义路由调试输出}}

[[Category:后端框架]]
[[Category:Gin]]
[[Category:Gin路由与请求处理]]