参数校验

Gin 内置 validator 库，通过结构体标签实现强大的参数校验。

基本校验规则

type User struct {
    Name     string `json:"name" binding:"required"`                          // 必填
    Email    string `json:"email" binding:"required,email"`                   // 邮箱格式
    Password string `json:"password" binding:"required,min=6,max=20"`         // 长度范围
    Age      int    `json:"age" binding:"gte=0,lte=150"`                      // 数值范围
    Phone    string `json:"phone" binding:"omitempty,len=11"`                // 可选但必须11位
    URL      string `json:"url" binding:"omitempty,url"`                      // URL格式
}

常用校验标签

枚举校验

type Article struct {
    Status string `json:"status" binding:"required,oneof=draft published archived"`
}

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

嵌套结构体校验

type Address struct {
    City    string `json:"city" binding:"required"`
    Street  string `json:"street" binding:"required"`
}

type Person struct {
    Name    string  `json:"name" binding:"required"`
    Address Address `json:"address" binding:"required,dive"` // dive 进入嵌套校验
}

切片校验

type Tags struct {
    Items []string `json:"items" binding:"required,dive,required,min=2"`
    // dive 进入切片，required 确保元素不为空，min=2 每个元素至少2字符
}

自定义校验错误消息

type LoginForm struct {
    Username string `json:"username" binding:"required" msg:"用户名不能为空"`
    Password string `json:"password" binding:"required,min=6" msg:"密码至少6位"`
}

// 使用自定义消息需要额外处理
r.POST("/login", func(c *gin.Context) {
    var form LoginForm
    if err := c.ShouldBindJSON(&form); err != nil {
        c.JSON(400, gin.H{
            "error": getValidateError(err, form),
        })
        return
    }
    c.JSON(200, gin.H{"message": "success"})
})

自定义校验规则

import "github.com/go-playground/validator/v10"

// 注册自定义校验
if v, ok := binding.Validator.Engine().(*validator.Validate); ok {
    v.RegisterValidation("mobile", func(fl validator.FieldLevel) bool {
        phone := fl.Field().String()
        matched, _ := regexp.MatchString(`^1[3-9]\d{9}$`, phone)
        return matched
    })
}

// 使用自定义校验
type Contact struct {
    Phone string `json:"phone" binding:"required,mobile"`
}

校验失败时，ShouldBind 系列方法返回错误，需要处理并返回友好提示。

要点总结

• 使用 binding 标签定义校验规则
• required 表示必填，omitempty 表示可选
• dive 用于校验嵌套结构和切片元素
• 可注册自定义校验规则扩展功能
• 校验失败返回错误需友好处理