4. 请求处理：获取Query参数、Form表单参数、JSON请求体绑定与验证

在 Gin 框架中，请求数据的获取是构建 API 的核心环节。本章将系统讲解如何从 HTTP 请求中提取 Query 参数、Form 表单参数，以及如何将 JSON 请求体 绑定到结构体并进行验证。掌握这些技能，你才能编写出健壮、可维护的 Web 服务。

4.1 Query 参数获取

Query 参数通常附加在 URL 的 ? 之后，用于传递过滤、分页或搜索条件。Gin 提供了简洁的 API 来获取这些参数。

4.1.1 基础获取方法

// 示例：获取分页与搜索参数
r.GET("/api/users", func(c *gin.Context) {
    page, _ := strconv.Atoi(c.DefaultQuery("page", "1"))
    pageSize, _ := strconv.Atoi(c.DefaultQuery("page_size", "20"))
    keyword := c.Query("keyword")

    c.JSON(http.StatusOK, gin.H{
        "page":     page,
        "pageSize": pageSize,
        "keyword":  keyword,
    })
})

4.2 Form 表单参数获取

当客户端以 application/x-www-form-urlencoded 或 multipart/form-data 格式提交数据时，Gin 提供了与 Query 参数类似的 API 来获取表单字段。

4.2.1 表单参数获取方法

// 示例：处理用户注册表单
r.POST("/register", func(c *gin.Context) {
    username := c.PostForm("username")
    password := c.PostForm("password")
    email := c.DefaultPostForm("email", "")

    // 处理文件上传
    file, err := c.FormFile("avatar")
    if err == nil {
        // 保存文件到本地
        c.SaveUploadedFile(file, "./uploads/"+file.Filename)
    }

    c.JSON(http.StatusOK, gin.H{
        "message": "注册成功",
        "user":    username,
    })
})

4.3 JSON 请求体绑定与验证

现代 API 开发中，JSON 是最常用的数据交换格式。Gin 提供了强大的 请求体绑定 功能，可以将 JSON 数据自动解析到 Go 结构体，并支持内置验证。

4.3.1 绑定方式对比

4.3.2 结构体标签与验证规则

Gin 使用 go-playground/validator 作为底层验证引擎。你可以在结构体字段上使用 binding 标签来定义验证规则。

// 定义用户创建请求结构体
type CreateUserRequest struct {
    Username string `json:"username" binding:"required,min=3,max=32"`
    Email    string `json:"email" binding:"required,email"`
    Age      int    `json:"age" binding:"gte=0,lte=150"`
    Password string `json:"password" binding:"required,min=8"`
    Role     string `json:"role" binding:"oneof=admin user guest"`
}

4.3.3 完整绑定与验证示例

r.POST("/users", func(c *gin.Context) {
    var req CreateUserRequest

    // 绑定 JSON 请求体到结构体
    if err := c.ShouldBindJSON(&req); err != nil {
        // 验证失败，返回详细的错误信息
        var errors []string
        for _, fieldErr := range err.(validator.ValidationErrors) {
            errors = append(errors, fieldErr.Translate(trans))
        }
        c.JSON(http.StatusBadRequest, gin.H{
            "code":    400,
            "message": "请求参数验证失败",
            "errors":  errors,
        })
        return
    }

    // 业务逻辑处理
    c.JSON(http.StatusCreated, gin.H{
        "code":    201,
        "message": "用户创建成功",
        "data":    req,
    })
})

4.4 请求处理流程总览

下面的 SVG 图展示了 Gin 框架中请求处理的完整流程，从接收请求到返回响应的各个阶段。

4.5 常见错误与避坑指南

4.6 最佳实践总结

• 统一使用 ShouldBindJSON：保持代码一致性，避免混合使用 BindJSON 和 ShouldBindJSON 导致错误处理逻辑混乱。
• 为所有 API 输入定义结构体：不要直接使用 c.Query 或 c.PostForm 获取原始值，始终定义结构体并绑定，便于维护和验证。
• 提供有意义的错误信息：验证失败时，返回具体的字段名和错误原因，而不是简单的 "参数错误"。
• 使用自定义验证器：对于复杂的业务规则（如密码强度、手机号格式），注册自定义验证器以复用验证逻辑。
• 区分 Query 和 Body 参数：GET 请求使用 Query 参数，POST/PUT/PATCH 使用 Body 参数，保持 RESTful 风格。