Golang结构体与字段验证工具插件库validator的使用

简介

validator是一个用于结构体和字段验证的Go语言库，它基于标签(tag)实现验证功能。该库具有以下独特特性：

• 通过验证标签或自定义验证器实现跨字段和跨结构体验证
• 支持切片、数组和映射的多层级验证
• 可以验证映射的键和值
• 处理接口类型时会先确定其底层类型
• 支持自定义字段类型如sql driver Valuer
• 验证标签别名，允许将多个验证映射到单个标签
• 可提取自定义字段名称
• 支持可定制的国际化错误消息
• 是gin框架的默认验证器

安装

使用go get安装：

go get github.com/go-playground/validator/v10

然后在代码中导入：

import "github.com/go-playground/validator/v10"

基本使用示例

下面是一个完整的示例，展示如何使用validator验证结构体字段：

package main

import (
	"fmt"
	"github.com/go-playground/validator/v10"
)

// 定义一个用户结构体
type User struct {
	FirstName string `validate:"required"`          // 必填字段
	LastName  string `validate:"required"`          // 必填字段
	Age       uint   `validate:"gte=18,lte=130"`    // 年龄必须在18到130之间
	Email     string `validate:"required,email"`    // 必填且必须是有效邮箱格式
}

func main() {
	// 创建验证器实例
	validate := validator.New(validator.WithRequiredStructEnabled())

	// 创建测试用户
	user := &User{
		FirstName: "John",
		LastName:  "Doe",
		Age:       25,
		Email:     "john.doe@example.com",
	}

	// 验证结构体
	err := validate.Struct(user)
	if err != nil {
		// 如果有错误，转换为验证错误类型
		if validationErrors, ok := err.(validator.ValidationErrors); ok {
			for _, fieldError := range validationErrors {
				fmt.Printf("字段 %s 验证失败: %s\n", fieldError.Field(), fieldError.Tag())
			}
		}
		return
	}

	fmt.Println("用户数据验证通过")
}

验证标签说明

validator支持多种验证标签，以下是一些常用标签：

字段比较

字符串验证

格式验证

数值验证

其他验证

高级示例

嵌套结构体验证

package main

import (
	"fmt"
	"github.com/go-playground/validator/v10"
)

// 地址结构体
type Address struct {
	Street string `validate:"required"`
	City   string `validate:"required"`
	Zip    string `validate:"required,len=6"`
}

// 用户结构体包含嵌套地址
type User struct {
	Name    string  `validate:"required"`
	Age     int     `validate:"gte=18"`
	Address Address `validate:"required"`
}

func main() {
	validate := validator.New()

	user := User{
		Name: "Alice",
		Age:  25,
		Address: Address{
			Street: "123 Main St",
			City:   "New York",
			Zip:    "10001",
		},
	}

	err := validate.Struct(user)
	if err != nil {
		if validationErrors, ok := err.(validator.ValidationErrors); ok {
			for _, fieldError := range validationErrors {
				fmt.Printf("错误: 字段 %s 验证失败: %s\n", fieldError.Field(), fieldError.Tag())
			}
		}
		return
	}

	fmt.Println("用户数据验证通过")
}

自定义验证函数

package main

import (
	"fmt"
	"github.com/go-playground/validator/v10"
)

// 自定义验证函数
func validateCountryCode(fl validator.FieldLevel) bool {
	countryCode := fl.Field().String()
	// 简单的国家代码验证
	return countryCode == "US" || countryCode == "CN" || countryCode == "JP"
}

type User struct {
	Name        string `validate:"required"`
	CountryCode string `validate:"required,countrycode"` // 使用自定义验证标签
}

func main() {
	validate := validator.New()
	
	// 注册自定义验证函数
	_ = validate.RegisterValidation("countrycode", validateCountryCode)

	user := User{
		Name:        "Bob",
		CountryCode: "UK", // 无效的国家代码
	}

	err := validate.Struct(user)
	if err != nil {
		if validationErrors, ok := err.(validator.ValidationErrors); ok {
			for _, fieldError := range validationErrors {
				fmt.Printf("错误: 字段 %s 验证失败: %s\n", fieldError.Field(), fieldError.Tag())
			}
		}
		return
	}

	fmt.Println("用户数据验证通过")
}

错误处理

验证函数返回error类型。如果验证失败，可以将错误转换为validator.ValidationErrors类型来获取详细的验证错误信息：

err := validate.Struct(mystruct)
if err != nil {
    if validationErrors, ok := err.(validator.ValidationErrors); ok {
        for _, fieldError := range validationErrors {
            fmt.Printf("字段 %s 验证失败: %s\n", fieldError.Field(), fieldError.Tag())
        }
    }
}

性能

validator经过高度优化，性能表现优异。在MacBook Pro Max M3上的基准测试结果如下：

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
BenchmarkFieldFailureParallel-16                                        17551471                83.68 ns/op          200 B/op          4 allocs/op

总结

validator是一个功能强大且灵活的Go语言验证库，适用于各种验证场景。通过结构体标签可以轻松定义验证规则，同时也支持自定义验证函数和复杂的验证逻辑。