基本使用
前言
在做API开发时,需要对请求参数的校验,防止用户的恶意请求。例如日期格式,用户年龄,性别等必须是正常的值,不能随意设置。以前会使用大量的if判断参数的值是否符合规范,现在可以使用validator库来进行参数校验。我们只需要在结构体的Tag中添加 validator 标签就可以实现参数校验。同时Gin框架当前内部也集成了validator.v10这个库,在Gin框架中只要在结构体的Tag中添加 binding 标签就可以实现参数校验。使用binding标签和validator标签都是可以的,但是在Gin框架中我们一般会使用binding标签来实现参数校验。
请求模型的定义
//请求的参数必须存在并且由数字或字母组成
type UserRequest struct {
Username string `json:"username" form:"username" binding:"required,alphanum"`
Password string `json:"password" form:"password" binding:"required,alphanum"`
}
编写接口及测试
// ModifyUser 用来修改用户的密码
func ModifyUser(c *gin.Context) {
var user UserRequest
if err := c.BindQuery(&user); err != nil {
c.JSON(http.StatusOK, gin.H{
"msg": err.Error(),
})
return
}
//查询是否存在该用户
result := service.SelectUserIfExist(user.Username)
if result == 1 { //该用户存在
userInfo := service.ChangeUserSecret(user.Username, user.Password)
c.JSON(http.StatusOK, gin.H{
"msg": userInfo,
})
} else {
c.JSON(http.StatusOK, gin.H{
"msg": "用户不存在",
})
}
}
现在数据库中有一个用户。
mysql> select * from user;
+---------+----------+----------+
| user_id | username | password |
+---------+----------+----------+
| 4 | abc123 | abc123 |
+---------+----------+----------+
我们在修改密码时,将密码设置为空或者改成 xyz@456 看看参数校验能不能通过。
![image-20231011173623783](https://i-blog.csdnimg.cn/blog_migrate/cd7ab2adc91bfd4c4827abb4ebe01689.png)
![image-20231011173823585](https://i-blog.csdnimg.cn/blog_migrate/a0ce8abc3c3303ffce2bf58e35548771.png)
可以看到将密码设置为空或者改成 xyz@456 会曝出不同的错误。下面使用满足校验规则的密码进行测试:
![image-20231011174027471](https://i-blog.csdnimg.cn/blog_migrate/681214b3846fe74376c78b237440ed64.png)
可以看到密码已经被成功修改。
翻译校验错误提示信息
当参数校验错误的时候会返回错误信息,可以看到上面的错误信息都是英文,有时候看英文确实会不太舒服,所以也没有什么办法可以把错误信息翻译成中文?答案是有的,validator 库本身是支持国际化的,借助相应的语言包可以实现校验错误提示信息的自动翻译。下面的示例代码演示了如何将错误提示信息翻译成中文。可以新建一个目录utils,目录下面新建一个translate.go文件。文件内容如下:
package utils
import (
"fmt"
"github.com/gin-gonic/gin/binding"
"github.com/go-playground/locales/en"
"github.com/go-playground/locales/zh"
ut "github.com/go-playground/universal-translator"
"github.com/go-playground/validator/v10"
enTranslations "github.com/go-playground/validator/v10/translations/en"
zhTranslations "github.com/go-playground/validator/v10/translations/zh"
)
// Trans 一个全局翻译器
var Trans ut.Translator
func Translate(locale string) (err error) {
// 修改gin框架中的Validator引擎属性,实现自定制
if value, ok := binding.Validator.Engine().(*validator.Validate); ok {
zhT := zh.New() // 中文翻译器
enT := en.New() // 英文翻译器
// 第一个参数是备用(fallback)的语言环境
// 后面的参数是支持的语言环境(支持多个)
uni := ut.New(enT, zhT, enT)
// locale 通常取决于 http 请求头的 'Accept-Language'
var ok bool
// 也可以使用 uni.FindTranslator(...) 传入多个locale进行查找
Trans, ok = uni.GetTranslator(locale)
if !ok {
return fmt.Errorf("uni.GetTranslator(%s) failed", locale)
}
// 注册翻译器
switch locale {
case "en":
err = enTranslations.RegisterDefaultTranslations(value, Trans)
case "zh":
err = zhTranslations.RegisterDefaultTranslations(value, Trans)
default:
err = enTranslations.RegisterDefaultTranslations(value, Trans)
}
return
}
return
}
然后需要在main函数中初始化 Translate 这个函数。
func main() {
if err := utils.Translate("zh"); err != nil {
fmt.Printf("init trans failed, err:%v\n", err)
return
}
}
接下来就能使用这个翻译器翻译英文信息。
// ModifyUser 用来修改用户的密码
func ModifyUser(c *gin.Context) {
var user UserRequest
if err := c.ShouldBindQuery(&user); err != nil {
// 获取validator.ValidationErrors类型的errors
errs, ok := err.(validator.ValidationErrors)
if !ok {
// 非validator.ValidationErrors类型错误直接返回
c.JSON(http.StatusOK, gin.H{
"msg": err.Error(),
})
return
}
// validator.ValidationErrors类型错误则进行翻译
c.JSON(http.StatusOK, gin.H{
"msg": errs.Translate(utils.Trans),
})
return
}
//查询是否存在该用户
result := service.SelectUserIfExist(user.Username)
if result == 1 { //该用户存在
userInfo := service.ChangeUserSecret(user.Username, user.Password)
c.JSON(http.StatusOK, gin.H{
"msg": userInfo,
})
} else {
c.JSON(http.StatusOK, gin.H{
"msg": "用户不存在",
})
}
}
测试结果如下:
![image-20231011192954175](https://i-blog.csdnimg.cn/blog_migrate/c7a47f74fad9c85bfdf50b7dba437f2e.png)
![image-20231011192918100](https://i-blog.csdnimg.cn/blog_migrate/bae919f27ae22ad00af2bd798ae7287b.png)
自定义错误提示信息的字段名
上面的错误提示看起来是可以了,但是还是差点意思,首先是错误提示中的字段并不是请求中使用的字段,例如:Password 是我们后端定义的结构体中的字段名,而请求中使用的是小写的 password 字段。如何让错误提示中的字段使用自定义的名称,例如json tag指定的值呢?
其实只需要在初始化翻译器的时候像下面一样添加一个获取json tag的自定义方法即可。
func Translate(locale string) (err error) {
// 修改gin框架中的Validator引擎属性,实现自定制
if value, ok := binding.Validator.Engine().(*validator.Validate); ok {
// 注册一个获取json tag的自定义方法
value.RegisterTagNameFunc(func(fld reflect.StructField) string {
name := strings.SplitN(fld.Tag.Get("json"), ",", 2)[0]
if name == "-" {
return ""
}
return name
})
zhT := zh.New() // 中文翻译器
enT := en.New() // 英文翻译器
// 第一个参数是备用(fallback)的语言环境
// 后面的参数是支持的语言环境(支持多个)
uni := ut.New(enT, zhT, enT)
······
}
return
}
现在错误信息中的password就变成了小写了。测试结果如下:
![image-20231011194814448](https://i-blog.csdnimg.cn/blog_migrate/a4db7fe81414710a9774ca0b502d510d.png)
但是还是有点瑕疵,那就是最终的错误提示信息中心还是有我们后端定义的结构体名称(UserRequest),这个名称其实是不需要随错误提示返回给前端的,前端并不需要这个值。我们需要想办法把它去掉。其实可以定义一个去掉结构体名称前缀的自定义方法:
func removeTopStruct(fields map[string]string) map[string]string {
res := map[string]string{}
for field, err := range fields {
res[field[strings.Index(field, ".")+1:]] = err
}
return res
}
我们在代码中使用上述函数将翻译后的 errors 做一下处理即可:
if err := c.ShouldBindQuery(&user); err != nil {
// 获取validator.ValidationErrors类型的errors
errs, ok := err.(validator.ValidationErrors)
if !ok {
// 非validator.ValidationErrors类型错误直接返回
c.JSON(http.StatusOK, gin.H{
"msg": err.Error(),
})
return
}
// validator.ValidationErrors类型错误则进行翻译
// 并使用removeTopStruct函数去除字段名中的结构体名称标识
c.JSON(http.StatusOK, gin.H{
"msg": removeTopStruct(errs.Translate(utils.Trans)),
})
return
}
测试结果如下:
![image-20231011195855386](https://i-blog.csdnimg.cn/blog_migrate/43359408b92263ad89b38eee0c931abc.png)
自定义校验规则
先在又有一个需求,那就是要求密码必须是由数字、字母或下划线组成,且第一个字符不能是下划线,那么这个需求又该如何实现呢?
func CustomFunc(fl validator.FieldLevel) bool {
// 正则表达式来匹配字母、数字和下划线,且第一个字符不能是下划线
re := regexp.MustCompile(`^[a-zA-Z0-9][a-zA-Z0-9_]*$`)
return re.MatchString(fl.Field().String())
}
// tag参数就是我们自己自定义的校验规则的名字
func Custom(tag string) (err error) {
if value, ok := binding.Validator.Engine().(*validator.Validate); ok {
// 在校验器注册自定义的校验方法
if err := value.RegisterValidation(tag, CustomFunc); err != nil {
return err
}
}
return err
}
接下来只需要在main函数或者一些初始化函数当中注册这个Custom函数就可以了。需要注意的是,要添加上binding的字段校验规则,比如:
// Password的校验规则就是我们自定义的校验规则:password
type UserRequest struct {
Username string `json:"username" form:"username" binding:"required,alphanum"`
Password string `json:"password" form:"password" binding:"required,password"`
}
测试结果如下:
![image-20231011204702960](https://i-blog.csdnimg.cn/blog_migrate/4b85fd432821ecda6f0c26a6290822bf.png)
![image-20231011204618021](https://i-blog.csdnimg.cn/blog_migrate/78aef2c6d3fea50ef6dd6bfbb5b1d975.png)
可以看到 abc_123 满足校验规则,而 _abc123 不满足校验规则。
常见的参数校验字段
下面是一些常见的校验规则:
Tag | 描述 |
---|---|
eqfield | 一个字段等于另一个字段 |
alpha | 仅限字母 |
alphanum | 仅限字母数字 |
excludes | 排除 |
json | JSON |
jwt | JSON Web Token (JWT) |
E-mail 字符串 | |
html_encoded | HTML编码 |
eq | 等于 |
gt | 大于 |
gte | 大于或等于 |
lt | 小于 |
lte | 小于或等于 |
ne | 不等于 |
len | 长度 |
max | 最大 |
min | 最小 |
required | 必需的 |
unique | 唯一 |