4. Gin路由进阶：路由分组、参数绑定（Path/Query）、路由中间件基础

在上一节中，我们掌握了 Gin 框架的基础路由与启动流程。然而，真实业务接口往往需要更精细的路由组织方式：将同类接口归为一组、从 URL 路径或查询字符串中提取参数、以及在请求处理前后插入通用逻辑。本节将深入这三个进阶主题，为后续的契约压测打下路由设计基础。

4.1 路由分组：模块化组织接口

路由分组（Group）是 Gin 最实用的组织特性。它允许你为同一前缀的多个路由共享相同的路径前缀和中间件。在微服务或模块化开发中，通常按业务领域划分路由组，例如用户模块、订单模块、支付模块。

// 路由分组示例
r := gin.Default()

// 用户模块分组
userGroup := r.Group("/users")
{
    userGroup.GET("/profile", getUserProfile)
    userGroup.POST("/register", registerUser)
    userGroup.PUT("/update", updateUser)
}

// 订单模块分组，带版本前缀
orderGroup := r.Group("/api/v1/orders")
{
    orderGroup.GET("/list", listOrders)
    orderGroup.GET("/:id", getOrderDetail)
}

// 嵌套分组：管理后台
adminGroup := r.Group("/admin")
{
    // 管理员用户管理
    adminUserGroup := adminGroup.Group("/users")
    adminUserGroup.GET("/", listAllUsers)
    adminUserGroup.DELETE("/:id", deleteUser)
}

4.2 参数绑定：Path 参数与 Query 参数

Web 接口的核心能力是从请求中提取动态数据。Gin 提供了两种最常用的参数绑定方式：路径参数（Path Parameter）和查询参数（Query Parameter）。理解它们的区别与使用场景，是编写可测试接口的前提。

4.2.1 Path 参数：资源定位

Path 参数嵌入在 URL 路径中，使用冒号 : 定义，通过 c.Param() 获取。适用于标识唯一资源，如用户 ID、订单号。

// Path 参数示例
r.GET("/users/:id", func(c *gin.Context) {
    userID := c.Param("id")
    c.JSON(200, gin.H{
        "user_id": userID,
        "message": "获取用户信息成功",
    })
})

// 多级 Path 参数
r.GET("/orders/:orderId/items/:itemId", func(c *gin.Context) {
    orderID := c.Param("orderId")
    itemID  := c.Param("itemId")
    c.JSON(200, gin.H{
        "order_id": orderID,
        "item_id":  itemID,
    })
})

4.2.2 Query 参数：筛选与分页

Query 参数位于 URL 问号之后，使用 c.Query() 或 c.DefaultQuery() 获取。适用于过滤、排序、分页等非标识性参数。

// Query 参数示例
r.GET("/users", func(c *gin.Context) {
    // 获取查询参数，不存在时返回空字符串
    page     := c.Query("page")
    pageSize := c.DefaultQuery("page_size", "10")  // 默认值 10
    keyword  := c.Query("keyword")

    c.JSON(200, gin.H{
        "page":      page,
        "page_size": pageSize,
        "keyword":   keyword,
    })
})

// 请求示例：/users?page=1&page_size=20&keyword=张三

4.3 路由中间件基础：请求处理管道

中间件（Middleware）是 Gin 框架的核心设计模式之一。它允许你在请求到达处理函数之前或之后执行通用逻辑，形成一条处理管道。常见的中间件用途包括：日志记录、身份认证、请求限流、跨域处理、请求耗时统计等。

4.3.1 中间件的定义与注册

Gin 中间件是一个 gin.HandlerFunc，接收 *gin.Context 参数。在中间件中调用 c.Next() 将控制权交给下一个处理函数，调用 c.Abort() 则终止后续处理。

// 自定义日志中间件
func LoggerMiddleware() gin.HandlerFunc {
    return func(c *gin.Context) {
        // 请求前
        startTime := time.Now()
        path := c.Request.URL.Path

        // 调用下一个处理函数
        c.Next()

        // 请求后
        latency := time.Since(startTime)
        statusCode := c.Writer.Status()
        log.Printf("[%d] %s %v", statusCode, path, latency)
    }
}

