Golang结构体标签校验实现自动数据结构绑定-Golang-PHP中文网

必须使用 validate 作为 struct tag 键名，因 go-playground/validator 仅识别该键；需全局复用 validator 实例、字段必须导出、json 与 validate tag 要对齐，错误需类型断言为 validationerrors 提取字段级信息。

golang结构体标签校验实现自动数据结构绑定

struct tag 里用 `validate` 而不是 `valid` 或自定义字段名

Go 标准库不解析校验标签，必须依赖第三方库（如 go-playground/validator），而它约定使用 validate 这个 key。写成 valid、validation 或 check 都不会被识别——连 warning 都没有，静默失效。

常见错误现象：结构体字段明明写了 `json:"name" valid:"required"`，但调用 Validate.Struct() 却始终返回 nil 错误。

必须统一用 validate 作为 struct tag 的键名
值部分支持链式规则，比如 validate:"required,email,max=100"
嵌套结构体默认不递归校验，需显式加 validate:"dive"
指针字段要小心空指针 panic，建议配合 omitempty 或前置判空

初始化 validator 实例时启用 `ValidateStruct` 的 struct cache

每次调用 validate.Struct() 若没复用 validator 实例，会反复反射解析 struct tag，性能损耗明显。尤其在 HTTP handler 中高频调用时，QPS 可能掉 30%+。

正确做法是全局复用一个 *validator.Validate 实例，并在初始化时注册自定义函数（如手机号、身份证号校验）：

Golang Naming

Go（Golang）命名规范 — 包括包、构造函数、结构体、接口、常量、枚举、错误、布尔值、接收器、getter/setter、函数等。

下载

var validate *validator.Validate

func init() {
    validate = validator.New()
    validate.RegisterValidation("chinese_mobile", validateChineseMobile)
}

不要在 handler 里每次 new 一个 validator.New()
注册自定义校验函数必须在首次调用 Struct() 前完成
若用 SetTagName("validate") 改了 tag 名，所有 struct 都得同步改，不推荐

绑定 JSON 请求体时，`json` tag 和 `validate` tag 要对齐字段可导出性

如果结构体字段首字母小写（未导出），json 解码会失败，validate 校验也根本跑不到——因为字段压根没被反序列化进来。

典型错误场景：前端传了 {"user_name":"foo"}，后端定义 UserName string `json:"user_name" validate:"required"` 是对的；但若写成 userName string（小写 u），则解码后字段为空，校验跳过，且无任何提示。

所有参与绑定和校验的字段必须是导出字段（首字母大写）
json tag 的 value 和实际传入 key 必须完全一致（区分大小写、下划线）
可加 omitempty 避免零值干扰，但 validate:"required" 与之不冲突——required 检查的是字段是否被设置，不是是否为零值
时间字段建议用 time.Time + time.UnmarshalJSON，别用字符串手动 parse

错误信息提取别直接用 `err.Error()`，要用 `validator.ValidationErrors` 类型断言

Validate.Struct() 返回的 error 是个 interface，直接 err.Error() 得到的是全量堆栈式字符串，没法做前端友好的字段级提示（比如“邮箱格式错误”对应到 email 字段）。

必须类型断言为 validator.ValidationErrors，再遍历每个 FieldError 提取 Field()、Tag()、Value()：

if err != nil {
    if errs, ok := err.(validator.ValidationErrors); ok {
        for _, e := range errs {
            log.Printf("field %s failed %s, value: %v", 
                e.Field(), e.Tag(), e.Value())
        }
    }
}