gin框架(4)- binding和validate

前言

  在 Engine与Context 中,我们提到了Context的作用之一就是解析request请求并实现request在上下游的传递,其中的解析request调用的是binding相关的函数,解析完数据,还需要对数据进行有效性验证,这部分是通过validator相关的函数实现的。本章重点讲解bindign和validator。

1. binding的原理

针对不同的请求,gin提供了很多函数,用于解析对应的参数,常用的函数如下:

Param(key string) string  // 用于获取url参数,比如/welcome/:user_id中的user_id

// 获取GET请求中携带的参数
GetQueryArray(key string) ([]string, bool)  
GetQuery(key string)(string, bool)
Query(key string) string
DefaultQuery(key, defaultValue string) string

// 获取POST请求参数
GetPostFormArray(key string) ([]string, bool)
PostFormArray(key string) []string 
GetPostForm(key string) (string, bool)
PostForm(key string) string
DefaultPostForm(key, defaultValue string) string

// data binding 
Bind (obj interface {}) error // bind data according to Content-Type
BindJSON(obj interface{}) error
BindQuery(obj interface{}) error

ShouldBind(obj interface{}) error
ShouldBindJSON(obj interface{}) error
ShouldBindQuery(obj interface{}) error
... 
其中Bind相关的函数是一种比较通用的方法,它允许我们将请求参数填充到一个map或struct中,这样在后续请求处理时,能够方便的使用传入的参数。Bind相关的函数分为三大类:
// 1. Bind函数
Bind (obj interface {}) error // 根据请求中content-type的类型来选择对应的具体Bind函数,底层调用的是BindJson, BindQuery这种具体的Bind函数

// 2. BindXXX(),具体的Bind函数,用于绑定一种参数类型,底层调用MustBindWith或者ShouldBindWith
BindJSON(obj interface{}) error
BindQuery(obj interface{}) error

// 3. 最底层的基础函数
MustBindWith(obj any, b binding.Binding) error // 当出现参数校验问题时,会直接返回400,底层仍然是ShouldBindWith
ShouldBindWith(obj any, b binding.Binding) error
其中各种类型的Bind函数,最底层的调用都是ShouldBindWith()函数,该函数有两个参数,第一个参数obj为需要将参数填充进去的对象(本文称为填充对象);第二个参数为binding.Binding类型,该类型的定义在package binding中,如下:
type Binding interface {
    Name() string
    Bind(*http.Request, any) error
}
Bingding为一个接口,提供了Name()和Bind()两个函数,Name()负责返回对应的Bind类型,比如JSON,XML等,Bind()函数则负责实现具体类型的参数绑定。为了完成常用参数类型的绑定,gin给每种参数类型都定义了一个类,并实现Binding接口,具体实现了Binding接口的类如下:
// 实现Binding接口的具体类
var (
    JSON          = jsonBinding{}
    XML           = xmlBinding{}
    Form          = formBinding{}
    Query         = queryBinding{}
    FormPost      = formPostBinding{}
    FormMultipart = formMultipartBinding{}
    ProtoBuf      = protobufBinding{}
    MsgPack       = msgpackBinding{}
    YAML          = yamlBinding{}
    Uri           = uriBinding{}
    Header        = headerBinding{}
    TOML          = tomlBinding{}
)
这样,每当一个HTTP请求到来的时候,用户可以直接调用Bind()函数,Bind()函数可以通过content-type选择对应的实现了Bind()方法的对应类的实例,调用其Bind()方法,完成参数绑定。
  常用的HTTP请求参数类型为HTTP GET query参数类型和HTTP POST json参数类型。我们以这两个为例,看一下参数绑定的一些细节。

1.1 BindJSON

jsonBinding对Binding的实现如下:

func (jsonBinding) Name() string {
    return "json"
}

func (jsonBinding) Bind(req *http.Request, obj any) error {
    if req == nil || req.Body == nil {
        return errors.New("invalid request")
    }
    return decodeJSON(req.Body, obj)
}

func decodeJSON(r io.Reader, obj any) error {
    decoder := json.NewDecoder(r) // 使用json.Decoder对json进行解析
    if EnableDecoderUseNumber {
        decoder.UseNumber()
    }
    if EnableDecoderDisallowUnknownFields {
        decoder.DisallowUnknownFields()
    }
    if err := decoder.Decode(obj); err != nil {
        return err
    }
    return validate(obj) // 参数校验
}
json的参数绑定比较简单,使用json.Decoder完成。

1.2 BindQuery

  一个HTTP GET请求的query参数,在go中,可以通过request.URL.Query()获取到,获取到的query参数类型为url.Values。因此,BindQuery()首先获取到url.Values类型的query参数,然后设置对应的值。BindQuery()根据传进来的要将参数填充进去的对象类型(本文称为填充对象,是map类型还是struct ptr),分成了两个填充函数:

