学会gin的参数校验之validator库，看这一篇就够用了

前言

哈喽，大家好，我是asong。这是我的第十篇原创文章。这周在公司做项目，在做API部分开发时，需要对请求参数的校验，防止用户的恶意请求。例如日期格式，用户年龄，性别等必须是正常的值，不能随意设置。最开始在做这一部分的时候，我采用老方法，自己编写参数检验方法，统一进行参数验证。后来在同事CR的时候，说GIN有更好的参数检验方法，gin框架使用github.com/go-playground/validator进行参数校验，我们只需要在定义结构体时使用binding或validatetag标识相关校验规则，就可以进行参数校验了，很方便。相信也有很多小伙伴不知道这个功能，今天就来介绍一下这部分。

自己翻译了一份gin官方中文文档。关注公众号[Golang梦工厂]（扫描下方二维码），后台回复：gin，即可获取。

快速安装

使用之前，我们先要获取validator这个库。

# 第一次安装使用如下命令
$ go get github.com/go-playground/validator/v10
# 项目中引入包
import "github.com/go-playground/validator/v10"

简单示例

安装还是很简单的，下面我先来一个官方样例，看看是怎么使用的，然后展开分析。

package main

import (
    "fmt"
    "net/http"

    "github.com/gin-gonic/gin"
)

type RegisterRequest struct {
    Username string `json:"username" binding:"required"`
    Nickname string `json:"nickname" binding:"required"`
    Email    string `json:"email" binding:"required,email"`
    Password string `json:"password" binding:"required"`
    Age      uint8  `json:"age" binding:"gte=1,lte=120"`
}

func main() {

    router := gin.Default()

    router.POST("register", Register)

    router.Run(":9999")
}

func Register(c *gin.Context) {
    var r RegisterRequest
    err := c.ShouldBindJSON(&r)
    if err != nil {
        fmt.Println("register failed")
        c.JSON(http.StatusOK, gin.H{"msg": err.Error()})
        return
    }
    //验证 存储操作省略.....
    fmt.Println("register success")
    c.JSON(http.StatusOK, "successful")
}
  • 测试
curl --location --request POST 'http://localhost:9999/register' \
--header 'Content-Type: application/json' \
--data-raw '{
    "username": "asong",
    "nickname": "golang梦工厂",
    "email": "7418.com",
    "password": "123",
    "age": 140
}'
  • 返回结果
{
    "msg": "Key: 'RegisterRequest.Email' Error:Field validation for 'Email' failed on the 'email' tag\nKey: 'RegisterRequest.Age' Error:Field validation for 'Age' failed on the 'lte' tag"
}

看这个输出结果，我们可以看到validator的检验生效了，email字段不是一个合法邮箱，age字段超过了最大限制。我们只在结构体中添加tag就解决了这个问题，是不是很方便，下面我们就来学习一下具体使用。

validator库

gin框架是使用validator.v10这个库来进行参数验证的，所以我们先来看看这个库的使用。

先安装这个库：

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

然后先写一个简单的示例：

package main

import (
    "fmt"

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

type User struct {
    Username string `validate:"min=6,max=10"`
    Age      uint8  `validate:"gte=1,lte=10"`
    Sex      string `validate:"oneof=female male"`
}

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

    user1 := User{Username: "asong", Age: 11, Sex: "null"}
    err := validate.Struct(user1)
    if err != nil {
        fmt.Println(err)
    }

    user2 := User{Username: "asong111", Age: 8, Sex: "male"}
    err = validate.Struct(user2)
    if err != nil {
        fmt.Println(err)
    }

}

我们在结构体定义validator标签的tag，使用validator.New()创建一个验证器，这个验证器可以指定选项、添加自定义约束，然后在调用他的Struct()方法来验证各种结构对象的字段是否符合定义的约束。

上面的例子，我们在User结构体中，有三个字段：

  • Name：通过min和max来进行约束，Name的字符串长度为[6,10]之间。
  • Age：通过gte和lte对年轻的范围进行约束，age的大小大于1，小于10。
  • Sex：通过oneof对值进行约束，只能是所列举的值，oneof列举出性别为男士🚹和女士🚺(不是硬性规定奥，可能还有别的性别)。

所以user1会进行报错，错误信息如下：

Key: 'User.Name' Error:Field validation for 'Name' failed on the 'min' tag
Key: 'User.Age' Error:Field validation for 'Age' failed on the 'lte' tag
Key: 'User.Sex' Error:Field validation for 'Sex' failed on the 'oneof' tag

各个字段违反了什么约束，一眼我们便能从错误信息中看出来。看完了简单示例，下面我就来看一看都有哪些tag，我们都可以怎么使用。本文不介绍所有的tag，更多使用方法，请到官方文档自行学习。

