当前位置： 首页 > article >正文

gin源码阅读（1）URL中的参数是如何解析的？

article 2024/11/19 19:57:11

gin源码阅读（1）URL中的参数是如何解析的？

向gin服务器请求时，URL请求参数有两种形式：（1）在路径中的参数，比如"/user/2/send"中的"2"就是用户编号；（2）查询参数，比如“/user/list?page=1&pageSize=5”中的"page"和"pageSize"就是查询参数。

下面分别对这种URL参数进行解读，看看gin中是如何解析这两种参数的。

一、gin是如何解析URL中路径参数的？

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

func main() {
    router := gin.Default()

    // 此 handler 将匹配 /user/john 但不会匹配 /user/ 或者 /user
    router.GET("/user/:name", func(c *gin.Context) {
        name := c.Param("name")
        c.String(http.StatusOK, "Hello %s", name)
    })

    // 此 handler 将匹配 /user/john/ 和 /user/john/send
    // 如果没有其他路由匹配 /user/john，它将重定向到 /user/john/
    router.GET("/user/:name/*action", func(c *gin.Context) {
        name := c.Param("name")  // ref-1
        action := c.Param("action")
        message := name + " is " + action
        c.String(http.StatusOK, message)
    })

    router.Run(":8080")
}

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

// Param returns the value of the URL param.
// It is a shortcut for c.Params.ByName(key)
//
//	router.GET("/user/:id", func(c *gin.Context) {
//	    // a GET request to /user/john
//	    id := c.Param("id") // id == "john"
//	    // a GET request to /user/john/
//	    id := c.Param("id") // id == "/john/"
//	})
func (c *Context) Param(key string) string {
	return c.Params.ByName(key)
}

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

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

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

// Param is a single URL parameter, consisting of a key and a value.
type Param struct {
	Key   string
	Value string
}

// Params is a Param-slice, as returned by the router.
// The slice is ordered, the first URL parameter is also the first slice value.
// It is therefore safe to read values by the index.
type Params []Param

现在有一个问题，这个Params是在哪儿赋值的呢？为了回答这个问题，我们先来看看gin是如何处理http请求的。

先看一下router.Run(":8080")函数的调用，如下所示：


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

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

func (engine *Engine) Handler() http.Handler {
    if !engine.UseH2C {
        return engine
    }

    h2s := &http2.Server{}
    return h2c.NewHandler(engine, h2s)
}

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

type Handler interface {
	ServeHTTP(ResponseWriter, *Request)
}

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

// ServeHTTP conforms to the http.Handler interface.
func (engine *Engine) ServeHTTP(w http.ResponseWriter, req *http.Request) {
    c := engine.pool.Get().(*Context)
    c.writermem.reset(w)
    c.Request = req
    c.reset()

    engine.handleHTTPRequest(c) // ref-3

    engine.pool.Put(c)
}

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

func (engine *Engine) handleHTTPRequest(c *Context) {
	httpMethod := c.Request.Method
	rPath := c.Request.URL.Path
	unescape := false
	if engine.UseRawPath && len(c.Request.URL.RawPath) > 0 {
		rPath = c.Request.URL.RawPath
		unescape = engine.UnescapePathValues
	}

	if engine.RemoveExtraSlash {
		rPath = cleanPath(rPath)
	}

	// Find root of the tree for the given HTTP method
	t := engine.trees
	for i, tl := 0, len(t); i < tl; i++ { // 先找到匹配树中对应的根节点。
		if t[i].method != httpMethod {
			continue
		}
		root := t[i].root
		// Find route in tree
		value := root.getValue(rPath, c.params, c.skippedNodes, unescape) // ref-4
		if value.params != nil {
			c.Params = *value.params // ref-5
		}
		if value.handlers != nil {
			c.handlers = value.handlers
			c.fullPath = value.fullPath
			c.Next()
			c.writermem.WriteHeaderNow()
			return
		}
		if httpMethod != http.MethodConnect && rPath != "/" {
			if value.tsr && engine.RedirectTrailingSlash {
				redirectTrailingSlash(c)
				return
			}
			if engine.RedirectFixedPath && redirectFixedPath(c, root, engine.RedirectFixedPath) {
				return
			}
		}
		break
	}
	...... // 省略其他代码
}

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

在这里插入图片描述

关于字符串搜索树trie可以看轻松搞懂Trie树，这篇文章中有详细的解释。

我们继续回到到代码中，上面的代码会首先找到http请求方法对应的树根(root)，然后在root下面的树中找到对应的节点(value)，并且在ref-5处将节点的params值赋值给域对象中的Params。我们把关注点集中在ref-4中，接着往下看：

