nhost 项目中的 go-playground/validator v10:基于 Tag 的结构体校验完整实战指南
nhost 项目中的 go-playground/validator v10:基于 Tag 的结构体校验完整实战指南
导读:本文以 nhost 仓库中 vendored 的
github.com/go-playground/validator/v10(版本 v10.27.0)官方 README 为主体,系统讲解这套 Go 生态最常用的结构体/字段校验框架:从 tag 语法、内置验证器全表、跨字段与跨结构校验、slice/map 深入(dive)机制,到自定义验证器注册、错误类型设计与 i18n 翻译,并对照仓库源码(validator_instance.go、baked_in.go、errors.go)与 gin 框架的默认绑定集成,给出可直接落地到 API 层、配置解析层的校验方案。
一、包定位与核心设计理念
validator 是一个基于 struct tag 对结构体和单字段执行值校验的 Go 包。它不依赖代码生成,不侵入业务逻辑,而是通过在结构体字段上声明声明式的校验规则,在运行时用反射完成校验。nhost 仓库通过 go.mod(第 153 行,标注为 v10.27.0 // indirect)将其纳入依赖树,并随 vendor 目录一起托管在 vendor/github.com/go-playground/validator/v10/ 下。
从源码结构看,该包的能力由三个核心文件承载:
- baked_in.go:内置验证器(
bakedInValidators,约 170 个条目)与内置别名(bakedInAliases)的注册表; - validator_instance.go:
Validate实例的构造与全部公开 API(Struct、Var、RegisterValidation等); - errors.go:
ValidationErrors、InvalidValidationError等错误类型定义。
与其他校验库相比,它具备以下独有能力:
- 跨字段、跨结构校验:通过
eqfield、gtefield、eqcsfield等 tag,或自定义结构级验证器,比较同一结构体内部乃至不同结构体之间的字段; - Slice/Array/Map 深入校验(diving):借助
dive关键字,可校验多维切片、数组和映射的任意层级,且能同时深入 map 的 key 与 value; - interface 底层类型探测:校验
interface{}字段前先解析其真实底层类型; - 自定义字段类型支持:可接入
database/sql/driver的Valuer等实现了特定接口的类型; - 别名 tag:将多个验证组合映射到单个 tag,便于在结构体上复用;
- 自定义字段名提取:可指定在验证时提取 JSON 名称,并使其出现在
FieldError中; - 可定制的 i18n 错误消息:配合
universal-translator实现多语言错误文案。
二、安装与初始化
使用 go get 安装:
go get github.com/go-playground/validator/v10
在代码中导入:
import "github.com/go-playground/validator/v10"
创建校验器实例并初始化所有内置验证器:
validate := validator.New()
New(options ...Option) *Validate 在 validator_instance.go 中会以 bakedInAliases 和 bakedInValidators 的容量预分配 map,并将全部内置规则逐一复制到实例中——这意味着每个 Validate 实例都拥有一份独立可变的规则表,你可以在不影响全局的前提下增删改验证器。
2.1 推荐选项:WithRequiredStructEnabled
对于新用户,README 强烈建议在初始化时启用 WithRequiredStructEnabled 选项:
validate := validator.New(validator.WithRequiredStructEnabled())
该选项在 options.go 中定义,作用是让 required tag 对非指针结构体字段生效(默认行为下,结构体类型的 required 会被忽略)。这一行为是 v11+ 的默认走向,提前开启可避免未来升级时的行为变化。在 nhost 这样的长期演进项目中,建议所有新建的校验器实例都显式传入该选项。
三、错误返回值设计:为什么校验函数返回 error
所有校验函数统一返回 error 类型,这是刻意设计:早期 Go 社区常见的错误用法是让校验函数永远返回 err != nil(例如把校验结果写进一个已存在的 error 变量),导致 err != nil 判断形同虚设。该包通过让校验函数仅在真正失败时返回非 nil,规避了这一反模式(对应上游讨论见 validator issues #134)。
返回的错误只有三种可能:
nil:校验通过;InvalidValidationError:传入的校验输入本身非法(例如Struct收到非结构体、Var收到不可校验类型),绝大多数场景下可以忽略这种类型;ValidationErrors:字段校验失败的错误集合。
因此标准处理模式是:先判断 err != nil,再(按需)类型断言为 ValidationErrors 逐条处理:
err := validate.Struct(mystruct)
if err != nil {
validationErrors := err.(validator.ValidationErrors)
// 逐条处理 validationErrors
}
在 errors.go 中可以看到二者的定义:ValidationErrors 是 []FieldError 的别名(实现了 error 与 Errors 接口),而 InvalidValidationError 是一个携带 Type 与 Current 字段的小结构体。ValidationErrors 还提供 Translate(ut.Translator) 方法用于输出翻译后的消息,并可通过 ValidationErrorsTranslations(map[string]string)承载翻译结果。
四、基础用法:Struct / Var / VarWithValue
4.1 结构体验证
type User struct {
Name string `validate:"required"`
Age uint8 `validate:"gte=0,lte=130"`
Email string `validate:"required,email"`
Phone string `validate:"required,e164"`
}
user := &User{
Name: "nhost",
Age: 25,
Email: "dev@nhost.io",
Phone: "+15551234567",
}
err := validate.Struct(user)
Struct 会遍历结构体的每个字段,解析其 validate tag(默认 tag 名,可通过 SetTagName 修改),执行规则组合。同一条 tag 内用逗号分隔多个规则,任一失败即记录一条 FieldError。
4.2 单字段验证
不需要完整结构体时,用 Var 直接校验单个值:
err := validate.Var("test@example.com", "required,email")
对应实现见 validator_instance.go(Var 与其带 context 的 VarCtx 变体)。
4.3 与另一个值比较
VarWithValue 用于把当前值同另一个任意值比较,例如"确认密码":
err := validate.VarWithValue("password123", "password123", "eqfield")
对应实现见 validator_instance.go(VarWithValue / VarWithValueCtx)。
4.4 Context 变体
包内几乎所有核心方法都提供带 context.Context 的变体(StructCtx、VarCtx、VarWithValueCtx、RegisterValidationCtx 等),可在自定义验证器中感知取消信号与超时,适合在 HTTP 请求生命周期内做校验的场景。
五、内置验证器全表
以下验证器全部预置在 bakedInValidators 中(见 baked_in.go 第 79 行起的注册表),开箱即用。
5.1 Fields:字段间比较
| Tag | 描述 |
|---|---|
| eqcsfield | 字段等于另一字段(相对路径,跨结构) |
| eqfield | 字段等于另一字段 |
| fieldcontains | 字段中包含指定字符 |
| fieldexcludes | 字段中不包含指定字符 |
| gtcsfield | 字段大于另一相对字段 |
| gtecsfield | 字段大于等于另一相对字段 |
| gtefield | 字段大于等于另一字段 |
| gtfield | 字段大于另一字段 |
| ltcsfield | 字段小于另一相对字段 |
| ltecsfield | 字段小于等于另一相对字段 |
| ltefield | 字段小于等于另一字段 |
| ltfield | 字段小于另一字段 |
| necsfield | 字段不等于另一字段(相对路径) |
| nefield | 字段不等于另一字段 |
其中 eqfield/nefield/gtfield 等用于同一结构体内部的比较(如 ConfirmPassword 与 Password),以 cs 结尾的变体用于跨结构体比较(语法如 eqcsfield=InnerStruct.Field),详见下文第六节。
5.2 Network:网络相关
| Tag | 描述 |
|---|---|
| cidr | CIDR 网段 |
| cidrv4 | IPv4 CIDR 网段 |
| cidrv6 | IPv6 CIDR 网段 |
| datauri | Data URL |
| fqdn | 完全限定域名(FQDN) |
| hostname | 主机名(RFC 952) |
| hostname_port | 主机名:端口(HostPort) |
| hostname_rfc1123 | 主机名(RFC 1123) |
| ip | IP 地址 |
| ip4_addr | IPv4 地址 |
| ip6_addr | IPv6 地址 |
| ip_addr | IP 地址 |
| ipv4 | IPv4 地址 |
| ipv6 | IPv6 地址 |
| mac | MAC 地址 |
| tcp4_addr | TCPv4 地址 |
| tcp6_addr | TCPv6 地址 |
| tcp_addr | TCP 地址 |
| udp4_addr | UDPv4 地址 |
| udp6_addr | UDPv6 地址 |
| udp_addr | UDP 地址 |
| unix_addr | Unix 域套接字端点地址 |
| uri | URI 字符串 |
| url | URL 字符串 |
| http_url | HTTP URL 字符串 |
| url_encoded | URL 编码字符串 |
| urn_rfc2141 | URN(RFC 2141)字符串 |
这些验证器的正则与解析逻辑集中在 regexes.go,网络地址类校验(IP/MAC/端口)则由 net 标准库配合正则实现。
5.3 Strings:字符串特征
| Tag | 描述 |
|---|---|
| alpha | 仅字母 |
| alphanum | 字母数字 |
| alphanumunicode | Unicode 字母数字 |
| alphaunicode | Unicode 字母 |
| ascii | 仅 ASCII |
| boolean | 布尔值字符串 |
| contains | 包含指定子串 |
| containsany | 包含任意指定字符 |
| containsrune | 包含指定 rune |
| endsnotwith | 不以指定子串结尾 |
| endswith | 以指定子串结尾 |
| excludes | 不包含指定子串 |
| excludesall | 不包含任意指定字符 |
| excludesrune | 不包含指定 rune |
| lowercase | 全小写 |
| multibyte | 包含多字节字符 |
| number | 数字(number) |
| numeric | 数值(numeric) |
| printascii | 可打印 ASCII |
| startsnotwith | 不以指定子串开头 |
| startswith | 以指定子串开头 |
| uppercase | 全大写 |
5.4 Format:格式校验
| Tag | 描述 |
|---|---|
| base64 | Base64 字符串 |
| base64url | Base64URL 字符串 |
| base64rawurl | Base64RawURL 字符串 |
| bic | 银行识别码(ISO 9362,即 SWIFT/BIC) |
| bcp47_language_tag | 语言标签(BCP 47) |
| btc_addr | 比特币地址 |
| btc_addr_bech32 | 比特币 Bech32 地址(segwit) |
| credit_card | 信用卡号 |
| mongodb | MongoDB ObjectID |
| mongodb_connection_string | MongoDB 连接字符串 |
| cron | Cron 表达式 |
| spicedb | SpiceDb ObjectID/Permission/Type |
| datetime | 日期时间 |
| e164 | E.164 格式电话号码 |
| ein | 美国雇主识别号(EIN) |
| 邮箱字符串 | |
| eth_addr | 以太坊地址 |
| hexadecimal | 十六进制字符串 |
| hexcolor | 十六进制颜色 |
| hsl | HSL 颜色 |
| hsla | HSLA 颜色 |
| html | HTML 标签 |
| html_encoded | HTML 编码 |
| isbn | 国际标准书号(ISBN) |
| isbn10 | ISBN-10 |
| isbn13 | ISBN-13 |
| issn | 国际标准连续出版物号(ISSN) |
| iso3166_1_alpha2 | 两位国家代码(ISO 3166-1 alpha-2) |
| iso3166_1_alpha3 | 三位国家代码(ISO 3166-1 alpha-3) |
| iso3166_1_alpha_numeric | 数字国家代码(ISO 3166-1 numeric) |
| iso3166_2 | 国家细分代码(ISO 3166-2) |
| iso4217 | 货币代码(ISO 4217) |
| json | JSON |
| jwt | JSON Web Token(JWT) |
| latitude | 纬度 |
| longitude | 经度 |
| luhn_checksum | Luhn 算法校验和(适用于字符串与 (u)int) |
| postcode_iso3166_alpha2 | 邮政编码 |
| postcode_iso3166_alpha2_field | 邮政编码(按字段) |
| rgb | RGB 颜色 |
| rgba | RGBA 颜色 |
| ssn | 美国社会安全号码(SSN) |
| timezone | 时区 |
| uuid | UUID |
| uuid3 | UUID v3 |
| uuid3_rfc4122 | UUID v3(RFC 4122) |
| uuid4 | UUID v4 |
| uuid4_rfc4122 | UUID v4(RFC 4122) |
| uuid5 | UUID v5 |
| uuid5_rfc4122 | UUID v5(RFC 4122) |
| uuid_rfc4122 | UUID(RFC 4122) |
| md4 | MD4 哈希 |
| md5 | MD5 哈希 |
| sha256 | SHA256 哈希 |
| sha384 | SHA384 哈希 |
| sha512 | SHA512 哈希 |
| ripemd128 | RIPEMD-128 哈希 |
| ripemd160 | RIPEMD-160 哈希 |
| tiger128 | TIGER128 哈希 |
| tiger160 | TIGER160 哈希 |
| tiger192 | TIGER192 哈希 |
| semver | 语义化版本 2.0.0 |
| ulid | ULID(字典序可排序唯一标识) |
| cve | CVE 标识符 |
其中国家代码、货币代码、邮编正则分别由 country_codes.go、currency_codes.go、postcode_regexes.go 提供数据支撑。
5.5 Comparisons:比较
| Tag | 描述 |
|---|---|
| eq | 等于 |
| eq_ignore_case | 忽略大小写等于 |
| gt | 大于 |
| gte | 大于等于 |
| lt | 小于 |
| lte | 小于等于 |
| ne | 不等于 |
| ne_ignore_case | 忽略大小写不等于 |
5.6 Other:其他常用规则
| Tag | 描述 |
|---|---|
| dir | 已存在的目录 |
| dirpath | 目录路径 |
| file | 已存在的文件 |
| filepath | 文件路径 |
| image | 图片 |
| isdefault | 是否为默认值 |
| len | 长度 |
| max | 最大值/最大长度 |
| min | 最小值/最小长度 |
| oneof | 取值之一 |
| required | 必填 |
| required_if | 若条件满足则必填 |
| required_unless | 除非条件满足否则必填 |
| required_with | 与指定字段同现时必填 |
| required_with_all | 与所有指定字段同现时必填 |
| required_without | 未指定字段时必填 |
| required_without_all | 所有指定字段均缺省时必填 |
| excluded_if | 若条件满足则禁止存在 |
| excluded_unless | 除非条件满足否则禁止存在 |
| excluded_with | 与指定字段同现时禁止存在 |
| excluded_with_all | 与所有指定字段同现时禁止存在 |
| excluded_without | 未指定字段时禁止存在 |
| excluded_without_all | 所有指定字段均缺省时禁止存在 |
| unique | 唯一(slice/map 内无重复) |
| validateFn | 验证指定方法 Validate() error 是否返回 nil(或任意指定方法) |
条件型规则(required_if、required_unless、skip_unless、excluded_* 系列)在 baked_in.go 中均有对应实现函数(requiredIf、requiredUnless、skipUnless、excludedIf 等),它们允许你基于同结构体内其他字段的取值动态决定当前字段的必填/排除状态,是实现复杂表单校验的关键工具。
5.7 Aliases:别名
| Tag | 描述 |
|---|---|
| iscolor | hexcolor|rgb|rgba|hsl|hsla |
| country_code | iso3166_1_alpha2|iso3166_1_alpha3|iso3166_1_alpha_numeric |
别名在 baked_in.go 第 70 行起的 bakedInAliases 中定义,此外还包含 README 未单独列出的 eu_country_code(欧盟国家代码组合)。你同样可以通过 RegisterAlias 注册业务自定义别名,例如把一组正则校验收敛成一个 tag。
六、跨字段与跨结构校验
6.1 同结构体跨字段
type RegisterForm struct {
Password string `validate:"required,min=8"`
ConfirmPassword string `validate:"required,eqfield=Password"`
}
eqfield=Password 要求 ConfirmPassword 与 Password 完全相等。同类规则还有 nefield(不等于)、gtfield/gtefield/ltfield/ltefield(数值比较)、fieldcontains/fieldexcludes(字符包含)。
6.2 跨结构体比较
当比较目标位于另一结构体(或嵌套结构)时,使用以 cs 结尾的 tag,语法为 eqcsfield=OuterStruct.InnerStruct.Field:
type Inner struct {
StartDate time.Time
}
type Outer struct {
InnerStruct Inner `validate:"dive"`
EndDate time.Time `validate:"gtecsfield=InnerStruct.StartDate"`
}
gtecsfield=InnerStruct.StartDate 要求 EndDate 不早于内层结构的 StartDate。跨结构校验的底层实现在 baked_in.go 的 isXxxCrossStructField 系列函数中,它们通过相对路径表达式在反射树上定位目标字段。
七、dive:深入 Slice / Array / Map
dive 是 validator 最具标志性的能力——校验容器元素的每一层。规则写在 dive 之后,作用于当前容器的元素。
7.1 切片/数组深入
type Tags struct {
Names []string `validate:"required,dive,required,alpha"`
}
含义:Names 本身必填(非空切片),dive 进入每个元素,要求每个元素均为必填且纯字母。多维场景可叠加:
Matrix [][]int `validate:"required,dive,dive,gt=0"`
两层 dive 分别穿透外层切片和内层切片,最终要求每个内层元素 > 0。
7.2 Map 的 key 与 value 同时深入
dive 默认深入 map 的 value;若要连 key 一起校验,需在 dive 前使用 keys / endkeys 包裹 key 规则:
type Config struct {
Settings map[string]int `validate:"required,keys,alpha,endkeys,dive,gt=0"`
}
keys,alpha,endkeys 校验每个 key 为纯字母,dive 后的 gt=0 校验每个 value 为正数。对应基准测试 BenchmarkFieldMapDiveWithKeys* 验证了这条路径的完备性。
7.3 深入嵌套结构体
type User struct {
Address Address `validate:"dive"`
}
dive 让校验递归进入 Address 结构体内部字段,逐层应用其自身的 tag 规则。
八、自定义验证器、别名与自定义类型
8.1 注册自定义验证器
通过 validator_instance.go 中的 RegisterValidation / RegisterValidationCtx 注册:
validate.RegisterValidation("is-awesome", func(fl validator.FieldLevel) bool {
return fl.Field().String() == "awesome"
})
RegisterValidation(tag, fn, callValidationEvenIfNull ...bool):注册无 context 的校验函数;RegisterValidationCtx:注册带context.Context的版本;- 第三个可变参数
callValidationEvenIfNull默认为 false,即字段为零值/空值时跳过该校验器,需要"空值也校验"时传true; - 注册时会校验 tag 是否与内置规则冲突、是否包含保留字符(见
registerValidation中restrictedTagChars检查)。
8.2 结构级校验
字段级 tag 无法表达"跨多个字段的整体约束"(如 start < end 的区间合法性)时,用 RegisterStructValidation 注册结构级校验器:
validate.RegisterStructValidation(func(sl validator.StructLevel) {
s := sl.Current().Interface().(Range)
if s.Start.After(s.End) {
sl.ReportError(s.End, "End", "end", "gtfield", "Start")
}
}, Range{})
RegisterStructValidationMapRules 则允许以 map[string]string 声明式映射字段规则,无需手写回调。
8.3 自定义字段类型
通过 RegisterCustomTypeFunc 为特定 Go 类型提供取值函数,典型场景是 database/sql 的可空类型与 driver.Valuer 实现:
validate.RegisterCustomTypeFunc(ValidateValuer, sql.NullString{}, sql.NullInt64{})
见 validator_instance.go。校验器会调用该函数提取实际值后再应用规则。
8.4 自定义字段名提取
默认 FieldError 中的字段名是 Go 结构体字段名;通过 RegisterTagNameFunc 可改为提取 JSON 名称:
validate.RegisterTagNameFunc(func(fld reflect.StructField) string {
name := strings.SplitN(fld.Tag.Get("json"), ",", 2)[0]
if name == "-" {
return ""
}
return name
})
这样错误消息中展示的就是 json tag 指定的对外名称,与 API 响应字段保持一致。
8.5 修改默认 tag 名
默认规则 tag 名为 validate,可通过 SetTagName 替换,例如与 json 共用一套声明:
validate.SetTagName("validate")
九、i18n 错误消息翻译
validator 与 go-playground/locales、go-playground/universal-translator 配合实现多语言错误消息(nhost 的 go.mod 中这两个包同样以 indirect 依赖存在)。注册流程:
import (
"github.com/go-playground/locales/zh"
ut "github.com/go-playground/universal-translator"
"github.com/go-playground/validator/v10/translations/zh"
)
zhT := zh.New()
uni := ut.New(zhT, zhT)
trans, _ := uni.GetTranslator("zh")
_ = zhtranslations.RegisterDefaultTranslations(validate, trans)
校验失败后调用 ValidationErrors.Translate(trans) 即可获得本地化消息;若想精确控制某个 tag 的翻译文案,可用 validator_instance.go 的 RegisterTranslation 注册自定义翻译函数(registerFn 负责注册规则与占位符,translationFn 负责生成最终文案)。
十、与 gin 框架的集成(nhost 的实际使用形态)
nhost 的 Go 侧依赖通过 gin 间接引入 validator:在 vendor/github.com/gin-gonic/gin/binding/default_validator.go 中,gin 的默认 StructValidator 实现内部持有一个 validator.Validate 实例,ValidateStruct 最终调用 validate.Struct(obj),并且暴露 Engine() 方法返回底层 validator 实例——这意味着你可以在 gin 应用中通过 binding.Validator.Engine().(*validator.Validate) 取出该实例,继续注册自定义验证器与翻译器。
在 nhost 的依赖图中,validator 被标记为 // indirect,即它不是被项目代码直接 import,而是经由 gin 等依赖引入;go.sum 中记录的版本与 go.mod 第 153 行一致,为 v10.27.0。因此,凡是 nhost 中经由 gin 处理 HTTP 请求绑定的 Go 服务(如 CLI 的 configserver、各后台服务),其 ShouldBind / Bind 流程的字段校验默认都走这套 tag 体系——为这些服务的 API 请求结构体声明 validate tag 即可获得开箱即用的参数校验。
十一、性能基准
README 附带了官方在 MacBook Pro Max M3(go1.23.3 darwin/arm64)上运行的基准数据(节选核心项,-16 表示 16 核并行):
BenchmarkFieldSuccess-16 42461943 27.88 ns/op 0 B/op 0 allocs/op
BenchmarkFieldSuccessParallel-16 486632887 2.289 ns/op 0 B/op 0 allocs/op
BenchmarkFieldFailure-16 9566167 121.3 ns/op 200 B/op 4 allocs/op
BenchmarkFieldArrayDiveSuccess-16 7602306 155.6 ns/op 97 B/op 5 allocs/op
BenchmarkFieldArrayDiveFailure-16 4659756 252.9 ns/op 301 B/op 10 allocs/op
BenchmarkFieldMapDiveWithKeysSuccess-16 2544975 464.8 ns/op 288 B/op 14 allocs/op
BenchmarkFieldMapDiveWithKeysFailure-16 2435484 490.7 ns/op 553 B/op 16 allocs/op
BenchmarkFieldCustomTypeSuccess-16 14943525 77.35 ns/op 32 B/op 2 allocs/op
BenchmarkStructLevelValidationSuccess-16 16808389 70.25 ns/op 16 B/op 1 allocs/op
BenchmarkStructSimpleCrossFieldSuccess-16 6459542 183.4 ns/op 56 B/op 3 allocs/op
BenchmarkStructSimpleCrossStructCrossFieldSuccess-16 4448528 267.7 ns/op 64 B/op 4 allocs/op
BenchmarkStructSimpleSuccess-16 10675562 109.5 ns/op 0 B/op 0 allocs/op
BenchmarkStructComplexSuccess-16 2073470 576.0 ns/op 224 B/op 5 allocs/op
BenchmarkStructComplexFailure-16 576358 2001 ns/op 3042 B/op 48 allocs/op
BenchmarkOneof-16 22503973 52.82 ns/op 0 B/op 0 allocs/op
从数据可以读出的实践结论:校验成功路径零分配(0 B/op, 0 allocs/op),失败路径的分配主要来自错误收集;复杂结构体(BenchmarkStructComplex*)失败时因要组装完整的 FieldError 集合而开销最大。对高频调用(如中间件内的逐请求校验)建议复用 Validate 实例,避免重复初始化内置规则表。
十二、配套软件与维护策略
12.1 配套库
go-playground/form:在url.Values与 Go 值之间双向编解码,支持数组与完整 map,可作为校验前/后的数据转换层;go-playground/mold:通用数据改写/设定库,用于在校验前对结构体内的数据做规范化(trim、默认值等)。
二者与 validator 组成"转换 → 清洗 → 校验"的完整数据管道。
12.2 版本支持策略
该包遵循 Go 官方发布策略,保证支持最近两个大版本,这并不意味着旧版本不可用,而是保留了在需要修复安全问题、操作系统兼容性或引入重大功能时提升最低支持 Go 版本(MSGV)的权利;MSGV 的提升只会随 Minor 版本发布进行,不会在 patch 版本中突然发生。对 nhost 这类长期维护的仓库,跟随 v10 的最新 minor 版本(当前 vendored 为 v10.27.0)即可获得修复与新增验证器的持续同步。
12.3 许可证
validator 以 MIT 许可证分发(见 vendor/github.com/go-playground/validator/v10/LICENSE),可自由用于开源与商业项目。
十三、小结:在 nhost 项目中落地的建议
综合 README 与仓库源码,在 nhost 的 Go 代码中落地 validator 时建议遵循以下实践:
- 统一初始化:
validator.New(validator.WithRequiredStructEnabled())作为默认工厂,避免 v11 升级时的行为漂移; - 为所有 API 请求结构体声明
validatetag:借助 gin 绑定层自动生效,失败后统一转换为ValidationErrors并序列化为结构化响应; - 复杂表单优先条件规则:用
required_if/excluded_unless等条件 tag 表达动态必填,减少手写 if 分支; - 容器校验善用
dive与keys/endkeys:一行 tag 即可覆盖多维数组与 map 的 key/value; - 业务规则用自定义验证器 + 结构级校验:通过
RegisterValidation/RegisterStructValidation收敛到可测试的独立函数; - 对外暴露 JSON 字段名并本地化错误:
RegisterTagNameFunc+RegisterTranslation让校验错误直接可用于前端展示。