gin源码阅读（1）URL中的参数是怎样剖析的？

gin源码阅读（1）URL中的参数是怎样剖析的？

向gin服务器哀求时，URL哀求参数有两种情势：（1）在路径中的参数，比如"/user/2/send"中的"2"就是用户编号；（2）查询参数，比如“/user/list?page=1&pageSize=5”中的"page"和"pageSize"就是查询参数。
下面分别对这种URL参数举行解读，看看gin中是怎样剖析这两种参数的。
一、gin是怎样剖析URL中路径参数的？

先看一个官方给出的例子：

1. func main() {
2.     router := gin.Default()
4.     // 此 handler 将匹配 /user/john 但不会匹配 /user/ 或者 /user
5.     router.GET("/user/:name", func(c *gin.Context) {
6.         name := c.Param("name")
7.         c.String(http.StatusOK, "Hello %s", name)
8.     })
10.     // 此 handler 将匹配 /user/john/ 和 /user/john/send
11.     // 如果没有其他路由匹配 /user/john，它将重定向到 /user/john/
12.     router.GET("/user/:name/*action", func(c *gin.Context) {
13.         name := c.Param("name")  // ref-1
14.         action := c.Param("action")
15.         message := name + " is " + action
16.         c.String(http.StatusOK, message)
17.     })
19.     router.Run(":8080")
20. }

复制代码

在ref-1处利用了Param(...)函数获取路径中"name"参数的值，我们详细看一下该函数的细节：

1. // Param returns the value of the URL param.
2. // It is a shortcut for c.Params.ByName(key)
3. //
4. //        router.GET("/user/:id", func(c *gin.Context) {
5. //            // a GET request to /user/john
6. //            id := c.Param("id") // id == "john"
7. //            // a GET request to /user/john/
8. //            id := c.Param("id") // id == "/john/"
9. //        })
10. func (c *Context) Param(key string) string {
11.         return c.Params.ByName(key)
12. }

复制代码

解释中写的很明白，Param(...)函数就是c.Params.ByName(key)的一个简写，我们继续看c.Params.ByName(key)细节：

1. // ByName returns the value of the first Param which key matches the given name.
2. // If no matching Param is found, an empty string is returned.
3. func (ps Params) ByName(name string) (va string) {
4.         va, _ = ps.Get(name)
5.         return
6. }

复制代码

ByName(...)函数就是在从Params中获取键值对数据，我们来看看Params结构体的界说：

1. // Param is a single URL parameter, consisting of a key and a value.
2. type Param struct {
3.         Key   string
4.         Value string
5. }
7. // Params is a Param-slice, as returned by the router.
8. // The slice is ordered, the first URL parameter is also the first slice value.
9. // It is therefore safe to read values by the index.
10. type Params []Param

复制代码

现在有一个标题，这个Params是在哪儿赋值的呢？为了答复这个标题，我们先来看看gin是如那边置处罚http哀求的。
先看一下router.Run(":8080")函数的调用，如下所示：

2. func (engine *Engine) Run(addr ...string) (err error) {
3.         ...... // 省略其他代码
4.         address := resolveAddress(addr)
5.         debugPrint("Listening and serving HTTP on %s\n", address)
6.         err = http.ListenAndServe(address, engine.Handler()) // ref-2
7.         return
8. }

复制代码

可以看到实在Run方法调用了go自带库中的http.ListenAndServe(...)方法，而且注册了处置处罚器engine.Handler()，这就很明白，http哀求就是被注册的handler处置处罚的，我们详细来看一下：

1. func (engine *Engine) Handler() http.Handler {
2.     if !engine.UseH2C {
3.         return engine
4.     }
6.     h2s := &http2.Server{}
7.     return h2c.NewHandler(engine, h2s)
8. }

复制代码

这内里的h2c不是本次要关注的内容，这儿现实返回的是engine，那么engine就应该实现了下面的接口：

1. type Handler interface {
2.         ServeHTTP(ResponseWriter, *Request)
3. }

复制代码

我们可以就接着看engine中ServeHTTP(...)方法的实现，如下所示：

1. // ServeHTTP conforms to the http.Handler interface.
2. func (engine *Engine) ServeHTTP(w http.ResponseWriter, req *http.Request) {
3.     c := engine.pool.Get().(*Context)
4.     c.writermem.reset(w)
5.     c.Request = req
6.     c.reset()
8.     engine.handleHTTPRequest(c) // ref-3
10.     engine.pool.Put(c)
11. }

