3. Gin 路由详解：GET/POST/PUT/DELETE 路由、路由分组、路由参数、通配符路由

Gin 框架的路由设计是其核心能力之一，它基于 httprouter 实现，提供了高性能的 HTTP 方法路由、路径参数、通配符匹配以及路由分组等特性。本章将系统讲解 Gin 路由的完整用法，为后续构建 RESTful API 和压测闭环打下坚实基础。

3.1 基础 HTTP 方法路由

Gin 为常见的 HTTP 方法提供了直接的路由注册函数：GET、POST、PUT、DELETE、PATCH、HEAD、OPTIONS。每个方法对应一个处理函数，签名均为 func(c *gin.Context)。

package main

import (
    "net/http"
    "github.com/gin-gonic/gin"
)

func main() {
    r := gin.Default()

    // GET 路由：查询资源
    r.GET("/users", func(c *gin.Context) {
        c.JSON(http.StatusOK, gin.H{"message": "获取用户列表"})
    })

    // POST 路由：创建资源
    r.POST("/users", func(c *gin.Context) {
        c.JSON(http.StatusCreated, gin.H{"message": "创建用户成功"})
    })

    // PUT 路由：全量更新资源
    r.PUT("/users/:id", func(c *gin.Context) {
        id := c.Param("id")
        c.JSON(http.StatusOK, gin.H{"message": "更新用户 " + id})
    })

    // DELETE 路由：删除资源
    r.DELETE("/users/:id", func(c *gin.Context) {
        id := c.Param("id")
        c.JSON(http.StatusOK, gin.H{"message": "删除用户 " + id})
    })

    r.Run(":8080")
}

3.2 路由参数与通配符路由

Gin 支持两种动态路径匹配方式：路径参数（:param） 和 通配符（*param）。路径参数匹配单个路径段，通配符匹配所有剩余路径。

3.2.1 路径参数（:param）

使用冒号 : 前缀定义路径参数，通过 c.Param("name") 获取值。路径参数必须匹配一个非空的路径段，不支持跨斜杠匹配。

// 匹配 /users/123，不匹配 /users/123/orders
r.GET("/users/:id", func(c *gin.Context) {
    id := c.Param("id")
    c.JSON(http.StatusOK, gin.H{"user_id": id})
})

// 多个参数：/users/123/orders/456
r.GET("/users/:uid/orders/:oid", func(c *gin.Context) {
    uid := c.Param("uid")
    oid := c.Param("oid")
    c.JSON(http.StatusOK, gin.H{"user_id": uid, "order_id": oid})
})

3.2.2 通配符路由（*param）

使用星号 * 前缀定义通配符参数，可以匹配零个或多个路径段（包括斜杠）。通配符必须放在路径末尾。

// 匹配 /files/、/files/a.txt、/files/dir/sub/file.go
r.GET("/files/*filepath", func(c *gin.Context) {
    filepath := c.Param("filepath")
    c.JSON(http.StatusOK, gin.H{"path": filepath})
})

// 访问 /files/main.go  →  filepath = "/main.go"
// 访问 /files/src/util/helper.go  →  filepath = "/src/util/helper.go"

3.3 路由分组（Group）

路由分组用于将具有相同前缀或中间件的路由组织在一起，减少重复代码，提升可维护性。分组支持嵌套，每个分组可以绑定独立的中间件。

// 创建分组：/api/v1
v1 := r.Group("/api/v1")
{
    v1.GET("/users", listUsers)
    v1.POST("/users", createUser)
    v1.GET("/users/:id", getUser)
    v1.PUT("/users/:id", updateUser)
    v1.DELETE("/users/:id", deleteUser)
}

// 嵌套分组：/api/v1/admin
admin := v1.Group("/admin")
admin.Use(middleware.AuthRequired())
{
    admin.GET("/dashboard", adminDashboard)
    admin.POST("/settings", updateSettings)
}

// 带中间件的分组
r.Group("/public", middleware.RateLimit()).GET("/health", healthCheck)

3.4 路由匹配优先级与冲突

Gin 的路由匹配遵循 最长前缀匹配 原则，静态路径优先于动态参数，动态参数优先于通配符。当路由注册存在冲突时，Gin 会在启动时 panic 报错。

• 静态路径 > 路径参数：/users/new 优先于 /users/:id
• 路径参数 > 通配符：/users/:id 优先于 /users/*action
• 冲突示例：/users/:id 与 /users/:name 在同一层级冲突，因为参数名不同但模式相同

3.5 路由架构总览

下图展示了 Gin 路由的核心组件及其关系，包括 HTTP 方法路由、路径参数、通配符、路由分组和中间件链的协作方式。

3.6 路由分组与中间件协作流程

下图展示了请求经过路由分组和中间件链的完整执行顺序，帮助理解 Gin 的请求处理管道。

3.7 路由设计最佳实践