// Returns the handle registered with the given path (key). The values of
// wildcards are saved to a map.
// If no handle can be found, a TSR (trailing slash redirect) recommendation is
// made if a handle exists with an extra (without the) trailing slash for the
// given path.
func (n *node) getValue(path string, params *Params, skippedNodes *[]skippedNode, unescape bool) (value nodeValue) {
	var globalParamsCount int16

walk: // Outer loop for walking the tree
	for {
		prefix := n.path
		if len(path) > len(prefix) {
			if path[:len(prefix)] == prefix {
				path = path[len(prefix):]

				// Try all the non-wildcard children first by matching the indices
				idxc := path[0]
				for i, c := range []byte(n.indices) {
					if c == idxc {
						//  strings.HasPrefix(n.children[len(n.children)-1].path, ":") == n.wildChild
						if n.wildChild {
							...... // 省略其他的代码
						}

						n = n.children[i]
						continue walk
					}
				}

				if !n.wildChild {
					...... // 省略其他代码
				}

				// Handle wildcard child, which is always at the end of the array
				n = n.children[len(n.children)-1]
				globalParamsCount++

				switch n.nType {
				case param: // 处理url路径中的占位符参数
					// fix truncate the parameter
					// tree_test.go  line: 204

					// Find param end (either '/' or path end)
					end := 0
					for end < len(path) && path[end] != '/' {
						end++
					}

					// Save param value
					if params != nil && cap(*params) > 0 {
						if value.params == nil {
							value.params = params
						}
						// Expand slice within preallocated capacity
						i := len(*value.params)
						*value.params = (*value.params)[:i+1]
						val := path[:end]
						if unescape {
							if v, err := url.QueryUnescape(val); err == nil {
								val = v
							}
						}
                          // 将路径中的占位符参数的key和value组装到params中
						(*value.params)[i] = Param{
							Key:   n.path[1:],
							Value: val,
						}
					}

					// we need to go deeper!
					if end < len(path) {
						if len(n.children) > 0 {
							path = path[end:]
							n = n.children[0]
							continue walk
						}

						// ... but we can't
						value.tsr = len(path) == end+1
						return
					}

					if value.handlers = n.handlers; value.handlers != nil {
						value.fullPath = n.fullPath
						return
					}
					if len(n.children) == 1 {
						// No handle found. Check if a handle for this path + a
						// trailing slash exists for TSR recommendation
						n = n.children[0]
						value.tsr = (n.path == "/" && n.handlers != nil) || (n.path == "" && n.indices == "/")
					}
					return

                case catchAll: // 处理URL路径中的通配符参数
					...... // 省略其他的代码
				default:
					panic("invalid node type")
				}
			}
		}

		if path == prefix {
			// 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
			// the current node needs to roll back to last valid skippedNode
			if n.handlers == nil && path != "/" {
				for length := len(*skippedNodes); length > 0; length-- {
					skippedNode := (*skippedNodes)[length-1]
					*skippedNodes = (*skippedNodes)[:length-1]
					if strings.HasSuffix(skippedNode.path, path) {
						path = skippedNode.path
						n = skippedNode.node
						if value.params != nil {
							*value.params = (*value.params)[:skippedNode.paramsCount]
						}
						globalParamsCount = skippedNode.paramsCount
						continue walk
					}
				}
				//	n = latestNode.children[len(latestNode.children)-1]
			}
			// We should have reached the node containing the handle.
			// Check if this node has a handle registered.
			if value.handlers = n.handlers; value.handlers != nil {
				value.fullPath = n.fullPath
				return
			}

			// If there is no handle for this route, but this route has a
			// wildcard child, there must be a handle for this path with an
			// additional trailing slash
			if path == "/" && n.wildChild && n.nType != root {
				value.tsr = true
				return
			}

			if path == "/" && n.nType == static {
				value.tsr = true
				return
			}

			// No handle found. Check if a handle for this path + a
			// trailing slash exists for trailing slash recommendation
			for i, c := range []byte(n.indices) {
				if c == '/' {
					n = n.children[i]
					value.tsr = (len(n.path) == 1 && n.handlers != nil) ||
						(n.nType == catchAll && n.children[0].handlers != nil)
					return
				}
			}

			return
		}

		// Nothing found. We can recommend to redirect to the same URL with an
		// extra trailing slash if a leaf exists for that path
		value.tsr = path == "/" ||
			(len(prefix) == len(path)+1 && prefix[len(path)] == '/' &&
				path == prefix[:len(prefix)-1] && n.handlers != nil)

		// roll back to last valid skippedNode
		if !value.tsr && path != "/" {
			for length := len(*skippedNodes); length > 0; length-- {
				skippedNode := (*skippedNodes)[length-1]
				*skippedNodes = (*skippedNodes)[:length-1]
				if strings.HasSuffix(skippedNode.path, path) {
					path = skippedNode.path
					n = skippedNode.node
					if value.params != nil {
						*value.params = (*value.params)[:skippedNode.paramsCount]
					}
					globalParamsCount = skippedNode.paramsCount
					continue walk
				}
			}
		}

		return
	}
}

上面的代码大致分为三个步骤，（1）通过匹配路径找到对应的节点；（2）判断节点的类型；（3）如果节点类型是param，也就是路径参数，那么就会对实际http请求的路径进行解析，组装键值对，并且把组装好的键值对赋值给params中。这个就和前面从Param获取参数连起来了。