/* mapFormByTag是queryBinding.Bind()的底层核心函数
* ptr: 填充对象,可能是map或strcut的指针
* form: url.Values,包含所有query参数
* tag: 值为"form"
*/
func mapFormByTag(ptr any, form map[string][]string, tag string) error {
    // Check if ptr is a map
    ptrVal := reflect.ValueOf(ptr)
    var pointed any
    if ptrVal.Kind() == reflect.Ptr {
        ptrVal = ptrVal.Elem()
        pointed = ptrVal.Interface()
    }
    if ptrVal.Kind() == reflect.Map &&
        ptrVal.Type().Key().Kind() == reflect.String {
        if pointed != nil {
            ptr = pointed
        }
        return setFormMap(ptr, form) // 如果填充对象是map类型
    }

    return mappingByPtr(ptr, formSource(form), tag) // 填充对象是ptr struct类型
}
接下来分别看一下两个核心的填充函数setFormMap()和mappingByPtr()
// setFormMap本身比较简单,因为query参数(url.Values是map[string][]string类型的别称)本身就是map[string][]string类型,只需要判断填充对象是map[string]string还是map[string][]string类型
func setFormMap(ptr any, form map[string][]string) error {
    el := reflect.TypeOf(ptr).Elem() // 因为ptr本身是map类型,Elem返回该map的value值
    // 如果map填充对象的value值为[]string类型,直接填充
    if el.Kind() == reflect.Slice {
        ptrMap, ok := ptr.(map[string][]string)
        if !ok {
            return ErrConvertMapStringSlice
        }
        for k, v := range form {
            ptrMap[k] = v
        }

        return nil
    }
    // 否则,map填充对象为map[string]string类型,取url.Values每个key对应的value值(类型为[]string)的最后一个元素填充到填充对象中
    ptrMap, ok := ptr.(map[string]string)
    if !ok {
        return ErrConvertToMapString
    }
    for k, v := range form {
        ptrMap[k] = v[len(v)-1] // pick last
    }

    return nil
}
mappingByPtr()的逻辑比较复杂,核心是遍历struct的每一个字段,获取该struct字段的json tag,如果tag的值跟某一个url.Values的key的值相等,填充对应的值。
func mappingByPtr(ptr any, setter setter, tag string) error {
    _, err := mapping(reflect.ValueOf(ptr), emptyField, setter, tag)
    return err
}

/* mapping是一个递归函数,因为struct填充对象有可能嵌套了ptr成员
* value:填充对象
* field:struct填充对象的某个具体成员变量
* setter:内部包含了url.Values
* tag: 等于"form"
*/
func mapping(value reflect.Value, field reflect.StructField, setter setter, tag string) (bool, error) {
    if field.Tag.Get(tag) == "-" { // just ignoring this field
        return false, nil
    }

    vKind := value.Kind()

    // 如果填充对象是ptr,获取其指向的对象递归调用mapping
    if vKind == reflect.Ptr {
        var isNew bool
        vPtr := value
        if value.IsNil() {
            isNew = true
            vPtr = reflect.New(value.Type().Elem())
        }
        isSet, err := mapping(vPtr.Elem(), field, setter, tag) 
        if err != nil {
            return false, err
        }
        if isNew && isSet {
            value.Set(vPtr)
        }
        return isSet, nil
    }
    // 递归到最底层,每个value都是StructField类型,开始填充值
    if vKind != reflect.Struct || !field.Anonymous {
        ok, err := tryToSetValue(value, field, setter, tag)
        if err != nil {
            return false, err
        }
        if ok {
            return true, nil
        }
    }
    // 如果填充对象是struct,针对每一个struct field,递归调用mapping
    if vKind == reflect.Struct {
        tValue := value.Type()

        var isSet bool
        for i := 0; i < value.NumField(); i++ {
            sf := tValue.Field(i)
            if sf.PkgPath != "" && !sf.Anonymous { // unexported
                continue
            }
            ok, err := mapping(value.Field(i), sf, setter, tag)
            if err != nil {
                return false, err
            }
            isSet = isSet || ok
        }
        return isSet, nil
    }
    return false, nil
}

1.3 Binding总结

gin通过区分不同的参数类型,每种参数类型实现了统一的Bind()函数来完成对应的参数绑定,用户只需要调用统一的函数,不用关系底层实现细节,即可完成参数绑定。除了基本的Bind()函数外,某些参数类型还提供了一些常用的快捷方法供用户使用。

2. 常见HTTP参数的获取

在第一节中,我们详细分析了gin通用的用于参数绑定的Bind()方法,这部分只需了解实现过程和原理即可。接下来介绍一些常用的参数类型的获取方法。

路径参数和查询参数

获取路径参数

// 获取路径参数的方法为c.Param,返回结果均为string
router.GET("/user/:name", func(c *gin.Context) {
    name := c.Param("name")
    c.String(http.StatusOK, "Hello %s", name)
})

router.GET("/user/:name/*action", func(c *gin.Context) {
    name := c.Param("name")
    action := c.Param("action")
    message := name + " is " + actionc.String(http.StatusOK, message)
})
获取查询参数
// 获取query参数的方法为c.Query(), c.DefaultQuery(), 返回结果均为string
 // url: /welcome?firstname=Jane&lastname=Doe
 router.GET("/welcome", func(c *gin.Context) {
    firstname := c.DefaultQuery("firstname", "Guest")
    lastname := c.Query("lastname") // shortcut for c.Request.URL.Query().Get("lastname")c.String(http.StatusOK, "Hello %s %s", firstname, lastname)
 })