复制代码

现实处置处罚哀求的就是ref-3处的代码，我们继续往下看，该函数的实现如下所示：

1. func (engine *Engine) handleHTTPRequest(c *Context) {
2.         httpMethod := c.Request.Method
3.         rPath := c.Request.URL.Path
4.         unescape := false
5.         if engine.UseRawPath && len(c.Request.URL.RawPath) > 0 {
6.                 rPath = c.Request.URL.RawPath
7.                 unescape = engine.UnescapePathValues
8.         }
10.         if engine.RemoveExtraSlash {
11.                 rPath = cleanPath(rPath)
12.         }
14.         // Find root of the tree for the given HTTP method
15.         t := engine.trees
16.         for i, tl := 0, len(t); i < tl; i++ { // 先找到匹配树中对应的根节点。
17.                 if t[i].method != httpMethod {
18.                         continue
19.                 }
20.                 root := t[i].root
21.                 // Find route in tree
22.                 value := root.getValue(rPath, c.params, c.skippedNodes, unescape) // ref-4
23.                 if value.params != nil {
24.                         c.Params = *value.params // ref-5
25.                 }
26.                 if value.handlers != nil {
27.                         c.handlers = value.handlers
28.                         c.fullPath = value.fullPath
29.                         c.Next()
30.                         c.writermem.WriteHeaderNow()
31.                         return
32.                 }
33.                 if httpMethod != http.MethodConnect && rPath != "/" {
34.                         if value.tsr && engine.RedirectTrailingSlash {
35.                                 redirectTrailingSlash(c)
36.                                 return
37.                         }
38.                         if engine.RedirectFixedPath && redirectFixedPath(c, root, engine.RedirectFixedPath) {
39.                                 return
40.                         }
41.                 }
42.                 break
43.         }
44.         ...... // 省略其他代码
45. }

复制代码

gin现实上会将注册的路由构成一个trie树结构，在网上找了一个gin为路由构建的树表示图，如下所示：

关于字符串搜索树trie可以看轻松搞懂Trie树，这篇文章中有详细的表明。
我们继续回到到代码中，上面的代码会起首找到http哀求方法对应的树根(root)，然后在root下面的树中找到对应的节点(value)，而且在ref-5处将节点的params值赋值给域对象中的Params。我们把关注点会集在ref-4中，接着往下看：

