Go Validator 怎样为切片元素配置 dive 规则

接口接收一组邮箱、标签或商品明细时，最容易漏掉的是“切片里的每一个元素”。go-playground/validator 里的 dive 专门解决这个边界：切片字段自己的规则写在前面，dive 后面的规则下沉到每个元素。比如 min=1,dive,required,email 表示切片至少有一个元素，并且每个元素都必须是非空邮箱。

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

dive 先把规则下沉到切片元素

我在给批量通知接口加输入保护时，先把要保护的资产定成两层：请求必须带有收件人集合，集合里的每个地址还必须满足邮箱格式。只写 min=1 只能保护容器长度，不能阻止一个非邮箱字符串进入后续业务。

package main

import (
    "fmt"

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

type NotifyRequest struct {
    // min=1 约束切片至少有一个元素；dive 后才进入元素规则。
    Recipients []string `validate:"min=1,dive,required,email"`
}

func validateRequest(req NotifyRequest) error {
    // 每次请求复用同一个校验器配置，返回值仍要交给调用方处理。
    v := validator.New()
    if err := v.Struct(req); err != nil {
        return fmt.Errorf("请求校验失败: %w", err)
    }
    return nil
}

这里的规则可以拆成三段理解：min=1 作用于 Recipients 这个切片，dive 切换到元素域，required,email 依次作用于每个字符串。若把 dive 删除，后面的规则就不会按切片元素展开。

用错误路径定位第几个元素不符合约束

输入校验的第二个风险是错误信息只说“Recipients 不合法”，却没有告诉前端具体哪一项出错。Validator 返回的字段错误会携带命名空间和索引，例如 NotifyRequest.Recipients[1]，调用方可以据此把错误映射回批量表单中的对应行。

func validationMessage(err error) string {
    // 只把库返回的字段错误转换成人类可读的定位信息。
    var fieldErrors validator.ValidationErrors
    if !errors.As(err, &fieldErrors) {
        return "校验输入类型不正确"
    }
    first := fieldErrors[0]
    // Namespace 保留切片下标，便于前端定位具体元素。
    return fmt.Sprintf("%s 触发规则 %s", first.Namespace(), first.Tag())
}

示例中需要补充 errors 和 fmt 导入。正式项目还应把字段名映射成稳定的接口错误码，避免把内部结构体名称直接暴露给外部调用者。错误路径是定位线索，不代表某一项一定是恶意输入；安全控制仍要在校验通过后继续执行权限和业务检查。

嵌套结构体和边界值怎么安排

当切片元素本身是结构体时，dive 后不再写字符串规则，而是让 Validator 进入每个元素的字段标签：

type Order struct {
    // dive 让 SKU 和 Quantity 的标签作用于每个 Item。
    Items []Item `validate:"min=1,dive"`
}

type Item struct {
    // required 防止空 SKU 进入库存查询；gt=0 防止无效数量参与结算。
    SKU      string `validate:"required"`
    Quantity int    `validate:"gt=0"`
}

空值策略要提前定下来。若订单可以不带明细，可去掉切片级 min=1；若字段可选且只在有值时校验，可使用 omitempty,dive。不要把 omitempty 当成“忽略所有错误”，它只是让空值跳过后续规则。嵌套切片还可以连续使用 dive,dive，但每多一层都要确认错误路径和空值语义是否仍然清楚。

上线前检查这四个输入边界

最后再看一遍保护边界：切片自身的长度是否符合业务要求，元素是否被逐项展开，嵌套对象是否有自己的字段规则，错误路径是否能定位到下标。这样 dive 才是输入模型的一部分，而不是标签里随手添加的字符串。

常见问题

min=1 会检查每个字符串的长度吗？

不会。它直接作用于切片容器；要检查每个字符串，应在 dive 后写 min，例如 min=1,dive,min=3。

结构体切片是否要在 dive 后重复写字段名？

不需要。元素结构体的字段规则写在元素类型的标签上，切片字段只需用 dive 进入每个元素。

空切片和 nil 切片是同一种校验结果吗？

它们都可能被容器级规则视为空集合，但最终结果取决于是否配置 required、min 或 omitempty。应按接口契约分别写测试用例。