路由参数与通配符

Gin 路由支持参数匹配和通配符匹配，灵活处理动态 URL。

单参数匹配

使用 :参数名 匹配单个路径段：

r.GET("/user/:id", func(c *gin.Context) {
    id := c.Param("id")
    c.String(200, "用户ID: %s", id)
})

// GET /user/123    → id = "123"
// GET /user/abc    → id = "abc"
// GET /user/       → 不匹配

多参数匹配

r.GET("/user/:id/profile/:section", func(c *gin.Context) {
    id := c.Param("id")
    section := c.Param("section")
    c.JSON(200, gin.H{
        "id":      id,
        "section": section,
    })
})

// GET /user/123/profile/basic → id="123", section="basic"

通配符匹配

使用 *参数名 匹配剩余所有路径：

r.GET("/files/*filepath", func(c *gin.Context) {
    filepath := c.Param("filepath") // 包含前导斜杠
    c.String(200, "文件路径: %s", filepath)
})

// GET /files/a.txt           → filepath = "/a.txt"
// GET /files/docs/readme.md  → filepath = "/docs/readme.md"
// GET /files/                → filepath = "/"

参数与通配符组合

r.GET("/resource/:id/*action", func(c *gin.Context) {
    id := c.Param("id")
    action := c.Param("action")
    c.JSON(200, gin.H{
        "id":     id,
        "action": action,
    })
})

// GET /resource/123/download → id="123", action="/download"

Query 参数获取

URL 问号后的参数用 c.Query() 获取：

r.GET("/search", func(c *gin.Context) {
    keyword := c.Query("keyword")           // 获取单个参数
    page := c.DefaultQuery("page", "1")     // 带默认值
    allParams := c.Request.URL.Query()      // 获取所有参数

    c.JSON(200, gin.H{
        "keyword": keyword,
        "page":    page,
        "all":     allParams,
    })
})

// GET /search?keyword=gin&page=2

参数类型对比

参数验证

r.GET("/user/:id", func(c *gin.Context) {
    id := c.Param("id")

    // 验证是否为数字
    if _, err := strconv.Atoi(id); err != nil {
        c.JSON(400, gin.H{"error": "ID必须是数字"})
        return
    }

    c.JSON(200, gin.H{"id": id})
})

参数绑定到结构体

type UserParam struct {
    ID   int    `uri:"id" binding:"required,min=1"`
    Name string `uri:"name" binding:"required"`
}

r.GET("/user/:id/:name", func(c *gin.Context) {
    var param UserParam
    if err := c.ShouldBindUri(&param); err != nil {
        c.JSON(400, gin.H{"error": err.Error()})
        return
    }
    c.JSON(200, param)
})

参数匹配不会匹配空值，如 /user/:id 不匹配 /user/；通配符可以匹配空。

要点总结

• :name 匹配单个路径段，不匹配空值
• *name 匹配剩余所有路径，包含前导斜杠
• c.Param() 获取路径参数，c.Query() 获取 Query 参数
• 通配符不能放在参数中间，只能放在末尾
• 使用 ShouldBindUri 可绑定参数到结构体并校验