1. // Returns the handle registered with the given path (key). The values of
2. // wildcards are saved to a map.
3. // If no handle can be found, a TSR (trailing slash redirect) recommendation is
4. // made if a handle exists with an extra (without the) trailing slash for the
5. // given path.
6. func (n *node) getValue(path string, params *Params, skippedNodes *[]skippedNode, unescape bool) (value nodeValue) {
7.         var globalParamsCount int16
9. walk: // Outer loop for walking the tree
10.         for {
11.                 prefix := n.path
12.                 if len(path) > len(prefix) {
13.                         if path[:len(prefix)] == prefix {
14.                                 path = path[len(prefix):]
16.                                 // Try all the non-wildcard children first by matching the indices
17.                                 idxc := path[0]
18.                                 for i, c := range []byte(n.indices) {
19.                                         if c == idxc {
20.                                                 //  strings.HasPrefix(n.children[len(n.children)-1].path, ":") == n.wildChild
21.                                                 if n.wildChild {
22.                                                         ...... // 省略其他的代码
23.                                                 }
25.                                                 n = n.children[i]
26.                                                 continue walk
27.                                         }
28.                                 }
30.                                 if !n.wildChild {
31.                                         ...... // 省略其他代码
32.                                 }
34.                                 // Handle wildcard child, which is always at the end of the array
35.                                 n = n.children[len(n.children)-1]
36.                                 globalParamsCount++
38.                                 switch n.nType {
39.                                 case param: // 处理url路径中的占位符参数
40.                                         // fix truncate the parameter
41.                                         // tree_test.go  line: 204
43.                                         // Find param end (either '/' or path end)
44.                                         end := 0
45.                                         for end < len(path) && path[end] != '/' {
46.                                                 end++
47.                                         }
49.                                         // Save param value
50.                                         if params != nil && cap(*params) > 0 {
51.                                                 if value.params == nil {
52.                                                         value.params = params
53.                                                 }
54.                                                 // Expand slice within preallocated capacity
55.                                                 i := len(*value.params)
56.                                                 *value.params = (*value.params)[:i+1]
57.                                                 val := path[:end]
58.                                                 if unescape {
59.                                                         if v, err := url.QueryUnescape(val); err == nil {
60.                                                                 val = v
61.                                                         }
62.                                                 }
63.                           // 将路径中的占位符参数的key和value组装到params中
64.                                                 (*value.params)[i] = Param{
65.                                                         Key:   n.path[1:],
66.                                                         Value: val,
67.                                                 }
68.                                         }
70.                                         // we need to go deeper!
71.                                         if end < len(path) {
72.                                                 if len(n.children) > 0 {
73.                                                         path = path[end:]
74.                                                         n = n.children[0]
75.                                                         continue walk
76.                                                 }
78.                                                 // ... but we can't
79.                                                 value.tsr = len(path) == end+1
80.                                                 return
81.                                         }
83.                                         if value.handlers = n.handlers; value.handlers != nil {
84.                                                 value.fullPath = n.fullPath
85.                                                 return
86.                                         }
87.                                         if len(n.children) == 1 {
88.                                                 // No handle found. Check if a handle for this path + a
89.                                                 // trailing slash exists for TSR recommendation
90.                                                 n = n.children[0]
91.                                                 value.tsr = (n.path == "/" && n.handlers != nil) || (n.path == "" && n.indices == "/")
92.                                         }
93.                                         return
95.                 case catchAll: // 处理URL路径中的通配符参数
96.                                         ...... // 省略其他的代码
97.                                 default:
98.                                         panic("invalid node type")
99.                                 }
100.                         }
101.                 }
103.                 if path == prefix {
104.                         // If the current path does not equal '/' and the node does not have a registered handle and the most recently matched node has a child node
105.                         // the current node needs to roll back to last valid skippedNode
106.                         if n.handlers == nil && path != "/" {
107.                                 for length := len(*skippedNodes); length > 0; length-- {
108.                                         skippedNode := (*skippedNodes)[length-1]
109.                                         *skippedNodes = (*skippedNodes)[:length-1]
110.                                         if strings.HasSuffix(skippedNode.path, path) {
111.                                                 path = skippedNode.path
112.                                                 n = skippedNode.node
113.                                                 if value.params != nil {
114.                                                         *value.params = (*value.params)[:skippedNode.paramsCount]
115.                                                 }
116.                                                 globalParamsCount = skippedNode.paramsCount
117.                                                 continue walk
118.                                         }
119.                                 }
120.                                 //        n = latestNode.children[len(latestNode.children)-1]
121.                         }
122.                         // We should have reached the node containing the handle.
123.                         // Check if this node has a handle registered.
124.                         if value.handlers = n.handlers; value.handlers != nil {
125.                                 value.fullPath = n.fullPath
126.                                 return
127.                         }
129.                         // If there is no handle for this route, but this route has a
130.                         // wildcard child, there must be a handle for this path with an
131.                         // additional trailing slash
132.                         if path == "/" && n.wildChild && n.nType != root {
133.                                 value.tsr = true
134.                                 return
135.                         }
137.                         if path == "/" && n.nType == static {
138.                                 value.tsr = true
139.                                 return
140.                         }
142.                         // No handle found. Check if a handle for this path + a
143.                         // trailing slash exists for trailing slash recommendation
144.                         for i, c := range []byte(n.indices) {
145.                                 if c == '/' {
146.                                         n = n.children[i]
147.                                         value.tsr = (len(n.path) == 1 && n.handlers != nil) ||
148.                                                 (n.nType == catchAll && n.children[0].handlers != nil)
149.                                         return
150.                                 }
151.                         }
153.                         return
154.                 }
156.                 // Nothing found. We can recommend to redirect to the same URL with an
157.                 // extra trailing slash if a leaf exists for that path
158.                 value.tsr = path == "/" ||
159.                         (len(prefix) == len(path)+1 && prefix[len(path)] == '/' &&
160.                                 path == prefix[:len(prefix)-1] && n.handlers != nil)
162.                 // roll back to last valid skippedNode
163.                 if !value.tsr && path != "/" {
164.                         for length := len(*skippedNodes); length > 0; length-- {
165.                                 skippedNode := (*skippedNodes)[length-1]
166.                                 *skippedNodes = (*skippedNodes)[:length-1]
167.                                 if strings.HasSuffix(skippedNode.path, path) {
168.                                         path = skippedNode.path
169.                                         n = skippedNode.node
170.                                         if value.params != nil {
171.                                                 *value.params = (*value.params)[:skippedNode.paramsCount]
172.                                         }
173.                                         globalParamsCount = skippedNode.paramsCount
174.                                         continue walk
175.                                 }
176.                         }
177.                 }
179.                 return
180.         }
181. }

