别着急，坐和放宽
使用社交账号登录
在 Go Web 开发中，数据验证是一个必不可少的环节。github.com/go-playground/validator/v10 是 Go 生态中最流行的验证库之一，但其默认的错误信息对用户并不友好。本文将详细介绍如何自定义验证错误信息，让你的 API 返回更加友好、易懂的错误提示。
使用原生 validator 时，错误信息通常是这样的：
这样的错误信息对开发者友好，但对最终用户来说可读性很差。我们希望的错误信息是：
email is required; age must be at least 18
首先，我们创建一个自定义的 CustomValidator 结构体，包装 validator 实例：
核心是实现 Validate 方法，该方法会被 Echo 框架自动调用：
在实际项目中，我们经常会遇到嵌套结构体和数组字段的验证。为了支持这些场景，需要实现递归查找字段的功能：
处理带数组索引的命名空间（如 Product.Tags[0].Name）：
解析 validate tag 中的参数信息：
核心方法：根据不同的验证规则生成对应的友好提示：
输入：
输出（原生 validator）：
输出（自定义 validator）：
你可以根据请求的语言返回不同的错误信息：
对于高频调用的场景，可以缓存反射的结果：
确保 validator.Validate 实例在整个应用生命周期中复用，避免重复创建。
通过本文介绍的方法，我们实现了：
msg tag 可以完全自定义错误信息这套方案在生产环境中经过验证，可以大幅提升 API 的用户体验。你可以根据项目需求进一步扩展和优化。
Key: 'User.Email' Error:Field validation for 'Email' failed on the 'required' tag
Key: 'User.Age' Error:Field validation for 'Age' failed on the 'min' tag
package server
import (
"errors"
"fmt"
"reflect"
"strings"
"github.com/go-playground/validator/v10"
"github.com/labstack/echo/v4"
)
type CustomValidator struct {
Validator *validator.Validate
}
func (cv *CustomValidator) Validate(req interface{}) error {
if err := cv.Validator.Struct(req); err != nil {
// 获取结构体类型信息
dataType := reflect.TypeOf(req)
if dataType.Kind() == reflect.Ptr {
dataType = dataType.Elem()
}
var errMsg []string
// 遍历所有验证错误
for _, fieldErr := range err.(validator.ValidationErrors) {
// 查找字段（支持嵌套和数组）
structField, found := cv.findNestedField(dataType, fieldErr)
if !found {
return fmt.Errorf("field %s not found", fieldErr.StructField())
}
// 解析 validate tag 的详细信息
tagDetails := parseValidateTag(structField)
// 生成友好的错误信息
em := getValidationMessage(structField, fieldErr.Tag(), tagDetails)
errMsg = append(errMsg, em)
}
if len(errMsg) != 0 {
return errors.New(strings.Join(errMsg, "; "))
}
return err
}
return nil
}
func (cv *CustomValidator) findNestedField(rootType reflect.Type, fieldErr validator.FieldError) (reflect.StructField, bool) {
// 首先尝试直接查找
if structField, found := rootType.FieldByName(fieldErr.StructField()); found {
return structField, true
}
// 如果没找到，解析命名空间路径
namespace := fieldErr.Namespace()
structField := fieldErr.StructField()
// 解析命名空间以找到嵌套路径
// 例如: "Product.ProductTags[0].TagName" -> ["Product", "ProductTags", "TagName"]
pathParts := cv.parseNamespacePath(namespace, structField)
if len(pathParts) <= 1 {
return reflect.StructField{}, false
}
// 通过嵌套结构导航
return cv.findFieldByPath(rootType, pathParts[1:]) // 跳过根结构体名称
}
func (cv *CustomValidator) findFieldByPath(rootType reflect.Type, pathParts []string) (reflect.StructField, bool) {
currentType := rootType
for i, part := range pathParts {
field, found := currentType.FieldByName(part)
if !found {
return reflect.StructField{}, false
}
// 如果这是最后一部分，返回字段
if i == len(pathParts)-1 {
return field, true
}
// 导航到下一层级
fieldType := field.Type
// 处理指针类型
if fieldType.Kind() == reflect.Ptr {
fieldType = fieldType.Elem()
}
// 处理切片/数组类型
if fieldType.Kind() == reflect.Slice || fieldType.Kind() == reflect.Array {
fieldType = fieldType.Elem()
if fieldType.Kind() == reflect.Ptr {
fieldType = fieldType.Elem()
}
}
// 必须是结构体才能继续
if fieldType.Kind() != reflect.Struct {
return reflect.StructField{}, false
}
currentType = fieldType
}
return reflect.StructField{}, false
}
func (cv *CustomValidator) parseNamespacePath(namespace, structField string) []string {
// 移除数组索引，如 [0], [1] 等
cleanNamespace := cv.removeArrayIndices(namespace)
// 通过点号分割路径组件
parts := strings.Split(cleanNamespace, ".")
// 确保 structField 包含在路径中
if len(parts) > 0 && parts[len(parts)-1] != structField {
for i, part := range parts {
if part == structField {
return parts[:i+1]
}
}
parts = append(parts, structField)
}
return parts
}
func (cv *CustomValidator) removeArrayIndices(namespace string) string {
result := ""
inBracket := false
for _, char := range namespace {
if char == '[' {
inBracket = true
} else if char == ']' {
inBracket = false
} else if !inBracket {
result += string(char)
}
}
return result
}
func parseValidateTag(field reflect.StructField) map[string]string {
tag := field.Tag.Get("validate")
if tag == "" {
return nil
}
result := make(map[string]string)
parts := strings.Split(tag, ",")
for _, part := range parts {
if strings.Contains(part, "=") {
// 处理带参数的规则，如 min=10
pair := strings.SplitN(part, "=", 2)
if len(pair) == 2 {
result[pair[0]] = pair[1]
}
} else {
// 处理不带参数的规则，如 required
result[part] = ""
}
}
return result
}
func getValidationMessage(field reflect.StructField, tag string, tagDetails map[string]string) string {
// 优先使用自定义的 msg tag
if msg := field.Tag.Get("msg"); msg != "" {
return msg
}
// 获取字段名（优先使用 json tag）
fieldName := field.Tag.Get("json")
if fieldName == "" {
fieldName = field.Name
}
// 处理 json tag 中的选项（如 omitempty）
if strings.Contains(fieldName, ",") {
fields := strings.Split(fieldName, ",")
fieldName = fields[0]
}
// 获取规则参数
param := tagDetails[tag]
// 根据不同的验证规则返回友好的错误信息
switch tag {
case "required":
return fmt.Sprintf("%s is required", fieldName)
case "min":
if param != "" {
return fmt.Sprintf("%s must be at least %s", fieldName, param)
}
return fmt.Sprintf("%s value too small", fieldName)
case "max":
if param != "" {
return fmt.Sprintf("%s must be at most %s", fieldName, param)
}
return fmt.Sprintf("%s value too large", fieldName)
case "oneof":
if param != "" {
return fmt.Sprintf("%s must be one of: %s", fieldName, strings.ReplaceAll(param, " ", ", "))
}
return fmt.Sprintf("%s has invalid value", fieldName)
case "email":
return fmt.Sprintf("%s must be a valid email address", fieldName)
case "url":
return fmt.Sprintf("%s must be a valid URL", fieldName)
case "len":
if param != "" {
return fmt.Sprintf("%s must be exactly %s characters", fieldName, param)
}
return fmt.Sprintf("%s has invalid length", fieldName)
case "eq":
if param != "" {
return fmt.Sprintf("%s must be equal to %s", fieldName, param)
}
return fmt.Sprintf("%s has invalid value", fieldName)
case "ne":
if param != "" {
return fmt.Sprintf("%s must not be equal to %s", fieldName, param)
}
return fmt.Sprintf("%s has invalid value", fieldName)
case "gt":
if param != "" {
return fmt.Sprintf("%s must be greater than %s", fieldName, param)
}
return fmt.Sprintf("%s value too small", fieldName)
case "gte":
if param != "" {
return fmt.Sprintf("%s must be greater than or equal to %s", fieldName, param)
}
return fmt.Sprintf("%s value too small", fieldName)
case "lt":
if param != "" {
return fmt.Sprintf("%s must be less than %s", fieldName, param)
}
return fmt.Sprintf("%s value too large", fieldName)
case "lte":
if param != "" {
return fmt.Sprintf("%s must be less than or equal to %s", fieldName, param)
}
return fmt.Sprintf("%s value too large", fieldName)
default:
return fmt.Sprintf("%s validation failed for rule: %s", fieldName, tag)
}
}
func NewHttpServer(c *config.Config) *echo.Echo {
e := echo.New()
// 注册自定义 Validator
e.Validator = &CustomValidator{
Validator: validator.New(),
}
// 其他中间件配置...
e.Use(middleware.CORS())
e.Use(middleware.Logger())
return e
}
type CreateUserRequest struct {
Username string `json:"username" validate:"required,min=3,max=20"`
Email string `json:"email" validate:"required,email"`
Age int `json:"age" validate:"required,min=18,max=120"`
Role string `json:"role" validate:"required,oneof=admin user guest"`
Website string `json:"website" validate:"omitempty,url"`
}
// 使用自定义 msg tag
type CreateProductRequest struct {
Name string `json:"name" validate:"required,min=3" msg:"Product name is required and must be at least 3 characters"`
Price float64 `json:"price" validate:"required,gt=0" msg:"Price must be greater than 0"`
}
// 嵌套结构体
type Product struct {
Name string `json:"name" validate:"required,min=3"`
Description string `json:"description" validate:"required"`
ProductTags []ProductTag `json:"product_tags" validate:"required,dive"`
}
type ProductTag struct {
TagName string `json:"tag_name" validate:"required,min=2"`
TagType string `json:"tag_type" validate:"required,oneof=category brand"`
}
func CreateUser(c echo.Context) error {
req := new(CreateUserRequest)
// Bind 请求数据
if err := c.Bind(req); err != nil {
return c.JSON(http.StatusBadRequest, map[string]string{
"error": "Invalid request format",
})
}
// 自动调用自定义的 Validate 方法
if err := c.Validate(req); err != nil {
return c.JSON(http.StatusBadRequest, map[string]string{
"error": err.Error(),
})
}
// 业务逻辑...
return c.JSON(http.StatusOK, map[string]string{
"message": "User created successfully",
})
}
{
"username": "ab",
"email": "invalid-email",
"age": 15,
"role": "superuser"
}
Key: 'CreateUserRequest.Username' Error:Field validation for 'Username' failed on the 'min' tag
Key: 'CreateUserRequest.Email' Error:Field validation for 'Email' failed on the 'email' tag
Key: 'CreateUserRequest.Age' Error:Field validation for 'Age' failed on the 'min' tag
Key: 'CreateUserRequest.Role' Error:Field validation for 'Role' failed on the 'oneof' tag
{
"error": "username must be at least 3; email must be a valid email address; age must be at least 18; role must be one of: admin, user, guest"
}
func getValidationMessage(field reflect.StructField, tag string, tagDetails map[string]string, lang string) string {
fieldName := field.Tag.Get("json")
if fieldName == "" {
fieldName = field.Name
}
param := tagDetails[tag]
if lang == "zh" {
switch tag {
case "required":
return fmt.Sprintf("%s 是必填项", fieldName)
case "min":
return fmt.Sprintf("%s 最小值为 %s", fieldName, param)
case "email":
return fmt.Sprintf("%s 必须是有效的邮箱地址", fieldName)
// ... 其他规则
}
}
// 默认返回英文
// ...
}
func NewHttpServer(c *config.Config) *echo.Echo {
e := echo.New()
v := validator.New()
// 注册自定义验证规则
v.RegisterValidation("username", func(fl validator.FieldLevel) bool {
username := fl.Field().String()
// 用户名只能包含字母、数字和下划线
matched, _ := regexp.MatchString("^[a-zA-Z0-9_]+$", username)
return matched
})
e.Validator = &CustomValidator{Validator: v}
return e
}
// 在 getValidationMessage 中添加对应的错误信息
case "username":
return fmt.Sprintf("%s can only contain letters, numbers and underscores", fieldName)
func NewHttpServer(c *config.Config) *echo.Echo {
e := echo.New()
v := validator.New()
// 注册函数以使用 json tag 作为字段名
v.RegisterTagNameFunc(func(fld reflect.StructField) string {
name := strings.SplitN(fld.Tag.Get("json"), ",", 2)[0]
if name == "-" {
return ""
}
return name
})
e.Validator = &CustomValidator{Validator: v}
return e
}
type CustomValidator struct {
Validator *validator.Validate
fieldCache sync.Map // 缓存字段查找结果
}
func (cv *CustomValidator) findNestedFieldCached(rootType reflect.Type, fieldErr validator.FieldError) (reflect.StructField, bool) {
cacheKey := fmt.Sprintf("%s.%s", rootType.String(), fieldErr.Namespace())
if cached, ok := cv.fieldCache.Load(cacheKey); ok {
return cached.(reflect.StructField), true
}
field, found := cv.findNestedField(rootType, fieldErr)
if found {
cv.fieldCache.Store(cacheKey, field)
}
return field, found
}
package server
import (
"testing"
"github.com/go-playground/validator/v10"
"github.com/stretchr/testify/assert"
)
func TestCustomValidator_Validate(t *testing.T) {
cv := &CustomValidator{
Validator: validator.New(),
}
type TestStruct struct {
Name string `json:"name" validate:"required,min=3"`
Email string `json:"email" validate:"required,email"`
Age int `json:"age" validate:"required,min=18"`
}
tests := []struct {
name string
input TestStruct
wantErr bool
errMsg string
}{
{
name: "valid input",
input: TestStruct{
Name: "John Doe",
Email: "[email protected]",
Age: 25,
},
wantErr: false,
},
{
name: "missing required fields",
input: TestStruct{
Name: "",
Email: "",
Age: 0,
},
wantErr: true,
errMsg: "name is required",
},
{
name: "invalid email",
input: TestStruct{
Name: "John",
Email: "invalid-email",
Age: 25,
},
wantErr: true,
errMsg: "email must be a valid email address",
},
{
name: "age below minimum",
input: TestStruct{
Name: "John",
Email: "[email protected]",
Age: 15,
},
wantErr: true,
errMsg: "age must be at least 18",
},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
err := cv.Validate(tt.input)
if tt.wantErr {
assert.Error(t, err)
assert.Contains(t, err.Error(), tt.errMsg)
} else {
assert.NoError(t, err)
}
})
}
}