编辑“︁Gin路由组”︁

{{DISPLAYTITLE:Gin路由组}}

'''Gin路由组'''是[[Gin框架]]中用于组织和管理相关路由的核心功能，允许开发者对具有共同前缀或中间件的路由进行逻辑分组。本条目将详细介绍其语法结构、应用场景及最佳实践。

== 概念说明 ==
路由组（Route Group）通过<code>RouterGroup</code>结构实现，提供以下核心特性：
* '''路径前缀共享'''：组内路由自动继承父路径
* '''中间件共享'''：统一应用鉴权/日志等处理逻辑
* '''代码分层'''：提升路由管理的模块化程度

数学表达上，给定路由组<math>G</math>和路由集合<math>R=\{r_1,r_2,...,r_n\}</math>，其组织关系可表示为：
<math>G(R) = \bigcup_{i=1}^{n}(prefix + r_i.path)</math>

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

<syntaxhighlight lang="go">
package main

import "github.com/gin-gonic/gin"

func main() {
    r := gin.Default()
    
    // 创建/api前缀的路由组
    api := r.Group("/api")
    {
        api.GET("/users", listUsers)    // 实际路径：/api/users
        api.POST("/upload", uploadFile)  // 实际路径：/api/upload
    }
    
    r.Run(":8080")
}
</syntaxhighlight>

=== 执行流程 ===
<mermaid>
graph TD
    A[客户端请求 /api/users] --> B[路由组路径匹配]
    B --> C[执行组级中间件]
    C --> D[执行路由处理函数]
</mermaid>

== 中间件应用 ==
路由组可批量应用中间件，典型用于权限控制：

<syntaxhighlight lang="go">
func AuthMiddleware(c *gin.Context) {
    // 验证逻辑...
}

func adminRoutes(r *gin.Engine) {
    admin := r.Group("/admin")
    admin.Use(AuthMiddleware) // 组内路由统一鉴权
    {
        admin.GET("/dashboard", showDashboard)
        admin.POST("/settings", updateSettings)
    }
}
</syntaxhighlight>

== 嵌套路由组 ==
支持多级嵌套实现更精细的路由管理：

<syntaxhighlight lang="go">
v1 := r.Group("/v1")
{
    // /v1/products
    products := v1.Group("/products")
    {
        products.GET("", listProducts)
        products.GET("/:id", getProduct)
    }
    
    // /v1/orders
    orders := v1.Group("/orders")
    {
        orders.POST("", createOrder)
    }
}
</syntaxhighlight>

== 实际应用案例 ==
=== 场景：API版本控制 ===
通过路由组实现多版本API共存：

<syntaxhighlight lang="go">
func setupRoutes(r *gin.Engine) {
    // 公共中间件
    r.Use(gin.Logger())
    
    // 版本分组
    v1 := r.Group("/v1")
    v2 := r.Group("/v2")
    
    // v1路由
    v1.GET("/users", v1UserHandler)
    
    // v2路由（新增特性）
    v2.GET("/users", v2UserHandler)
    v2.POST("/users/search", userSearchHandler)
}
</syntaxhighlight>

=== 输出示例 ===
请求<code>/v1/users</code>时：
<syntaxhighlight lang="json">
{
    "api_version": "1.0",
    "data": [...]
}
</syntaxhighlight>

请求<code>/v2/users/search</code>时：
<syntaxhighlight lang="json">
{
    "api_version": "2.1",
    "results": [...],
    "pagination": {...}
}
</syntaxhighlight>

== 最佳实践 ==
1. '''命名一致性'''：采用<code>/api/v[0-9]+</code>格式的版本前缀
2. '''中间件顺序'''：全局中间件→路由组中间件→路由级中间件
3. '''功能分组'''：按业务域（如<code>/users</code>、<code>/products</code>）划分路由组
4. '''避免过深嵌套'''：建议不超过3级嵌套

== 性能考量 ==
路由组在Gin内部通过前缀树（Trie）实现，时间复杂度为：
<math>O(m)</math>（m为路径段数）

与单独注册路由相比，路由组仅增加常数级的内存开销，不影响路由匹配效率。

== 常见问题 ==
{{Collapse
|title=Q: 路由组路径是否支持正则表达式？
|content=Gin原生不支持正则路径，但可通过参数捕获实现类似效果：
<syntaxhighlight lang="go">
group.GET("/:id(\\d+)", handler) // 仅匹配数字ID
</syntaxhighlight>
}}

{{Collapse
|title=Q: 如何在不同路由组间共享中间件？
|content=将中间件定义为变量后重复使用：
<syntaxhighlight lang="go">
commonMW := gin.HandlersChain{Logger(), Recovery()}
group1.Use(commonMW...)
group2.Use(commonMW...)
</syntaxhighlight>
}}

== 进阶技巧 ==
* '''动态路由组'''：通过函数动态生成路由组
<syntaxhighlight lang="go">
func createDynamicGroup(r *gin.Engine, prefix string) {
    group := r.Group(prefix)
    // 动态配置...
}
</syntaxhighlight>

* '''自动OPTIONS处理'''：为RESTful接口统一添加支持
<syntaxhighlight lang="go">
apiGroup := r.Group("/api")
apiGroup.Use(func(c *gin.Context) {
    if c.Request.Method == "OPTIONS" {
        c.AbortWithStatus(204)
    }
})
</syntaxhighlight>

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