Gin - 验证请求参数

结构体验证器

Gin 的结构体验证器是基于 go-playground/validator/v10 实现的。这个库本身非常强大，内置了大量常用的验证器，例如：

• 网络相关字段：ip, ipv4, ipv6, cidr, uri, http_url 等
• 字符串类验证：contains, startswith, lowercase, uppercase, len=X, min, max
• 数值比较器：gt, gte, lt, lte
• 集合验证：dive、slice、array 校验
• 跨字段验证：eqfield, nefield
• 格式相关：email, uuid, datetime 等

而且验证器还能组合多个条件：

• , 表示 AND（全部满足）
• | 表示 OR（满足其中一个即可）

基础使用方式

只需要在结构体的 tag 中，通过 binding 声明验证规则即可。
例如下面代码中，把 age 限制为大于 18 并小于 30，email 字段必须是合法 email，并且全部字段必填：

type Person struct {
	Name  string `form:"name" binding:"required"`
	Age   int    `form:"age" binding:"required,gt=18,lt=30"`
	Email string `form:"email" binding:"required,email"`
}

完整示例

package main

import (
	"fmt"

	"github.com/gin-gonic/gin"
)

type Person struct {
	Name  string `form:"name" binding:"required"`
	Age   int    `form:"age" binding:"required,gt=18,lt=30"`
	Email string `form:"email" binding:"required,email"`
}

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

	r.GET("/user", func(c *gin.Context) {
		var person Person
		if err := c.ShouldBind(&person); err != nil {
			c.JSON(400, gin.H{
				"error": err.Error(),
			})
			return
		}
		c.JSON(200, gin.H{
			"message": fmt.Sprintf("you name is %s, age is %d, email is %s", person.Name, person.Age, person.Email),
			"person":  person,
		})
	})

	r.Run()
}

请求示例

可以看到，我在 age 字段输入 18 后，不满足大于 18 的要求，接口就返回了错误。

更多常用验证示例

下面整理一些常见的验证场景。

1. 字符串校验场景

字段必须以某前缀开头、包含某字符、长度范围限制

• startswith=http|startswith=https：支持两种协议
• omitempty：可选字段，填了就验证，没填就跳过
• contains: 必须包含某个字符

type Register struct {
	Username string `form:"username" binding:"required,min=3,max=20"`
	Password string `form:"password" binding:"required,min=6"`
	Website  string `form:"website" binding:"required,startswith=http|startswith=https"`
	Remark   string `form:"remark"  binding:"omitempty,contains=ok"`
}

请求示例

如下图示，因为 website 没有按要求填写 http、https 前缀导致报错，同时虽然 remark 没有写，但是因为设置了 omitempty 所以忽略了校验。

2. 数值类验证（范围、比较）

• gt=0：必须大于 0
• gte=0: 必须大于等于 0
• lte=100：最大 100

type Order struct {
	Amount  float64 `json:"amount" binding:"required,gt=0"`
	Discount int    `json:"discount" binding:"gte=0,lte=100"`
}

3. 网络类字段验证（URL/IP）

type NetworkConfig struct {
	IP   string `json:"ip" binding:"required,ip"`
	URL  string `json:"url" binding:"required,http_url"`
	CIDR string `json:"cidr" binding:"required,cidr"`
}

非常适合做网关/代理/自动化工具类接口。

4. 数组 / Slice 验证 (dive)

dive 表示 “对 slice 中每个元素进行校验”。

• 必传 tags
• 每个 tag 长度 >= 1

type TagsInput struct {
	Tags []string `json:"tags" binding:"required,dive,min=1"`
}

5. 跨字段验证（eqfield / nefield）

type ResetPassword struct {
	Password        string `json:"password" binding:"required,min=6"`
	ConfirmPassword string `json:"confirm_password" binding:"required,eqfield=Password"`
}

如果两次密码不一致，直接返回错误。

6. 使用 OR 条件 (|)

以下年龄字段：满足任一条件即可：

• 18 岁以下，或 60 岁以上

type Test struct {
	Age int `form:"age" binding:"required,lt=18|gt=60"`
}