字符串约束

  • excludesall：不包含参数中任意的 UNICODE 字符，例如excludesall=ab；

  • excludesrune：不包含参数表示的 rune 字符，excludesrune=asong；

  • startswith：以参数子串为前缀，例如startswith=hi；

  • endswith：以参数子串为后缀，例如endswith=bye。

  • contains=：包含参数子串，例如contains=email；

  • containsany：包含参数中任意的 UNICODE 字符，例如containsany=ab；

  • containsrune：包含参数表示的 rune 字符，例如`containsrune=asong；

  • excludes：不包含参数子串，例如excludes=email；

范围约束

范围约束的字段类型分为三种：

  • 对于数值，我们则可以约束其值
  • 对于切片、数组和map，我们则可以约束其长度
  • 对于字符串，我们则可以约束其长度

常用tag介绍：

  • ne：不等于参数值，例如ne=5；
  • gt：大于参数值，例如gt=5；
  • gte：大于等于参数值，例如gte=50；
  • lt：小于参数值，例如lt=50；
  • lte：小于等于参数值，例如lte=50；
  • oneof：只能是列举出的值其中一个，这些值必须是数值或字符串，以空格分隔，如果字符串中有空格，将字符串用单引号包围，例如oneof=male female。
  • eq：等于参数值，注意与len不同。对于字符串，eq约束字符串本身的值，而len约束字符串长度。例如eq=10；
  • len：等于参数值，例如len=10；
  • max：小于等于参数值，例如max=10；
  • min：大于等于参数值，例如min=10

Fields约束

  • eqfield：定义字段间的相等约束，用于约束同一结构体中的字段。例如：eqfield=Password
  • eqcsfield：约束统一结构体中字段等于另一个字段（相对），确认密码时可以使用，例如：eqfiel=ConfirmPassword
  • nefield：用来约束两个字段是否相同，确认两种颜色是否一致时可以使用，例如：nefield=Color1
  • necsfield：约束两个字段是否相同（相对）

常用约束

  • unique：指定唯一性约束，不同类型处理不同：

    • 对于map，unique约束没有重复的值
    • 对于数组和切片，unique没有重复的值
    • 对于元素类型为结构体的碎片，unique约束结构体对象的某个字段不重复，使用unique=field指定字段名

  • email：使用email来限制字段必须是邮件形式，直接写eamil即可，无需加任何指定。

  • omitempty：字段未设置，则忽略

  • -：跳过该字段，不检验；

  • |：使用多个约束，只需要满足其中一个，例如rgb|rgba；

  • required：字段必须设置，不能为默认值；

好啦，就介绍这些常用的约束，更多约束学习请到文档自行学习吧，都有example供你学习，很快的。

gin中的参数校验

学习了validator，我们也就知道了怎么在gin中使用参数校验了。这些约束是都没有变的，在validator中，我们直接结构体中将约束放到validate tag中，同样道理，在gin中我们只需将约束放到bindingtag中就可以了。是不是很简单。

但是有些时候，并不是所有的参数校验都能满足我们的需求，所以我们可以定义自己的约束。自定义约束支持自定义结构体校验、自定义字段校验等。这里来介绍一下自定义结构体校验。

自定义结构体校验

当涉及到一些复杂的校验规则，这些已有的校验规则就不能满足我们的需求了。例如现在有一个需求，存在db的用户信息中创建时间与更新时间都要大于某一时间，假设是从前端传来的（当然不可能，哈哈）。现在我们来写一个简单示例，学习一下怎么对这个参数进行校验。

package main

import (
    "fmt"
    "net/http"
    "time"

    "github.com/gin-gonic/gin"
    "github.com/gin-gonic/gin/binding"
    "github.com/go-playground/validator/v10"
)

type Info struct {
    CreateTime time.Time `form:"create_time" binding:"required,timing" time_format:"2006-01-02"`
    UpdateTime time.Time `form:"update_time" binding:"required,timing" time_format:"2006-01-02"`
}

// 自定义验证规则断言
func timing(fl validator.FieldLevel) bool {
    if date, ok := fl.Field().Interface().(time.Time); ok {
        today := time.Now()
        if today.After(date) {
            return false
        }
    }
    return true
}

func main() {
    route := gin.Default()
    // 注册验证
    if v, ok := binding.Validator.Engine().(*validator.Validate); ok {
        err := v.RegisterValidation("timing", timing)
        if err != nil {
            fmt.Println("success")
        }
    }

    route.GET("/time", getTime)
    route.Run(":8080")
}

func getTime(c *gin.Context) {
    var b Info
    // 数据模型绑定查询字符串验证
    if err := c.ShouldBindWith(&b, binding.Query); err == nil {
        c.JSON(http.StatusOK, gin.H{"message": "time are valid!"})
    } else {
        c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
    }
}

写好了，下面我就来测试验证一下：

$ curl "localhost:8080/time?create_time=2020-10-11&update_time=2020-10-11"
# 结果
{"message":"time are valid!"}%
$ curl "localhost:8080/time?create_time=1997-10-11&update_time=1997-10-11"
# 结果
{"error":"Key: 'Info.CreateTime' Error:Field validation for 'CreateTime' failed on the 'timing' tag\nKey: 'Info.UpdateTime' Error:Field validation for 'UpdateTime' failed on the 'timing' tag"}%

这里我们看到虽然参数验证成功了，但是这里返回的错误显示的也太全了，在项目开发中不可以给前端返回这么详细的信息的，所以我们需要改造一下：

func getTime(c *gin.Context) {
    var b Info
    // 数据模型绑定查询字符串验证
    if err := c.ShouldBindWith(&b, binding.Query); err == nil {
        c.JSON(http.StatusOK, gin.H{"message": "time are valid!"})
    } else {
        _, ok := err.(validator.ValidationErrors)
        if !ok {
            c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
            return
        }
        c.JSON(http.StatusOK, gin.H{"code": 1000, "msg": "param is error"})
    }
}

这里在出现错误时返回固定错误即可。这里你也可以使用一个方法封装一下，对错误进行处理在进行返回，更多使用方法等你发觉哟。

小彩蛋

我们返回错误时都是英文的，当错误很长的时候，对于我这种英语渣渣，就要借助翻译软件了。所以要是能返回的错误直接是中文的就好了。validator库本身是支持国际化的，借助相应的语言包可以实现校验错误提示信息的自动翻译。下面就写一个代码演示一下啦。

package main

import (
    "fmt"
    "log"
    "net/http"

    "github.com/gin-gonic/gin"
    "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"
    chTranslations "github.com/go-playground/validator/v10/translations/zh"
)

var trans ut.Translator

// loca 通常取决于 http 请求头的 'Accept-Language'
func transInit(local string) (err error) {
    if v, ok := binding.Validator.Engine().(*validator.Validate); ok {
        zhT := zh.New() //chinese
        enT := en.New() //english
        uni := ut.New(enT, zhT, enT)

        var o bool
        trans, o = uni.GetTranslator(local)
        if !o {
            return fmt.Errorf("uni.GetTranslator(%s) failed", local)
        }
        //register translate
        // 注册翻译器
        switch local {
        case "en":
            err = enTranslations.RegisterDefaultTranslations(v, trans)
        case "zh":
            err = chTranslations.RegisterDefaultTranslations(v, trans)
        default:
            err = enTranslations.RegisterDefaultTranslations(v, trans)
        }
        return
    }
    return
}

type loginRequest struct {
    Username string `json:"username" binding:"required"`
    Password string `json:"password" binding:"required,max=16,min=6"`
}

func main() {
    if err := transInit("zh"); err != nil {
        fmt.Printf("init trans failed, err:%v\n", err)
        return
    }
    router := gin.Default()

    router.POST("/user/login", login)

    err := router.Run(":8888")
    if err != nil {
        log.Println("failed")
    }
}

func login(c *gin.Context) {
    var req loginRequest
    if err := c.ShouldBindJSON(&req); 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(trans),
        })
        return
    }
    //login 操作省略
    c.JSON(http.StatusOK, gin.H{
        "code": 0,
        "msg":  "success",
    })
}

我这里请求参数中限制密码的长度，来验证一下吧。

curl --location --request POST 'http://localhost:8888/user/login' \
--header 'Content-Type: application/json' \
--data-raw '{
    "username": "asong",
    "password": "11122222222222222222"
}'
# 返回
{
    "msg": {
        "loginRequest.Password": "Password长度不能超过16个字符"
    }
}

看，直接显示中文了，是不是很棒，我们可以在测试的时候使用这个，上线项目不建议使用呦！！！

总结

好啦，这一篇文章到这里结束啦。这一篇干货还是满满的。学会这些知识点，提高我们的开发效率，省去了一些没必要写的代码。能用的轮子我们还是不要错过滴。

我是asong，一名普普通通的程序猿，让我一起慢慢变强吧。欢迎各位的关注，我们下期见~~~

公众号图片

推荐往期文章：

最后编辑于 ：
©著作权归作者所有,转载或内容合作请联系作者
  • 人面猴
    序言：七十年代末，一起剥皮案震惊了整个滨河市，随后出现的几起案子，更是在滨河造成了极大的恐慌，老刑警刘岩，带你破解...
    沈念sama阅读 202,529评论 5赞 475
  • 死咒
    序言：滨河连续发生了三起死亡事件，死亡现场离奇诡异，居然都是意外死亡，警方通过查阅死者的电脑和手机，发现死者居然都...
    沈念sama阅读 85,015评论 2赞 379
  • 救了他两次的神仙让他今天三更去死
    文/潘晓璐 我一进店门，熙熙楼的掌柜王于贵愁眉苦脸地迎上来，“玉大人，你说我怎么就摊上这事。” “怎么了？”我有些...
    开封第一讲书人阅读 149,409评论 0赞 335
  • 道士缉凶录：失踪的卖姜人
    文/不坏的土叔 我叫张陵，是天一观的道长。 经常有香客问我，道长，这世上最难降的妖魔是什么？ 我笑而不...
    开封第一讲书人阅读 54,385评论 1赞 273
  • 港岛之恋（遗憾婚礼）
    正文 为了忘掉前任，我火速办了婚礼，结果婚礼上，老公的妹妹穿的比我还像新娘。我一直安慰自己，他们只是感情好，可当我...
    茶点故事阅读 63,387评论 5赞 364
  • 恶毒庶女顶嫁案：这布局不是一般人想出来的
    文/花漫 我一把揭开白布。 她就那样静静地躺着，像睡着了一般。 火红的嫁衣衬着肌肤如雪。 梳的纹丝不乱的头发上，一...
    开封第一讲书人阅读 48,466评论 1赞 281
  • 城市分裂传说
    那天，我揣着相机与录音，去河边找鬼。 笑死，一个胖子当着我的面吹牛，可吹牛的内容都是我干的。 我是一名探鬼主播，决...
    沈念sama阅读 37,880评论 3赞 395
  • 双鸳鸯连环套：你想象不到人心有多黑
    文/苍兰香墨 我猛地睁开眼，长吁一口气：“原来是场噩梦啊……” “哼！你这毒妇竟也来了？” 一声冷哼从身侧响起，我...
    开封第一讲书人阅读 36,528评论 0赞 256
  • 万荣杀人案实录
    序言：老挝万荣一对情侣失踪，失踪者是张志新（化名）和其女友刘颖，没想到半个月后，有当地人在树林里发现了一具尸体，经...
    沈念sama阅读 40,727评论 1赞 295
  • 护林员之死
    正文 独居荒郊野岭守林人离奇死亡，尸身上长有42处带血的脓包…… 初始之章·张勋 以下内容为张勋视角 年9月15日...
    茶点故事阅读 35,528评论 2赞 319
  • 白月光启示录
    正文 我和宋清朗相恋三年，在试婚纱的时候发现自己被绿了。 大学时的朋友给我发了我未婚夫和他白月光在一起吃饭的照片。...
    茶点故事阅读 37,602评论 1赞 329
  • 活死人
    序言：一个原本活蹦乱跳的男人离奇死亡，死状恐怖，灵堂内的尸体忽然破棺而出，到底是诈尸还是另有隐情，我是刑警宁泽，带...
    沈念sama阅读 33,302评论 4赞 318
  • 日本核电站爆炸内幕
    正文 年R本政府宣布，位于F岛的核电站，受9级特大地震影响，放射性物质发生泄漏。R本人自食恶果不足惜，却给世界环境...
    茶点故事阅读 38,873评论 3赞 306
  • 男人毒药：我在死后第九天来索命
    文/蒙蒙 一、第九天 我趴在偏房一处隐蔽的房顶上张望。 院中可真热闹，春花似锦、人声如沸。这庄子的主人今日做“春日...
    开封第一讲书人阅读 29,890评论 0赞 19
  • 一桩弑父案，背后竟有这般阴谋
    文/苍兰香墨 我抬头看了看天上的太阳。三九已至，却和暖如春，着一层夹袄步出监牢的瞬间，已是汗流浃背。 一阵脚步声响...
    开封第一讲书人阅读 31,132评论 1赞 259
  • 情欲美人皮
    我被黑心中介骗来泰国打工， 没想到刚下飞机就差点儿被人妖公主榨干…… 1. 我叫王不留，地道东北人。 一个月前我还...
    沈念sama阅读 42,777评论 2赞 349
  • 代替公主和亲
    正文 我出身青楼，却偏偏与公主长得像，于是被迫代替她去往敌国和亲。 传闻我的和亲对象是个残疾皇子，可洞房花烛夜当晚...
    茶点故事阅读 42,310评论 2赞 342