二、gin是如何解析URL查询参数的？

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

func main() {
    router := gin.Default()

    // 使用现有的基础请求对象解析查询字符串参数。
    // 示例 URL： /welcome?firstname=Jane&lastname=Doe
    router.GET("/welcome", func(c *gin.Context) {
        firstname := c.DefaultQuery("firstname", "Guest")
        // ref-6
        lastname := c.Query("lastname") // c.Request.URL.Query().Get("lastname") 的一种快捷方式

        c.String(http.StatusOK, "Hello %s %s", firstname, lastname)
    })
    router.Run(":8080")
}

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

func (c *Context) Query(key string) (value string) {
	value, _ = c.GetQuery(key)
	return
}

func (c *Context) GetQuery(key string) (string, bool) {
	if values, ok := c.GetQueryArray(key); ok {
		return values[0], ok
	}
	return "", false
}

func (c *Context) GetQueryArray(key string) (values []string, ok bool) {
	c.initQueryCache()
	values, ok = c.queryCache[key] // 从这儿可以看到是从queryCache中获取的查询参数
	return
}

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

func (c *Context) initQueryCache() {
	if c.queryCache == nil {
		if c.Request != nil {
			c.queryCache = c.Request.URL.Query()  // ref-7
		} else {
			c.queryCache = url.Values{}
		}
	}
}

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

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

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

func ParseQuery(query string) (Values, error) {
	m := make(Values)
	err := parseQuery(m, query)
	return m, err
}

func parseQuery(m Values, query string) (err error) {
	for query != "" {
		var key string
		key, query, _ = strings.Cut(query, "&") // 把query用&符号切开
		if strings.Contains(key, ";") {
			err = fmt.Errorf("invalid semicolon separator in query")
			continue
		}
		if key == "" {
			continue
		}
		key, value, _ := strings.Cut(key, "=") // 把key用=切开
		key, err1 := QueryUnescape(key)
		if err1 != nil {
			if err == nil {
				err = err1
			}
			continue
		}
		value, err1 = QueryUnescape(value)
		if err1 != nil {
			if err == nil {
				err = err1
			}
			continue
		}
		m[key] = append(m[key], value) // 组装key和value数据
	}
	return err
}

其实上面这段代码比较的简单，使用本地断点调试就可以看出来运行过程了，主要是注释strings.Cut(...)函数的使用了。

三、总结

对于URL路径参数，gin会使用为路由构建的trie树来进行匹配，匹配到具体的节点后就会将实际http请求路径中的参数提取出来，并组装为key-value对，赋值给域对象的Params中。

对于URL查询参数，则是直接调用go自带库中的net包进行解析，具体解析过程就是使用strings.Cut(...)函数进行切割，最后组装好键值对放在缓存中。

参考资料：

1、Gin 源码学习（一）丨请求中 URL 的参数是如何解析的？


http://www.kler.cn/a/400530.html

相关文章：

  • 《译文》2024年11月数维杯国际大学生数学建模挑战赛题目
  • [Qt platform plugin问题] Could not load the Qt platform plugin “xcb“
  • 七、箭头函数及简写、arguments、剩余参数、展开运算符、解构数组与对象、数组常见方法(forEach、map、join、reduce)
  • 通过 Docker 对 MySQL 做主从复制的时候，因为ip不对导致不能同步。后又因为二进制的偏移量写的不对，导致不能同步的问题
  • 【Android、IOS、Flutter、鸿蒙、ReactNative 】自定义View
  • C/C++中使用MYSQL
  • FastApi学习第二天：Pydantic对数据的校验和Form表单数据
  • 力扣题解661 图片平滑器
  • 三周精通FastAPI：42 手动运行服务器 - Uvicorn Gunicorn with Uvicorn
  • 群控系统服务端开发模式-应用开发-前端管理员功能开发
  • BLE 蓝牙客户端和服务器连接
  • 纯前端实现语音文字互转
  • 大模型实操练习二、文心大模型API使用方法(入门阶段)
  • 离散数学笔记
  • 【ASR技术】WhisperX安装使用
  • 【论文阅读】InstructPix2Pix: Learning to Follow Image Editing Instructions
  • 键盘上打出反引号符号（´），即单个上标的撇号（这个符号与反引号 ` 不同，反引号通常位于键盘的左上角）
  • DBeaver MACOS 安装 并连接到docker安装的mysql
  • Android 开发与救砖工具介绍
  • Fisher矩阵和Hessian矩阵的关系：证明Fisher为负对数似然函数的Hessian的期望
  • LeetCode 2816.翻倍以链表形式表示的数字
  • 消息队列原理面试题及参考答案
  • 手搓神经网络（MLP）解决MNIST手写数字识别问题 | 数学推导+代码实现 | 仅用numpy，tensor和torch基本计算 | 含正反向传播数学推导
  • 开源控件：Qt/C++自定义颜色组合框控件ColorComboBox
  • 深度学习：循环神经网络的计算复杂度，顺序操作和最大路径长度
  • Spring Boot汽车资讯：科技与速度的新纪元