Golang 结构体字段验证库 validate 使用指南

在 Go 语言中，validate 是一个流行的结构体字段验证库，它通过结构体标签来定义验证规则。下面我将详细介绍如何使用这个库。

安装

首先安装 validate 库：

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

基本用法

package main

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

// User 结构体定义验证规则
type User struct {
	FirstName      string     `validate:"required"`
	LastName       string     `validate:"required"`
	Age            uint8      `validate:"gte=0,lte=130"`
	Email          string     `validate:"required,email"`
	FavouriteColor string     `validate:"iscolor"`                // 必须是有效的颜色
	Addresses      []*Address `validate:"required,dive,required"` // dive 表示深入验证切片中的每个元素
}

// Address 子结构体
type Address struct {
	Street string `validate:"required"`
	City   string `validate:"required"`
	Planet string `validate:"required"`
	Phone  string `validate:"required"`
}

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

	// 验证结构体
	user := &User{
		FirstName:      "Badger",
		LastName:       "Smith",
		Age:            135, // 不符合 lte=130 规则
		Email:          "Badger.Smith@gmail.com",
		FavouriteColor: "#000-",
		Addresses: []*Address{
			{Street: "Eavesdown Docks", City: "Beijing", Planet: "Earth", Phone: "none"},
			{Street: "", City: "Beijing", Planet: "Earth", Phone: "none"}, // 缺少 Street
		},
	}

	// 执行验证
	err := validate.Struct(user)
	if err != nil {
		// 处理验证错误
		for _, err := range err.(validator.ValidationErrors) {
			fmt.Printf("字段 %s 验证失败: 标签 %s 的值 '%v' 不满足条件\n", 
				err.Field(), err.Tag(), err.Value())
		}
		return
	}
	
	fmt.Println("验证通过")
}

常用验证标签

validate 提供了丰富的验证标签：

• required - 字段不能为零值
• omitempty - 如果字段为空则跳过验证
• len=10 - 长度必须等于10
• min=1 - 最小值为1
• max=10 - 最大值为10
• eq=10 - 必须等于10
• ne=10 - 必须不等于10
• gt=10 - 必须大于10
• gte=10 - 必须大于或等于10
• lt=10 - 必须小于10
• lte=10 - 必须小于或等于10
• eqfield=Field - 必须等于另一个字段的值
• nefield=Field - 必须不等于另一个字段的值
• alpha - 只能包含字母字符
• alphanum - 只能包含字母和数字字符
• numeric - 必须是有效的数字值
• hexadecimal - 必须是有效的十六进制
• hexcolor - 必须是有效的十六进制颜色
• rgb - 必须是有效的RGB颜色
• rgba - 必须是有效的RGBA颜色
• hsl - 必须是有效的HSL颜色
• hsla - 必须是有效的HSLA颜色
• email - 必须是有效的电子邮件
• url - 必须是有效的URL
• uri - 必须是有效的URI
• uuid - 必须是有效的UUID
• uuid3 - 必须是有效的v3 UUID
• uuid4 - 必须是有效的v4 UUID
• uuid5 - 必须是有效的v5 UUID
• datetime=2006-01-02 - 必须匹配给定的日期时间格式
• timezone - 必须是有效的时区名称
• ip - 必须是有效的IP地址
• ipv4 - 必须是有效的IPv4地址
• ipv6 - 必须是有效的IPv6地址
• mac - 必须是有效的MAC地址

自定义验证规则

你可以注册自定义验证函数：

package main

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

// 自定义验证函数
func validateCool(fl validator.FieldLevel) bool {
	return fl.Field().String() == "cool"
}

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

	type User struct {
		Name string `validate:"required,cool"`
	}

	user := User{Name: "hot"}
	err := validate.Struct(user)
	if err != nil {
		for _, err := range err.(validator.ValidationErrors) {
			fmt.Printf("字段 %s 验证失败: 标签 %s 的值 '%v' 不满足条件\n", 
				err.Field(), err.Tag(), err.Value())
		}
		return
	}
	
	fmt.Println("验证通过")
}

国际化错误消息

validate 支持错误消息的国际化：

package main

import (
	"fmt"
	"github.com/go-playground/locales/zh"
	ut "github.com/go-playground/universal-translator"
	"github.com/go-playground/validator/v10"
	zh_translations "github.com/go-playground/validator/v10/translations/zh"
)

type User struct {
	Username string `validate:"required"`
	Email    string `validate:"required,email"`
}

func main() {
	// 中文翻译器
	zh_ch := zh.New()
	uni := ut.New(zh_ch, zh_ch)
	trans, _ := uni.GetTranslator("zh")
	
	validate := validator.New()
	// 注册中文翻译
	_ = zh_translations.RegisterDefaultTranslations(validate, trans)
	
	user := User{
		Username: "",
		Email:    "invalid",
	}
	
	err := validate.Struct(user)
	if err != nil {
		errs := err.(validator.ValidationErrors)
		for _, e := range errs {
			// 翻译错误消息
			fmt.Println(e.Translate(trans))
		}
	}
}

性能优化

对于高性能场景，可以预编译验证器：

package main

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

type User struct {
	Name string `validate:"required"`
	Age  int    `validate:"min=18"`
}

var validate *validator.Validate

func init() {
	validate = validator.New()
}

func main() {
	user := User{Name: "John", Age: 20}
	if err := validate.Struct(user); err != nil {
		fmt.Println(err)
	}
}

总结

validate 库提供了强大而灵活的结构体验证功能，通过结构体标签可以轻松定义验证规则，支持丰富的内置验证器和自定义验证器，还能实现错误消息的国际化。它是 Go 语言中最流行的验证库之一，适合各种规模的应用程序。