Go Validator omitempty 为什么会跳过零值字段的后续规则

这个现象的关键不在于 min 或 gte 失效，而在于 omitempty 先判断字段是否为空。判断结果为空时，Validator 会直接跳过同一 tag 中排在后面的规则；因此 0、""、nil 指针和空集合可能根本没有走到后续校验。

官方文档：https://pkg.go.dev/github.com/go-playground/validator/v10

omitempty 为什么会跳过后续规则

Validator 会先解析结构体 tag，再按字段遍历规则。omitempty,min=3 可以理解为“字段不为空时，才执行长度至少为 3”；它不是 min=3 的弱化版本。字符串为空、数字为 0、指针为 nil 时，字段被判定为空，后面的 min、gte、email 等规则就不会运行。

这正适合“可选字段”：例如补充说明可以不填，填了以后必须达到长度。但它不适合“0 也是一个需要校验的业务值”的字段，例如页码、库存或重试次数。

用最小结构体区分空值和非空值

下面的 tag 把 omitempty 放在前面。空字符串会直接通过，内容为 go 时才会触发 min=3。示例中的注释只说明关键分支，避免把每一行都写成注释。

package main

import (
    "fmt"
    "github.com/go-playground/validator/v10"
)

type Request struct {
    // 备注可以为空；一旦填写，长度必须达到 3 个字符。
    Remark string `validate:"omitempty,min=3"`
    // 0 会被 omitempty 当作空值，因此不会触发 gte=1。
    Retry int `validate:"omitempty,gte=1"`
}

func main() {
    validate := validator.New()
    cases := []Request{{}, {Remark: "go"}, {Remark: "golang", Retry: 2}}
    for _, item := range cases {
        // 只判断返回错误；非 nil 错误再按需展开 ValidationErrors。
        err := validate.Struct(item)
        fmt.Printf("%+v -> %v\n", item, err)
    }
}

第一条记录的 Remark 和 Retry 都是空值，所以后续规则被跳过；第二条记录的 Remark 非空但长度不足，会返回校验错误。也就是说，omitempty 改变的是“是否进入后续规则”，不是把字段转换成默认值。

omitnil、omitzero 与 omitempty 怎么选

三者的区别最好放到字段语义里看，而不是死记标签名称：

例如一个可选的超时指针可以写成 Timeout *int `validate:"omitnil,gte=1"`：nil 表示没有配置，指向 0 则仍会被检查。若把它写成 omitempty,gte=1，指向 0 的场景就可能被当成空值放过。指针、集合和结构体还要结合 JSON 解码结果一起确认，避免“没传”“传空”“传 0”在业务层被混成一种状态。

生产代码的三个排查点

1. 先问字段是否允许缺省，再决定是否使用 omit 标签；必填字段不要用 omitempty 掩盖缺失。
2. 确认 0、false 和空字符串是否有业务意义。它们有意义时，优先检查 omitnil 或去掉跳过标签。
3. 如果规则带 dive，区分字段本身被跳过和集合元素继续校验：空集合可能停在字段层，非空集合才会进入元素规则。

常见问题

为什么写了 gte=1，Retry=0 仍然不报错？

因为同一个 tag 中的 omitempty 先把 0 识别为空值，gte=1 没有执行。

omitempty 能只跳过 min，保留 required 吗？

不能把它理解成只影响下一条规则。需要必填时直接使用 required，再根据字段类型组合其他约束。

什么时候用 omitnil 更稳妥？

当 nil 表示“未提供”，但 0、false 或空字符串仍然是需要审查的输入时，omitnil 更贴近业务。