前言
在 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,配置常用的参数校验标签,来达到参数校验的目的。这样做的好处有两个:
- 参数校验本来不属于业务逻辑,因此将校验代码和业务逻辑处理代码分开,可以使项目结构更清晰;
- 通过提取通用的校验逻辑,比如是不是必填参数,达到代码复用的目的。
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()获取到上层结构体,即可拿到其他字段的值。