请求参数绑定

Gin 提供多种参数绑定方式，支持从不同来源获取请求数据。

Query 参数

URL 查询字符串参数：

// GET /search?keyword=gin&page=1
r.GET("/search", func(c *gin.Context) {
    keyword := c.Query("keyword")       // 获取参数，不存在返回空字符串
    page := c.DefaultQuery("page", "1") // 带默认值
    c.JSON(200, gin.H{
        "keyword": keyword,
        "page":    page,
    })
})

Form 表单参数

POST 表单数据：

// POST /login
// Content-Type: application/x-www-form-urlencoded
r.POST("/login", func(c *gin.Context) {
    username := c.PostForm("username")
    password := c.DefaultPostForm("password", "")
    c.JSON(200, gin.H{
        "username": username,
        "password": password,
    })
})

JSON 参数绑定

自动绑定 JSON 请求体：

type User struct {
    Name string `json:"name" binding:"required"`
    Age  int    `json:"age"`
}

r.POST("/user", func(c *gin.Context) {
    var user User
    if err := c.ShouldBindJSON(&user); err != nil {
        c.JSON(400, gin.H{"error": err.Error()})
        return
    }
    c.JSON(200, user)
})

URI 路径参数

URL 路径中的参数：

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

// 通配符参数
// GET /files/path/to/file.txt
r.GET("/files/*filepath", func(c *gin.Context) {
    filepath := c.Param("filepath") // /path/to/file.txt
    c.String(200, "File: %s", filepath)
})

Header 参数

获取请求头：

r.GET("/info", func(c *gin.Context) {
    token := c.GetHeader("Authorization")
    userAgent := c.GetHeader("User-Agent")
    c.JSON(200, gin.H{
        "token":      token,
        "user_agent": userAgent,
    })
})

自动绑定方法

type SearchReq struct {
    Keyword string `form:"keyword" binding:"required"`
    Page    int    `form:"page" form:"page" binding:"min=1"`
}

// 自动绑定 Query 参数
r.GET("/search", func(c *gin.Context) {
    var req SearchReq
    if err := c.ShouldBindQuery(&req); err != nil {
        c.JSON(400, gin.H{"error": err.Error()})
        return
    }
    c.JSON(200, req)
})

使用 ShouldBind 系列方法时，传入结构体指针。

要点总结

• c.Query() 获取 URL 查询参数
• c.PostForm() 获取表单数据
• c.Param() 获取 URL 路径参数
• ShouldBind 系列方法自动绑定到结构体
• 结构体标签指定字段映射