4. Gin框架入门：Gin路由、上下文(Context)、绑定(Binding)与验证(Validation)概览

在Go生态中，Gin 是目前最流行的HTTP框架之一，以其高性能和简洁的API设计著称。本章将带你快速掌握Gin的核心概念：路由、上下文(Context)、绑定(Binding) 与 验证(Validation)。这四个组件构成了Gin处理请求的完整链路，也是后续实现参数校验的基础。

4.1 Gin路由：请求的入口分发

Gin的路由基于 Radix Tree（基数树）实现，支持路径参数、通配符和分组路由。路由是请求进入框架后的第一站，决定了由哪个处理函数来响应。

// 基础路由示例
r := gin.Default()

// 静态路由
r.GET("/health", func(c *gin.Context) {
    c.JSON(200, gin.H{"status": "ok"})
})

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

// 分组路由
api := r.Group("/api/v1")
{
    api.GET("/products", listProducts)
    api.POST("/products", createProduct)
}

4.2 Gin上下文(Context)：请求的通行证

gin.Context 是Gin框架的核心数据结构，贯穿整个请求生命周期。它封装了HTTP请求和响应的所有信息，并提供了一系列便捷方法。

4.3 绑定(Binding)：从请求到结构体

绑定是Gin将HTTP请求中的数据（JSON、表单、查询参数等）自动映射到Go结构体的过程。Gin提供了两种绑定方式：Must Bind 和 Should Bind。

// 定义请求结构体
type CreateUserRequest struct {
    Name  string `json:"name" form:"name" binding:"required"`
    Email string `json:"email" form:"email" binding:"required,email"`
    Age   int    `json:"age" form:"age" binding:"gte=0,lte=150"`
}

// 使用 ShouldBindJSON 进行绑定
func createUser(c *gin.Context) {
    var req CreateUserRequest
    if err := c.ShouldBindJSON(&req); err != nil {
        // 自定义错误处理
        c.JSON(400, gin.H{"error": err.Error()})
        return
    }
    // 业务逻辑...
    c.JSON(200, gin.H{"message": "user created"})
}

4.4 验证(Validation)：数据质量的守门员

Gin默认集成了 go-playground/validator/v10 作为验证引擎。通过在结构体字段的 binding 标签中声明验证规则，Gin会在绑定阶段自动执行校验。

4.5 常用验证标签速查

Gin集成的验证器提供了丰富的内置标签，覆盖了大部分业务场景。以下是高频使用的验证规则：

4.6 完整示例：一个带校验的用户注册接口

将路由、上下文、绑定和验证串联起来，实现一个完整的用户注册接口：

package main

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

// 注册请求结构体
type RegisterRequest struct {
    Username string `json:"username" binding:"required,min=4,max=20"`
    Email    string `json:"email"    binding:"required,email"`
    Password string `json:"password" binding:"required,min=8,max=32"`
    Age      int    `json:"age"      binding:"gte=1,lte=120"`
    Gender   string `json:"gender"   binding:"oneof=male female other"`
}

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

    // 注册路由
    r.POST("/api/v1/register", registerHandler)

    r.Run(":8080")
}

func registerHandler(c *gin.Context) {
    var req RegisterRequest

    // 绑定并验证
    if err := c.ShouldBindJSON(&req); err != nil {
        // 验证失败，返回详细错误
        c.JSON(http.StatusBadRequest, gin.H{
            "code":    400,
            "message": "参数校验失败",
            "errors":  err.Error(),
        })
        return
    }

    // 业务逻辑（此处省略）
    // userService.Register(req.Username, req.Email, req.Password)

    c.JSON(http.StatusOK, gin.H{
        "code":    200,
        "message": "注册成功",
        "data": gin.H{
            "username": req.Username,
            "email":    req.Email,
        },
    })
}