复制代码

上面的代码大抵分为三个步调，（1）通过匹配路径找到对应的节点；（2）判断节点的范例；（3）如果节点范例是param，也就是路径参数，那么就会对现实http哀求的路径举行剖析，组装键值对，而且把组装好的键值对赋值给params中。这个就和前面从Param获取参数连起来了。
二、gin是怎样剖析URL查询参数的？

仍然是从官网给出的示例步调代码开始看起：

1. func main() {
2.     router := gin.Default()
4.     // 使用现有的基础请求对象解析查询字符串参数。
5.     // 示例 URL： /welcome?firstname=Jane&lastname=Doe
6.     router.GET("/welcome", func(c *gin.Context) {
7.         firstname := c.DefaultQuery("firstname", "Guest")
8.         // ref-6
9.         lastname := c.Query("lastname") // c.Request.URL.Query().Get("lastname") 的一种快捷方式
11.         c.String(http.StatusOK, "Hello %s %s", firstname, lastname)
12.     })
13.     router.Run(":8080")
14. }

复制代码

ref-6处代码调用了Query的代码，如下所示：

1. func (c *Context) Query(key string) (value string) {
2.         value, _ = c.GetQuery(key)
3.         return
4. }
6. func (c *Context) GetQuery(key string) (string, bool) {
7.         if values, ok := c.GetQueryArray(key); ok {
8.                 return values[0], ok
9.         }
10.         return "", false
11. }
13. func (c *Context) GetQueryArray(key string) (values []string, ok bool) {
14.         c.initQueryCache()
15.         values, ok = c.queryCache[key] // 从这儿可以看到是从queryCache中获取的查询参数
16.         return
17. }

复制代码

上述代码的关键就在于c.initQueryCache()了，我们接着往下看：

1. func (c *Context) initQueryCache() {
2.         if c.queryCache == nil {
3.                 if c.Request != nil {
4.                         c.queryCache = c.Request.URL.Query()  // ref-7
5.                 } else {
6.                         c.queryCache = url.Values{}
7.                 }
8.         }
9. }

复制代码

ref-7的代码展示了queryCache的泉源，细节如下所示：

1. func (u *URL) Query() Values {
2.         v, _ := ParseQuery(u.RawQuery)
3.         return v
4. }

复制代码

留意，从这儿开始已经进入到了go的net包下的url包了。我们继续看ParseQuery函数：

1. func ParseQuery(query string) (Values, error) {
2.         m := make(Values)
3.         err := parseQuery(m, query)
4.         return m, err
5. }
7. func parseQuery(m Values, query string) (err error) {
8.         for query != "" {
9.                 var key string
10.                 key, query, _ = strings.Cut(query, "&") // 把query用&符号切开
11.                 if strings.Contains(key, ";") {
12.                         err = fmt.Errorf("invalid semicolon separator in query")
13.                         continue
14.                 }
15.                 if key == "" {
16.                         continue
17.                 }
18.                 key, value, _ := strings.Cut(key, "=") // 把key用=切开
19.                 key, err1 := QueryUnescape(key)
20.                 if err1 != nil {
21.                         if err == nil {
22.                                 err = err1
23.                         }
24.                         continue
25.                 }
26.                 value, err1 = QueryUnescape(value)
27.                 if err1 != nil {
28.                         if err == nil {
29.                                 err = err1
30.                         }
31.                         continue
32.                 }
33.                 m[key] = append(m[key], value) // 组装key和value数据
34.         }
35.         return err
36. }

复制代码

实在上面这段代码比力的简朴，利用本地断点调试就可以看出来运行过程了，重要是解释strings.Cut(...)函数的利用了。
三、总结

对于URL路径参数，gin会利用为路由构建的trie树来举行匹配，匹配到详细的节点后就会将现实http哀求路径中的参数提取出来，并组装为key-value对，赋值给域对象的Params中。
对于URL查询参数，则是直接调用go自带库中的net包举行剖析，详细剖析过程就是利用strings.Cut(...)函数举行切割，末了组装好键值对放在缓存中。
参考资料：
1、Gin 源码学习（一）丨哀求中 URL 的参数是怎样剖析的？