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()获取到上层结构体，即可拿到其他字段的值。
