内置校验器

govalid 在全局 Checkers map 中注册了 17 个校验器。每个校验器都接受 相同的 CheckerContext，失败时返回 *ErrContext。

空字符串短路

格式型校验器（alpha、alphanumeric、alphadash、username、 email、ipv4、mobile、tel、phone、idcard）会把空字符串视为 有效。结合 required 即可拒绝空输入。这让"可选字段"的建模变 得非常自然。

存在性

required

字段必须不是其零值/空值。

类型	失败条件
string、slice、array、map、chan	长度为 0
pointer、interface、func	值为 nil
其他可比较类型	值等于零值
不可比较的 struct	跳过（不会 panic）

type Form struct {
    Name string            `valid:"required"`
    Tags []string          `valid:"required"`
    Cfg  *Config           `valid:"required"`
    Meta map[string]string `valid:"required"`
}

数值范围

min:N

字段必须 >= N。支持有符号整型、无符号整型和浮点数。

type Form struct {
    Age   uint    `valid:"min:18"`
    Score float64 `valid:"min:0"`
}

max:N

字段必须 <= N。支持有符号整型、无符号整型和浮点数。

type Form struct {
    Age uint `valid:"min:18;max:120"`
}

WARNING

NaN 既不会触发 min 也不会触发 max，因为 IEEE 754 NaN 比较结果 始终为假。如果你的领域里这点很重要，请用自定义校验器显式拒绝。

长度

minlen:N

长度 >= N。字符串按 rune 计数（所以 "中文" 长度为 2）。 支持 string、slice、array、map。

maxlen:N

长度 <= N。

type Comment struct {
    Body string   `valid:"minlen:1;maxlen:280"`
    Tags []string `valid:"maxlen:5"`
}

字符串

alpha

仅 ASCII 字母（a-z、A-Z）。

alphanumeric

ASCII 字母或数字。

alphadash

字母、数字或下划线（\w+）。注意 - 不包含在内。

username

alphadash 加上两条额外规则：

1. 第一个字符（rune）必须是 ASCII 字母。
2. 最后一个字符不能是 _。

type Form struct {
    Username string `valid:"required;username;minlen:3;maxlen:20"`
}

格式

email

电子邮箱地址。允许 +tag 寻址、带点的本地部分、多级域名。

ipv4

点分四段 IPv4 地址（0.0.0.0 到 255.255.255.255）。

mobile

中国手机号。可选的 +86 或 86 国家前缀。模式以 MobilePattern 名称导出，需要时可替换。

tel

中国座机号。可选的区号，可选的 -。

phone

mobile 或 tel 之一。两者都失败时返回专用的 phone 错误模板， 而不是底层的 mobile/tel。

idcard

中国居民身份证号：15 位数字，或 17 位数字 + 1 位末校验位（0-9、 X、x）。

type Profile struct {
    Email   string `valid:"email"`
    HomeIP  string `valid:"ipv4"`
    Mobile  string `valid:"required;mobile"`
    IDCard  string `valid:"idcard"`
}

跨字段

equal:OtherField

字符串化的值必须与外层 struct 的另一个字段相等。被比较的字段以 Go 字段名引用，而不是它的 label。

type Form struct {
    Password       string `valid:"required;minlen:8" label:"密码"`
    RepeatPassword string `valid:"equal:Password"   label:"重复密码"`
}

如果引用的字段不存在，规则会失败并返回 字段不存在 错误，而不会 默默通过。

枚举

list:a,b,c

字符串化的字段值必须是逗号分隔的允许值之一。所有类型都支持，因为 比较时会用 fmt.Sprintf("%v", value)。

type User struct {
    Role string `valid:"list:admin,editor,viewer"`
}

TIP

由于 list 会字符串化值，你也可以用在数字、布尔甚至自定义类型上， 只要它们的 %v 表示稳定即可：

type Settings struct {
    Verbosity int `valid:"list:0,1,2,3"`
}

总览表

规则	参数	适用类型	空字符串短路
required	—	任意	否
min:N	一个数字	int / uint / float	—
max:N	一个数字	int / uint / float	—
minlen:N	一个 int	string / slice / array / map	是
maxlen:N	一个 int	string / slice / array / map	是
alpha	—	string	是
alphanumeric	—	string	是
alphadash	—	string	是
username	—	string	是
email	—	string	是
ipv4	—	string	是
mobile	—	string	是
tel	—	string	是
phone	—	string	是
idcard	—	string	是
equal:Field	一个字段名	任意	否
list:a,b,c	一个或多个值	任意（字符串化）	否

需要别的能力？看 自定义校验器。