直接使用 go-playground/validator 会 panic：nil pointer 错误，是因为多数人未初始化 validator 实例就调用 Validate.Struct()；必须显式创建并复用全局 validator.New() 实例，否则因 nil 指针解引用触发 panic。
为什么直接用 go-playground/validator 会 panic：nil pointer 错误？
多数人第一次集成时，在结构体字段上加了 validate tag 却没初始化 validator 实例，调用 Validate.Struct() 就 panic。这不是库的问题，而是漏掉了核心步骤：必须显式创建并复用一个全局 validator.Validate 实例。
正确做法是声明一个包级变量：
var validate *validator.Validate
func init() {
validate = validator.New()
// 可选：注册自定义校验器、翻译器等
}
切记不要每次校验都 new 一个 —— 它内部缓存了反射信息和编译后的校验逻辑，重复 new 会导致性能下降且丢失自定义规则。
struct tag 写错导致校验完全不生效的常见写法
最常踩的坑是 tag 名写成 validation、valid 或漏掉引号，比如：json:"name" validation:"required" 是无效的。go-playground 只认 validate 这个 key。
立即学习“go语言免费学习笔记（深入）”；
-
validate:"required"✅ 正确 -
validation:"required"❌ 不识别，跳过校验 -
validate:required❌ 缺少引号，解析失败，静默忽略 -
validate:"required,email"✅ 多规则用逗号分隔
嵌套结构体要加 validate:"dive"，否则内层字段不会被递归校验：
type User struct {
Name string `validate:"required"`
Email string `validate:"required,email"`
Addr Address `validate:"required,dive"` // 必须加 dive
}
type Address struct {
City string `validate:"required"`
}
如何让错误提示更友好（而不是返回英文字段名）
默认错误信息像 Key: 'User.Email' Error:Field validation for 'Email' failed on the 'email' tag，前端没法直接展示。需要绑定中文翻译器。
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
推荐用官方维护的 go-playground/locales + uni 包：
import (
"github.com/go-playground/locales/zh"
ut "github.com/go-playground/universal-translator"
"gopkg.in/go-playground/validator.v9"
)
var trans ut.Translator
func init() {
zhT := zh.New()
uni := ut.New(zhT, zhT)
trans, _ = uni.GetTranslator("zh")
validate.RegisterTranslation("required", trans, func(ut ut.Translator) error {
return ut.Add("required", "{0} 不能为空", true)
}, func(ut ut.Translator, fe validator.FieldError) string {
t, _ := ut.T("required", fe.Field())
return t
})
}
之后调用 validate.StructCtx(ctx, obj) 得到 ValidationErrors 后，用 err.Translate(trans) 即可输出中文。
注意：v9 版本中 Translate() 返回的是 map[string]string，不是单条字符串；v10+ 改为 err.Error() 配合 SetTag 控制格式。
HTTP handler 中怎么安全、高效地校验请求数据？
别在 handler 里直接 json.Unmarshal() 后调用 Validate.Struct() —— 出错时无法区分是解析失败还是校验失败。应该把解码和校验封装成原子操作。
推荐写法：
func bindAndValidate(r *http.Request, dst interface{}) error {
if err := json.NewDecoder(r.Body).Decode(dst); err != nil {
return fmt.Errorf("json decode: %w", err)
}
return validate.Struct(dst)
}
func userHandler(w http.ResponseWriter, r *http.Request) {
var u User
if err := bindAndValidate(r, &u); err != nil {
if _, ok := err.(validator.ValidationErrors); ok {
// 校验失败：返回结构化错误（如 map[field]error）
http.Error(w, err.Error(), http.StatusBadRequest)
return
}
// 解析失败：返回 400 或 500 视情况而定
http.Error(w, "bad request", http.StatusBadRequest)
return
}
// 处理业务逻辑
}
额外提醒：如果用了 Gin/Echo 等框架，它们内置的 binding 已集成了 validator，但要注意确认版本是否匹配（Gin v1.9+ 默认用 v10，而很多教程仍按 v9 写法）。
真正麻烦的是跨服务校验一致性 —— 比如前端用 same rules 生成 JSON Schema，后端 validator 却不支持 minLength 对应的 min=3 写法。这时候得自己桥接或统一用 OpenAPI Spec 驱动校验逻辑。