post form参数

// Reuqest的内容
POST /post?id=1234&page=1 HTTP/1.1
Content-Type: application/x-www-form-urlencoded
name=manu&message=this_is_great

// c.PostForm()返回类型为string
router.POST("/post", func(c *gin.Context) {

        id := c.Query("id")
        page := c.DefaultQuery("page", "0")
        name := c.PostForm("name")
        message := c.PostForm("message")

        fmt.Printf("id: %s; page: %s; name: %s; message: %s", id, page, name, message)})
router.Run(":8080")

query map和form map参数

POST /post?ids[a]=1234&ids[b]=hello HTTP/1.1
Content-Type: application/x-www-form-urlencoded
names[first]=thinkerou&names[second]=tianou

func main() {
    router := gin.Default()
    router.POST("/post", func(c *gin.Context) {

            ids := c.QueryMap("ids")
            names := c.PostFormMap("names")

            fmt.Printf("ids: %v; names: %v", ids, names)})
    router.Run(":8080")
}

3. validator

  对request参数进行校验,是处理http请求的第一步。通常情况下,我们在获取到参数后,会在业务处理逻辑开始前,对需要校验的参数进行人工校验,比如年龄参数大于0且为整数,start_time和end_time必须满足标准的时间格式“2006-01-02 15:04:05”且start_time小于end_time。gin支持在参数绑定的时候,通过struct类型填充对象的tag,配置常用的参数校验标签,来达到参数校验的目的。这样做的好处有两个:

  • 参数校验本来不属于业务逻辑,因此将校验代码和业务逻辑处理代码分开,可以使项目结构更清晰;
  • 通过提取通用的校验逻辑,比如是不是必填参数,达到代码复用的目的。
gin的参数校验使用的是开源的包 validator,校验原理不是本文的重点。主要需要了解有哪些可以直接使用的校验tag,常用的校验tag参考 go validator常用校验tag。如果现有的校验tag不能满足需求的话,可以编写自己的校验函数。下面以start_time和end_time校验为例,要求start_time和end_time为标准的string类型时间格式“%Y-%m-% %H:%M:%S”,且start_time必须小于end_time(该校验为典型的跨字段校验)。
整体的流程如下:
func main() {
    r := gin.Default()
    if v, ok := binding.Validator.Engine().(*validator.Validate); ok {
        v.RegisterValidation($tag_name, $tag_func) // 注册校验函数
    }
}
RegisterValidation()函数有两个参数,第一个为string类型的校验tag的名称,第二个参数为校验函数,该函数的签名如下:
/*
校验函数的格式, fl代表添加了添加此tag的字段
fl.Field()  // 返回该字段的值,类型为reflect.Value 
fl.Top() // 返回该字段的top level struct,类型为reflect.Value,有了top level struct,获取该struct其他字段就非常方便了
fl.Parent() // 返回该字段的parent struct 
fl.FieldName() // 返回该字段的名称
*/
func(fl validator.FieldLevel) bool  
对start_time和end_time做校验的校验函数如下:
// 此函数用在end_time字段上
var
ValidateEndTime validator.Func = func(fl validator.FieldLevel) bool { endTimeStr := fl.Field().String() // 获取end_time的value endTime, err := time.Parse("2006-01-02 15:04:05", endTimeStr) // 转化为time.Time if err != nil { return false } startTimeStr := fl.Top().FieldByName("StartTime").String() // 获取start_time startTime, err := time.Parse("2006-01-02 15:04:05", startTimeStr) // 转化为time.Time if err != nil { return false } if endTime.Before(startTime) { // start_time和end_time的校验 return false } return true }
完整的示例如下:
type TimeRange struct {
    StartTime string `json:"start_time"  binding:"required"`
    EndTime   string `json:"end_time"    binding:"required,valid_end_time"` // 给end_time绑定自定义validator
} 

// 定义一个handle函数处理请求
func GetTimeRange(c *gin.Context) {
    timeRange := TimeRange{}
    err := c.ShouldBindWith(&timeRange, binding.JSON)
    if err != nil {
        c.AbortWithStatusJSON(http.StatusBadRequest, err.Error())
        return
    }
    c.JSON(http.StatusAccepted, "success")
}

// 主函数
func main() {
    r := gin.Default()
    if v, ok := binding.Validator.Engine().(*validator.Validate); ok {
        v.RegisterValidation("valid_end_time", ValidateEndTime)
    }
    r.POST("/get_time", GetTimeRange)
    r.Run(":8085")
}
注:使用以下两种方式,可以应付日常的绝大多数校验场景
  • 对单字段的校验,通过validator.FieldLevel.Field()获取到参数,进行校验即可;
  • 多跨字段的校验,通过validator.FieldLevel.Top()或validator.FieldLevel.Parent()获取到上层结构体,即可拿到其他字段的值。
posted @ 2022-10-23 14:31  晨枫1  阅读(1582)  评论(0编辑  收藏  举报