// 认证中间件
func AuthMiddleware() gin.HandlerFunc {
    return func(c *gin.Context) {
        token := c.GetHeader("Authorization")
        if token == "" {
            c.JSON(401, gin.H{"error": "未提供认证令牌"})
            c.Abort()  // 终止后续处理
            return
        }
        // 验证 token 逻辑...
        c.Set("user_id", "12345")  // 在上下文中设置值
        c.Next()
    }
}

4.3.2 中间件的三种注册方式

// 中间件注册综合示例
r := gin.Default()

// 全局中间件：所有请求都记录日志
r.Use(LoggerMiddleware())

// 公开路由组：不需要认证
publicGroup := r.Group("/api/public")
{
    publicGroup.GET("/health", healthCheck)
    publicGroup.POST("/login", loginHandler)
}

// 私有路由组：需要认证
privateGroup := r.Group("/api/private")
privateGroup.Use(AuthMiddleware())  // 分组级别中间件
{
    privateGroup.GET("/profile", getProfile)
    privateGroup.POST("/order", createOrder)
}

// 单路由中间件：仅该路由需要额外限流
r.GET("/api/sensitive", RateLimitMiddleware(), sensitiveHandler)

4.4 路由与中间件架构总览

下图展示了 Gin 路由分组、参数绑定与中间件在请求处理管道中的协作关系。理解这个架构，有助于你在编写压测脚本时准确构造请求路径和参数。

4.5 实战：构建可压测的路由结构

结合以上知识点，我们构建一个完整的用户管理路由结构。该结构将用于后续章节的契约压测，请重点关注路由分组、参数绑定和中间件的组合方式。

// main.go - 完整路由结构
func main() {
    r := gin.Default()

    // 全局中间件：请求耗时统计
    r.Use(func(c *gin.Context) {
        start := time.Now()
        c.Next()
        duration := time.Since(start)
        log.Printf("[%s] %s 耗时: %v", c.Request.Method, c.Request.URL.Path, duration)
    })

    // 公开接口组
    public := r.Group("/api/v1/public")
    {
        public.GET("/health", func(c *gin.Context) {
            c.JSON(200, gin.H{"status": "ok"})
        })
        public.POST("/login", loginHandler)
    }

    // 用户管理组（需要认证）
    users := r.Group("/api/v1/users")
    users.Use(authMiddleware())
    {
        // Path 参数：获取单个用户
        users.GET("/:id", getUserByID)

        // Query 参数：用户列表（分页）
        users.GET("/", listUsers)

        // Path + Query 混合：查询用户的订单
        users.GET("/:id/orders", getUserOrders)
    }

    // 管理后台组（需要认证 + 管理员权限）
    admin := r.Group("/api/v1/admin")
    admin.Use(authMiddleware(), adminMiddleware())
    {
        admin.GET("/dashboard", dashboardHandler)
        admin.DELETE("/users/:id", deleteUserByAdmin)
    }

    r.Run(":8080")
}

// 处理函数示例
func getUserByID(c *gin.Context) {
    userID := c.Param("id")
    // 模拟数据库查询
    c.JSON(200, gin.H{
        "user_id": userID,
        "name":    "测试用户",
        "email":   "test@example.com",
    })
}

func listUsers(c *gin.Context) {
    page     := c.DefaultQuery("page", "1")
    pageSize := c.DefaultQuery("page_size", "10")
    c.JSON(200, gin.H{
        "page":      page,
        "page_size": pageSize,
        "total":     100,
        "users":     []string{},
    })
}

4.6 本章小结

• 路由分组 通过 Group() 实现模块化组织，支持嵌套分组，是大型项目路由设计的基石。
• Path 参数 使用 :param 定义，c.Param() 获取，用于资源标识；Query 参数 使用 c.Query() 获取，用于筛选和分页。
• 中间件 支持全局、分组、单路由三种注册方式，通过 c.Next() 和 c.Abort() 控制请求处理流程。
• 合理的路由结构设计，能够显著提升接口的可测试性和压测脚本的编写效率。