Gin源码分析 – Context之Query
1 介绍
Gin中可以方便的获取URL中的查询参数，或者也可以简称为URL参数，此类参数以?为起点，后面的k=v&k1=v1&k2=v2这样的字符串就是查询参数，本小节通过示例演示获取URL查询参数的方式，以及背后的实现方式。
package main
import (
"net/http"
"github.com/gin-gonic/gin"
)
func main() {
r := gin.Default()
// GET请求 url ?后面是querystring参数,key = value格式,多个key-value用&连接
// eg: /queryParams?name=randySun&age=18
r.GET("/queryParams", func(c *gin.Context) {
name := c.Query("name")
age := c.Query("age")
c.JSON(http.StatusOK, gin.H{
"name": name,
"age": age,
})
})
r.GET("/queryDefault", func(c *gin.Context) {
name := c.DefaultQuery("name", "body")
age := c.DefaultQuery("age", "18")
c.JSON(http.StatusOK, gin.H{
"name": name,
"age": age,
})
})
r.GET("/queryGet", func(c *gin.Context) {
name, ok := c.GetQuery("name")
if !ok {
name = "body"
}
age, ok := c.GetQuery("age")
if !ok {
age = "18"
}
c.JSON(http.StatusOK, gin.H{
"name": name,
"age": age,
})
})
r.Run(":9999")
}
有三种获取URL查询参数的方式，分别是Query、DefaultQuery和GetQuery。其中最基本的是Query，针对上面的例子，使用curl测试如下。
curl "127.0.0.1:9999/queryParams?name=TerryPro&age=10 "
{"age":"10","name":"TerryPro"}
2 Query分析
// Query returns the keyed url query value if it exists,
// otherwise it returns an empty string `("")`.
// It is shortcut for `c.Request.URL.Query().Get(key)`
// GET /path?id=1234&name=Manu&value=
// c.Query("id") == "1234"
// c.Query("name") == "Manu"
// c.Query("value") == ""
// c.Query("wtf") == ""
func (c *Context) Query(key string) string {
value, _ := c.GetQuery(key)
return value
}
通过注释可以看出，Query返回参数值，如果不存在的话则返回空字符串””。在内部使用GetQuery获取具体的参数值。
3 GetQuery分析
// GetQuery is like Query(), it returns the keyed url query value
// if it exists `(value, true)` (even when the value is an empty string),
// otherwise it returns `("", false)`.
// It is shortcut for `c.Request.URL.Query().Get(key)`
// GET /?name=Manu&lastname=
// ("Manu", true) == c.GetQuery("name")
// ("", false) == c.GetQuery("id")
// ("", true) == c.GetQuery("lastname")
func (c *Context) GetQuery(key string) (string, bool) {
if values, ok := c.GetQueryArray(key); ok {
return values[0], ok
}
return "", false
}
GetQuery内部调用GetQueryArray获取URL查询参数的值，如果查询参数存在的话，则返回（value，true），如果参数值存在但是没有设置值，则返回（””, true），见注释中的lastname；如果不存在的话则返回(“”，false)。GetQueryArray实际上返回的是数组，后面会详细分析。GetQuery仅返回第一个就行。
4 GetQueryArray分析
// GetQueryArray returns a slice of strings for a given query key, plus
// a boolean value whether at least one value exists for the given key.
func (c *Context) GetQueryArray(key string) ([]string, bool) {
c.initQueryCache()
if values, ok := c.queryCache[key]; ok && len(values) > 0 {
return values, true
}
return []string{}, false
}
func (c *Context) initQueryCache() {
if c.queryCache == nil {
if c.Request != nil {
c.queryCache = c.Request.URL.Query()
} else {
c.queryCache = url.Values{}
}
}
}
type Values map[string][]string
type Context struct {
// queryCache use url.ParseQuery cached the param query result from c.Request.URL.Query()
queryCache url.Values
}
（1）首次调用initQueryCache获取查询参数，由于在一个请求中可能会多次调用Query方法因此使用Context中的queryCache对Query参数进行了缓存。
（2）通过源码可以看出，queryCache的类型是一个键类型为字符串，值类型是字符串切片。
（3）initQueryCache调用URL的Query方法对URL进行解析。
5 GetQuery分析
// DefaultQuery returns the keyed url query value if it exists,
// otherwise it returns the specified defaultValue string.
// See: Query() and GetQuery() for further information.
// GET /?name=Manu&lastname=
// c.DefaultQuery("name", "unknown") == "Manu"
// c.DefaultQuery("id", "none") == "none"
// c.DefaultQuery("lastname", "none") == ""
func (c *Context) DefaultQuery(key, defaultValue string) string {
if value, ok := c.GetQuery(key); ok {
return value
}
return defaultValue
}
GetQuery和Query的区别是，如果没有查询到相应的参数则直接返回传入的参数defaultValue。
6 查询数组
从上面的分析可以看出Gin还提供了QueryArray和GetQueryArray两种方法能够获取URL中的数组，例子如下：
r.GET("/queryArray", func(c *gin.Context) {
name := c.QueryArray("name")
c.JSON(http.StatusOK, gin.H{
"name": name,
})
})
curl "http://127.0.0.1:9999/queryArray?name=TerryPro&name=Hexiaoyu"
{"name":["TerryPro","Hexiaoyu"]}
可以看出当URL中存在多个重复的参数时，调用QueryArray时可以返回一个数组切片。第4节对GetQueryArray进行了分析，下面对QueryArray进行简单的分析。
7 QueryArray分析
// QueryArray returns a slice of strings for a given query key.
// The length of the slice depends on the number of params with the given key.
func (c *Context) QueryArray(key string) []string {
values, _ := c.GetQueryArray(key)
return values
}
QueryArray在内部调用GetQueryArray，如果不存在待查询的参数，则返回[]string{}。
8 QueryMap
Context中还提供了2个函数QueryMap、GetQueryMap，用于将Query参数转化成map的形式，这两个函数处理的URL查询参数形式为：?params[key1]=value1¶ms[key2]=value2¶ms[key3]=value3，下面举个例子，同时对相应的源码进行分析。
r.GET("/queryMap", func(c *gin.Context) {
params := c.QueryMap("params")
c.JSON(http.StatusOK, gin.H{
"params": params,
})
})
使用如下命令进行测试。
curl "127.0.0.1:9999/queryMap?params\[key1\]=value1¶ms\[key2\]=value2¶ms\[key3\]=value3"
{"params":{"key1":"value1","key2":"value2","key3":"value3"}}
注意在curl命令中发送多个参数使用””，并且需要对[]进行转移处理。下面对QueryMap和GetQueryMap函数进行分析。
// QueryMap returns a map for a given query key.
func (c *Context) QueryMap(key string) map[string]string {
dicts, _ := c.GetQueryMap(key)
return dicts
}
// GetQueryMap returns a map for a given query key, plus a boolean value
// whether at least one value exists for the given key.
func (c *Context) GetQueryMap(key string) (map[string]string, bool) {
// 缓存参数到queryCache中，然后对参数进行解析
c.initQueryCache()
return c.get(c.queryCache, key)
}
// get is an internal method and returns a map which satisfy conditions.
func (c *Context) get(m map[string][]string, key string) (map[string]string, bool) {
dicts := make(map[string]string)
exist := false
for k, v := range m {
if i := strings.IndexByte(k, '['); i >= 1 && k[0:i] == key {
if j := strings.IndexByte(k[i+1:], ']'); j >= 1 {
exist = true
dicts[k[i+1:][:j]] = v[0]
}
}
}
return dicts, exist
}
（1）QueryMap内部调用GetQueryMap，GetQueryMap返回一个map[string]string的参数值和一个是否成功的标识；首先仍然解析查询参数并缓存到queryCache中，调用一个内部的get从queryCache中获取map参数；
（2）get函数看起来比较复杂，实际上是一个解析方法，针对每一个参数，将其分解为key、'[‘、mapkey、’]’四个部分，比如上面的params[key1]就被分解为params、'[‘、 key1、 ‘]’四个字段，匹配params成功后，则在dicts中创建一个字段，dicts[key1] = value1。
9 小节
在Gin中接收数组是比较常用的，但是map不常用。其实对于接收参数来说，不光我们可以从URL查询参数中获得，还可以从提交的表单(Form)中获得，它们的原理是大同小异的，使用方式也非常像，下一篇就介绍表单的使用和原理分析。