validator.Struct() 静默失效的三类原因是字段小写（反射不可见）、tag 语法带空格（如“min=3”前有空格）、指针字段未初始化且无“omitempty”；Gin 中需显式替换默认 validator 实例并统一错误处理。
validator.Struct() 为什么没报错但校验失效
字段小写、tag 语法带空格、指针字段未初始化，这三类问题会让 Validate.Struct() 静默跳过校验——不 panic、不报 error、也不提示，但 required 规则完全不起作用。
- 结构体字段必须首字母大写：
Name可校验，name直接被 validator 忽略（反射不可见） -
validate:"required,min=3"合法；validate:"required, min=3"（逗号后有空格）→min规则静默失效 - 嵌套结构体字段为指针时，如
Address *Address，若req.Address == nil，默认不进入子校验；加validate:"omitempty"才会跳过，否则需手动判空并初始化
Gin 中替换默认 validator 实例的正确姿势
Gin v1.9+ 默认用的是 validator/v10，但若你 go get github.com/go-playground/validator/v10 后没显式替换，它仍可能用旧版或内部实例，导致自定义规则（如 chinese_mobile）不生效。
- 创建全局 validator 实例：
v := validator.New()，再调用v.RegisterValidation("xxx", fn) - 启动 Gin 前赋值：
router.Validator = &defaultValidator{validator: v}，不是中间件里改，也不是engine.Validator = ...（旧 API） - 不要在 handler 里调
c.ShouldBind(&req)后再手动v.Struct(req)——重复校验且错误类型不统一；ShouldBind 底层已走你注册的 validator 实例
URL 路径参数和 query 参数必须手动转换再校验
gorilla/mux 或 chi 提取的路径变量（如 {id}）是字符串，req.URL.Query().Get("page") 也是字符串。框架不会自动转类型或校验范围，直接 strconv.Atoi 不处理 error 就 panic。
- 路径参数：先
id, err := strconv.ParseUint(vars["id"], 10, 64)，检查err != nil，再判断业务约束（如id > 0） - query 参数：建议封装成独立结构体（如
Pagination），用mapstructure.Decode(values, &p)映射，再调v.Struct(p)；避免直接对url.Values写一堆 if-else - 别信 default fallback：传
page=（空字符串）时，strconv.Atoi("")返回0, error，应视为非法输入，而非设默认值 1
跨字段约束和运行时校验不能靠 struct tag 解决
validate:"eqfield=Password" 这类静态规则能处理简单一致性，但“支付金额 ≤ 用户余额”、“type=email 时 value 必须通过邮箱格式校验”这类逻辑，struct tag 无法表达，硬塞进去只会让校验器变脆弱。
立即学习“go语言免费学习笔记（深入）”；
- 把校验逻辑从结构体解耦：接收原始
map[string][]string或已解析的 struct，交由纯函数判断，例如ValidateTransferAmount(ctx, req *TransferReq) error - 查 DB 类校验（如用户名是否已存在）必须放 service 层或单独校验器，不在 binding 阶段做——避免 Gin ShouldBind 因 panic 导致错误信息丢失
- 错误要能定位到字段：返回
validator.FieldError类型错误，或用fmt.Errorf("amount: %w", err)包装，并在统一错误处理中间件中提取前缀
validate:"required"，也调了 v.Struct()，但没统一错误翻译、没剥离字段名前缀、没区分 validation error 和业务 error，结果前端收到 "Key: 'UserReq.Name' Error:'Field validation for 'Name' failed on the 'required' tag'" 这种消息——既难读，又暴露结构体名。 
