标签参考

govalid 读取三个结构体标签。它们的默认名称可以通过三个包级变量 配置，启动时设置一次即可让它们和其他标签命名空间共存。

标签	默认名称	变量
校验规则	valid	govalid.RulesField
字段标签	label	govalid.LabelField
覆盖消息	msg	govalid.MessageField

// 例：和其他标签命名空间共存
govalid.RulesField = "validate"
govalid.LabelField = "name"

valid —— 规则列表

valid 是一个 以 ; 分隔的规则列表。每条规则要么是：

• 单纯的校验器名：required
• 带参数的校验器，参数以 , 分隔：min:0、list:a,b,c

`valid:"required;min:18;max:120"`
`valid:"required;username;minlen:3;maxlen:20"`
`valid:"list:admin,editor,viewer"`

解析器细节

• 头尾的 ; 会被忽略。
• ;; 之间的空规则会被跳过。
• 参数为空（如 valid:"required:"）会产生一个空字符串参数，多数 校验器会因此返回参数错误。
• 第一个 : 之后的所有内容会原样作为参数字符串——所以 url:http://example.com 会被解析为校验器 url，参数是 http://example.com。

规则执行语义

规则从左到右依次执行。每次失败都会产生一个 *ErrContext， 执行会继续下一条规则——除非该字段配置了 msg 覆盖（见下文）。

type Form struct {
    Score int `valid:"required;min:0;max:100" label:"得分"`
}
// Score = -1 → "得分应大于0"
// Score = 200 → "得分应小于100"
// Score = 0 → 无错误

label —— 友好名称

label 会被加在错误消息的开头。没有它时，govalid 会回退到 Go 字段名。

type Form struct {
    Email string `valid:"required" label:"电子邮箱"`
}
// → "电子邮箱不能为空"

按 locale 的 label

通过 label-<lang> 标签可以为每种 locale 提供本地化的 label。lang 后缀对应 language.Tag.String()：

type Form struct {
    Email string `valid:"required" label:"邮箱" label-en:"Email"`
}

govalid.Check(form, language.English)
// → "Email can not be empty"

每次 Check 调用的查找顺序：

1. 请求 locale 对应的 label-<lang>
2. label（无后缀的默认值）
3. Go 字段名

msg —— 覆盖消息

msg 替换该字段第一条失败规则的整个错误消息。后续规则不会再 执行。

type Form struct {
    Password string `valid:"required;minlen:8;maxlen:64" label:"密码" msg:"密码长度需在 8-64 之间"`
}
// 空密码 → "密码长度需在 8-64 之间"
// 4 个字符的密码 → "密码长度需在 8-64 之间"

TIP

当文案比错因细节更重要时使用 msg。多消息 UI 推荐省略 msg，让 locale 的模板说话。

标签组合速查

type Profile struct {
    // required + 格式校验，使用默认中文 label。
    Email string `valid:"required;email" label:"邮箱"`

    // 可选但有值时必须合法。
    Backup string `valid:"email"          label:"备用邮箱"`

    // 自定义消息覆盖一切。
    Phone  string `valid:"required;mobile" label:"手机号" msg:"请输入有效的手机号"`

    // 按 locale 的 label。
    Name   string `valid:"required" label:"姓名" label-en:"Name"`

    // 跨字段引用使用 Go 字段名。
    Repeat string `valid:"equal:Password"`
}