Go Validator 怎样注册结构体级的跨字段校验

当注册接口同时接收密码和确认密码时，两个字段分别写 required 还不够：它们都非空，并不代表值相同。Go Validator 的字段标签适合单字段规则，跨字段不变量应注册一个结构体级回调，再用 ReportError 把错误落到具体字段上。

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

先划定跨字段校验要保护什么

这类校验保护的是请求内部的一致性，而不是某个字段的格式。以注册请求为例，Password 和 ConfirmPassword 是一对必须同时满足的输入资产。单字段标签可以拒绝空值，却无法表达“两个值相等”。

这一步还要把风险边界说清楚：密码长度、确认密码一致性可以在结构体级回调中完成；用户是否有权修改密码、密码是否命中历史密码、是否需要二次验证，则属于权限或业务规则，不应偷偷塞进校验回调。

用 StructLevelFunc 描述跨字段不变量

RegisterStructValidation 接收一个 StructLevelFunc 和要绑定的结构体类型。回调从 sl.Current() 取得当前值，比较两个字段；发现不一致时，把错误归因到确认字段，这样接口层可以给出稳定的字段提示。

package main

import (
    "fmt"

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

type Signup struct {
    // 字段标签负责各自的格式和长度，跨字段关系交给结构体回调。
    Password        string `validate:"required,min=8"`
    ConfirmPassword string `validate:"required"`
}

func signupStructValidation(sl validator.StructLevel) {
    // Current 返回当前正在校验的 Signup 值；示例只绑定这一种类型。
    req := sl.Current().Interface().(Signup)
    if req.Password != req.ConfirmPassword {
        // 将错误归因到确认字段，param 用来说明它应与哪个字段一致。
        sl.ReportError(req.ConfirmPassword, "ConfirmPassword", "ConfirmPassword", "sameas", "Password")
    }
}

func newValidator() *validator.Validate {
    // 注册在初始化阶段完成，返回的实例供请求处理器复用。
    v := validator.New()
    v.RegisterStructValidation(signupStructValidation, Signup{})
    return v
}

func main() {
    v := newValidator()
    err := v.Struct(Signup{Password: "correct-horse", ConfirmPassword: "different"})
    fmt.Println(err != nil)
}

这里的 sameas 是人为选择的错误标签，不要求它一定是库内置标签；调用方可以按自己的错误码映射。重要的是第四、第五个参数要稳定，前端才能知道哪个字段失败以及它应参考哪个字段。

注册时机和回调边界要固定

官方文档明确提示，RegisterStructValidation 不是并发安全的方法，应在第一次校验前完成注册；而校验器本身适合初始化一个共享实例并复用。不要在每个请求中重新注册，也不要在请求已经开始后动态修改同一个实例的规则。

回调内只做确定性的输入值判断。不要在里面调用数据库、权限服务或网络接口：这些操作会让校验结果依赖外部状态，也会让请求延迟和失败重试变得难以控制。通过结构体校验后，再进入鉴权、重复密码检查、审计和持久化流程。

把错误转换成接口能理解的字段信息

调用 Struct 返回的是 error。如果要把跨字段错误变成表单提示，可以用 errors.As 取出 validator.ValidationErrors，再读取 Field、Namespace、Tag 和 Param。

package validation

import (
    "errors"
    "fmt"

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

func firstMessage(err error) string {
    // 不是字段错误时保留通用提示，避免把内部类型断言暴露给调用方。
    var fieldErrors validator.ValidationErrors
    if !errors.As(err, &fieldErrors) || len(fieldErrors) == 0 {
        return "请求参数无法校验"
    }
    item := fieldErrors[0]
    // Param 保存回调传入的参考字段名，可用于拼接稳定的提示。
    return fmt.Sprintf("%s 未通过 %s 规则，参考字段：%s", item.Field(), item.Tag(), item.Param())
}

批量表单或嵌套结构体可以优先使用 Namespace 定位完整路径；对外返回时再映射成 JSON 字段名和业务错误码，不要直接把内部结构体名当成长期 API 契约。

上线前复查四个边界

如果跨字段规则需要请求上下文，可以进一步看 RegisterStructValidationCtx；但只要规则是纯值判断，普通的 StructLevelFunc 更直观。最后不要把“校验通过”误解成“业务操作安全”，它只说明这组输入通过了当前声明的值约束。

常见问题

两个字段的相等关系能不能只靠标签完成？

简单场景可以使用库提供的跨字段标签；当规则需要明确错误归因、组合多个字段或加入自定义判断时，结构体级回调更容易维护。

RegisterStructValidation 可以在请求处理中调用吗？

不建议。该注册方法不是并发安全的，应在第一次校验前完成。生产代码通常在初始化阶段创建并配置一个共享校验器。

回调里能不能查询数据库确认密码是否可用？

不应把外部查询混入值校验。回调判断结构体内部关系，数据库、权限、历史密码和风控检查放到后续业务流程，并单独记录审计结果。