必须用结构体级别验证器，因为字段级验证器每次只接收单个字段值和元信息，无法访问其他字段，故不能实现跨字段校验如密码一致性或时间范围判断；而结构体级验证器可获取整个结构体实例，支持任意字段组合判断与复用逻辑。
必须用结构体级别验证器，字段级验证器无法跨字段判断
为什么字段级验证器不能做多条件校验
字段级验证器（RegisterValidation）每次只拿到单个字段的值和元信息，比如 fl.Field().String() 或 fl.Param()，它看不到其他字段是否存在、是否为空、是否满足某范围——所以像 “密码和确认密码必须一致”“结束时间不能早于开始时间” 这类逻辑，字段级函数根本无从下手。
常见错误现象：binding:"required,eqfield=ConfirmPassword" 看似能用，但这是 validator/v10 内置的 eqfield 标签，不是自定义的；你若自己写个字段级函数试图读 ConfirmPassword 字段，会 panic 或返回空字符串，因为 fl 不提供跨字段访问能力。
- 字段级函数签名固定为
func(fl validator.FieldLevel) bool，作用域仅限当前字段 -
eqfield、gtfield等是 validator 库原生支持的结构体级标签，不是靠字段级注册实现的 - 强行在字段级函数里反射取其他字段，不仅不可靠，还会破坏 Gin 的验证流程顺序
正确做法：用 validator.RegisterStructValidation 注册结构体级验证器
结构体级验证器接收整个结构体实例，可以自由读取任意字段、做组合判断、复用已有逻辑。注册时机和字段级一样：必须在路由初始化前，且需确保 binding.Validator.Engine() 已就绪。
示例：校验用户注册时密码强度 + 两次输入一致
type RegisterReq struct {
Username string `form:"username" binding:"required,min=2"`
Password string `form:"password" binding:"required"`
Confirm string `form:"confirm" binding:"required"`
}
// 结构体级验证函数
func registerStructLevelValidation(sl validator.StructLevel) {
req := sl.Current().Interface().(RegisterReq)
if req.Password != req.Confirm {
sl.ReportError(reflect.ValueOf(req.Password), "Password", "Password", "password_mismatch", "")
return
}
// 密码强度：至少含数字、大小写字母、特殊字符中的三类
count := 0
if regexp.MustCompile(`[0-9]`).FindStringIndex([]byte(req.Password)) != nil {
count++
}
if regexp.MustCompile(`[a-z]`).FindStringIndex([]byte(req.Password)) != nil {
count++
}
if regexp.MustCompile(`[A-Z]`).FindStringIndex([]byte(req.Password)) != nil {
count++
}
if regexp.MustCompile(`[*|&|$|#]`).FindStringIndex([]byte(req.Password)) != nil {
count++
}
if count < 3 {
sl.ReportError(reflect.ValueOf(req.Password), "Password", "Password", "password_weak", "")
}
}
// 注册（必须在 r := gin.Default() 之后、r.GET/POST 之前）
if v, ok := binding.Validator.Engine().(*validator.Validate); ok {
v.RegisterStructValidation(registerStructLevelValidation, RegisterReq{})
}
- 注意
sl.ReportError第一个参数必须是reflect.ValueOf(字段值)，否则错误定位失效 - 第四个参数（
"password_mismatch"）是自定义 tag 名，后续可用来映射友好提示 - 不要在结构体级函数里调用
panic或阻塞 IO，验证必须轻量、同步
如何让结构体级验证器支持参数（如 role=admin）
validator/v10 的结构体级验证本身不解析 tag 参数，但你可以把参数写进结构体字段的 binding 标签里，再在验证函数中手动提取。
例如要求管理员注册时邮箱必须带 @admin.example.com 后缀：
type AdminRegisterReq struct {
Email string `form:"email" binding:"required,email"`
Role string `form:"role" binding:"required,oneof=admin user"`
}
// 在结构体级验证中检查 Role 字段值，再决定 Email 校验逻辑
func adminStructLevelValidation(sl validator.StructLevel) {
req := sl.Current().Interface().(AdminRegisterReq)
if req.Role == "admin" {
if !strings.HasSuffix(req.Email, "@admin.example.com") {
sl.ReportError(reflect.ValueOf(req.Email), "Email", "Email", "admin_email_domain", "")
}
}
}
- 参数实际是结构体字段的值，不是 binding 标签里的字符串（如
binding:"admin_role"无效） - 若需更灵活的参数传递，建议把配置项抽成全局变量或依赖注入，避免硬编码
- 结构体级验证函数不会被多次调用——每个请求只触发一次，无论结构体嵌套多深
最易忽略的一点：结构体级验证器注册后，Gin 不会自动为你绑定错误消息到 JSON 响应；ShouldBind 返回的 validator.ValidationErrors 中，Tag() 返回的是你 ReportError 传入的第四个参数（如 "admin_email_domain"），不是 binding 标签名。要返回中文提示，得靠 GetErrorMsg 这类封装函数查表映射，而不是指望 Gin 默认处理。
