gin 路由树的实现

一 路由树

gin 框架路由的实现使用了压缩字典树，压缩字典树是变种的字典树，相比字典树而言，使用压缩字典树可以降低树的层数。
下面介绍gin 框架路由树的实现，路由树节点的定义：

type node struct {
	// 相对路径
	path      string
	// 索引
	indices   string
	// 子节点
	children  []*node
	// 处理器函数
	handlers  HandlersChain
	// 优先级
	priority  uint32
	// 节点类型
	nType     nodeType
	// （即*与：个数）
	maxParams uint8
	// 子节点是否为参数节点，若子节点包含*或：，则为true
	wildChild bool
	fullPath  string
}

gin中定义了以下类型的节点

nType: 当前节点类型，有四个枚举值: 分别为 static/root/param/catchAll。
    static                   // 非根节点的普通字符串节点
    root                     // 根节点
    param                    // 参数节点，例如 :id
    catchAll                 // 通配符节点，例如 *anyway

gin 框架针对通配符进行了特殊处理。

gin框架中‘:’通配符只能如此使用
1 /ab/:x
2 /ab/:x/cd 可以
3 /ab/c  与1冲突
4 /ab/:cd 与1冲突
对于‘*’通配符，只能使用在路径末尾
1 /ab/*file  可以，匹配‘/ab/xxxx', xxxx可以为任意值，如/afile, /abm等等
2 /ab/*mm 与1冲突
3 /ab/*file/ss  错误，'*' 只能用于路径末尾

添加路径

// addRoute adds a node with the given handle to the path.
// Not concurrency-safe!
func (n *node) addRoute(path string, handlers HandlersChain) {
	fullPath := path
	n.priority++    @1
	// 计算路径中：与*的个数
	numParams := countParams(path)

	parentFullPathIndex := 0

	// non-empty tree
	if len(n.path) > 0 || len(n.children) > 0 {
	walk:
		for {
			// Update maxParams of the current node
			if numParams > n.maxParams {
				n.maxParams = numParams
			}

			// Find the longest common prefix.
			// This also implies that the common prefix contains no 
			// since the existing key can't contain those chars.
			// 如果现在存在的路径不包含'*'或‘：’，那么公共前缀中也不会含有*或：
			i := 0
			max := min(len(path), len(n.path))
			for i < max && path[i] == n.path[i] {
				i++
			}

			// Split edge
			// 分裂边，对现有节点的内容提取处理作为子节点，再把公共前缀部分提取出来作为父节点
			if i < len(n.path) {
				child := node{
					path:      n.path[i:],
					wildChild: n.wildChild,
					indices:   n.indices,
					children:  n.children,
					handlers:  n.handlers,
					//  对比：@1
					priority:  n.priority - 1,
					fullPath:  n.fullPath,
				}

				// Update maxParams (max of all children)
				for i := range child.children {
					if child.children[i].maxParams > child.maxParams {
						child.maxParams = child.children[i].maxParams
					}
				}

				n.children = []*node{&child}
				// []byte for proper unicode char conversion, see #65
				// 索引位置
				n.indices = string([]byte{n.path[i]})
				n.path = path[:i]
				// 生成父节点为空节点
				n.handlers = nil
				// 进行边分裂的节点必定不是参数节点
				n.wildChild = false
				n.fullPath = fullPath[:parentFullPathIndex+i]
			}

			// Make new node a child of this node
			// 生成子节点
			if i < len(path) {
				path = path[i:]

				// 子节点为参数节点
				if n.wildChild {
					parentFullPathIndex += len(n.path)
					// 包含*或：的路径节点必定是父节点的唯一子节点
					n = n.children[0]
					n.priority++

					// Update maxParams of the child node
					if numParams > n.maxParams {
						n.maxParams = numParams
					}
					numParams--

					// Check if the wildcard matches
					// 新添加的节点包含参数的这一部分路径必定与原有路径值相同
					if len(path) >= len(n.path) && n.path == path[:len(n.path)] {
						// check for longer wildcard, e.g. :name and :names
			            // 假定：n.path = /:ab
			            // path = /:ab 或 /:ab/xxxx
						if len(n.path) >= len(path) || path[len(n.path)] == '/' {
							continue walk
						}
					}

					pathSeg := path
					if n.nType != catchAll {
						pathSeg = strings.SplitN(path, "/", 2)[0]
					}
					prefix := fullPath[:strings.Index(fullPath, pathSeg)] + n.path
					panic("'" + pathSeg +
						"' in new path '" + fullPath +
						"' conflicts with existing wildcard '" + n.path +
						"' in existing prefix '" + prefix +
						"'")
				}

				c := path[0]

				// slash after param
				// 该节点为参数节点，且有一个孩子节点，则新添加的节点必定需要添加到孩子节点上
				if n.nType == param && c == '/' && len(n.children) == 1 {
					parentFullPathIndex += len(n.path)
					n = n.children[0]
					n.priority++
					continue walk
				}

				// Check if a child with the next path byte exists
				// 对比已有的孩子节点进行递归
				for i := 0; i < len(n.indices); i++ {
					if c == n.indices[i] {
						parentFullPathIndex += len(n.path)
						i = n.incrementChildPrio(i)
						n = n.children[i]
						continue walk
					}
				}

				// Otherwise insert it
				// 添加新的节点
				if c != ':' && c != '*' {
					// []byte for proper unicode char conversion, see #65
					n.indices += string([]byte{c})
					child := &node{
						maxParams: numParams,
						fullPath:  fullPath,
					}
					n.children = append(n.children, child)
					n.incrementChildPrio(len(n.indices) - 1)
					n = child
				}
				n.insertChild(numParams, path, fullPath, handlers)
				return

			} else if i == len(path) { // Make node a (in-path) leaf
				// 如果现有节点上的处理函数不为空，则报错
				if n.handlers != nil {
					panic("handlers are already registered for path '" + fullPath + "'")
				}
				n.handlers = handlers
			}
			return
		}
	} else { 
		// 路由树为空，直接添加新节点
		n.insertChild(numParams, path, fullPath, handlers)
		n.nType = root
	}
}

添加节点

func (n *node) insertChild(numParams uint8, path string, fullPath string, handlers HandlersChain) {
	var offset int // already handled bytes of the path

	// find prefix until first wildcard (beginning with ':' or '*')
	// 循环主要用于处理path中的参数路径部分
	for i, max := 0, len(path); numParams > 0; i++ {
		c := path[i]
		if c != ':' && c != '*' {
			continue
		}

		// find wildcard end (either '/' or path end)
		end := i + 1
		for end < max && path[end] != '/' {
			switch path[end] {
			// the wildcard name must not contain ':' and '*'
			case ':', '*':
				panic("only one wildcard per path segment is allowed, has: '" +
					path[i:] + "' in path '" + fullPath + "'")
			default:
				end++
			}
		}

		// check if this Node existing children which would be
		// unreachable if we insert the wildcard here
		if len(n.children) > 0 {
			panic("wildcard route '" + path[i:end] +
				"' conflicts with existing children in path '" + fullPath + "'")
		}

		// check if the wildcard has a name
		if end-i < 2 {
			panic("wildcards must be named with a non-empty name in path '" + fullPath + "'")
		}

		if c == ':' { 
			// param 节点
			// split path at the beginning of the wildcard
			if i > 0 {
				// 修订父节点的path
				// 情况： n.path = /ab
				// path = /ab/:cf
				// 修订 n.path = /ab/
				n.path = path[offset:i]
				offset = i
			}

			child := &node{
				nType:     param,
				maxParams: numParams,
				fullPath:  fullPath,
			}
			n.children = []*node{child}
			n.wildChild = true
			n = child
			n.priority++
			numParams--

			// if the path doesn't end with the wildcard, then there
			// will be another non-wildcard subpath starting with '/'
			// 情况：path = /ab/:ef/cf
			// 添加节点（path= :ef) 后，再为该节点添加一个子节点，与标示1处代码相配合
			if end < max {
				n.path = path[offset:end]
				offset = end

				child := &node{
					maxParams: numParams,
					priority:  1,
					fullPath:  fullPath,
				}
				n.children = []*node{child}
				n = child
			}

		} else { // catchAll
			// catchAll节点只能添加在末尾，包含一个空路径节点和一个真正的节点
			if end != max || numParams > 1 {
				panic("catch-all routes are only allowed at the end of the path in path '" + fullPath + "'")
			}

			if len(n.path) > 0 && n.path[len(n.path)-1] == '/' {
				panic("catch-all conflicts with existing handle for the path segment root in path '" + fullPath + "'")
			}

			// currently fixed width 1 for '/'
			i--
			if path[i] != '/' {
				panic("no / before catch-all in path '" + fullPath + "'")
			}

			n.path = path[offset:i]

			// first node: catchAll node with empty path
			child := &node{
				wildChild: true,
				nType:     catchAll,
				maxParams: 1,
				fullPath:  fullPath,
			}
			n.children = []*node{child}
			n.indices = string(path[i])
			n = child
			n.priority++

			// second node: node holding the variable
			child = &node{
				path:      path[i:],
				nType:     catchAll,
				maxParams: 1,
				handlers:  handlers,
				priority:  1,
				fullPath:  fullPath,
			}
			n.children = []*node{child}

			return
		}
	}

	// insert remaining path part and handle to the leaf
	// 处理完了参数路径部分，可以直接添加该节点
	n.path = path[offset:]  @1
	n.handlers = handlers   @1
	n.fullPath = fullPath  @1
}

查找路径处理函数

// nodeValue holds return values of (*Node).getValue method
type nodeValue struct {
	handlers HandlersChain
	params   Params
	tsr      bool
	fullPath string
}
type Params []Param
// Param is a single URL parameter, consisting of a key and a value.
 type Param struct {
     Key   string
     Value string
  }
// getValue 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, po Params, unescape bool) (value nodeValue) {
	value.params = po
walk: // Outer loop for walking the tree
	for {
		if len(path) > len(n.path) {
			if path[:len(n.path)] == n.path {
				path = path[len(n.path):]
				// If this node does not have a wildcard (param or catchAll)
				// child,  we can just look up the next child node and continue
				// to walk down the tree
				if !n.wildChild {
					c := path[0]
					for i := 0; i < len(n.indices); i++ {
						if c == n.indices[i] {
							n = n.children[i]
							continue walk
						}
					}

					// Nothing found.
					// We can recommend to redirect to the same URL without a
					// trailing slash if a leaf exists for that path.
					// 尝试重定向到不含‘/’的路径
					value.tsr = path == "/" && n.handlers != nil
					return
				}

				// handle wildcard child
				n = n.children[0]
				switch n.nType {
				case param:
					// find param end (either '/' or path end)
					end := 0
					for end < len(path) && path[end] != '/' {
						end++
					}
					// save param value
					// 保存请求路径中的参数值
					if cap(value.params) < int(n.maxParams) {
						value.params = make(Params, 0, n.maxParams)
					}
					i := len(value.params)
					// 在原有地址上扩展
					value.params = value.params[:i+1] // expand slice within preallocated capacity
					// 插入的参数节点，path格式如下 :ab
					value.params[i].Key = n.path[1:]
					val := path[:end]
					if unescape {
						var err error
						if value.params[i].Value, err = url.QueryUnescape(val); err != nil {
							value.params[i].Value = val // fallback, in case of error
						}
					} else {
						value.params[i].Value = val
					}

					// we need to go deeper!
					if end < len(path) {
						if len(n.children) > 0 {
							// 参数节点的子节点只会有一个，格式为下面两种
							// :ab
							//    / 或者 /xx
							// 如果存在多个孩子，则会生成path为“/”的父节点作为参数节点的子节点
							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]
						// 参数节点的孩子，path为“/”， 会再次尝试获取
						value.tsr = n.path == "/" && n.handlers != nil
					}

					return

				case catchAll:
					// catchAll节点在路径末尾
					// save param value
					if cap(value.params) < int(n.maxParams) {
						value.params = make(Params, 0, n.maxParams)
					}
					i := len(value.params)
					value.params = value.params[:i+1] // expand slice within preallocated capacity
					value.params[i].Key = n.path[2:]
					if unescape {
						var err error
						if value.params[i].Value, err = url.QueryUnescape(path); err != nil {
							value.params[i].Value = path // fallback, in case of error
						}
					} else {
						value.params[i].Value = path
					}
					value.handlers = n.handlers
					value.fullPath = n.fullPath
					return

				default:
					panic("invalid node type")
				}
			}
		} else if path == n.path {
			// 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 path == "/" && n.wildChild && n.nType != root {
				value.tsr = true
				return
			}

			// No handle found. Check if a handle for this path + a
			// trailing slash exists for trailing slash recommendation
			for i := 0; i < len(n.indices); i++ {
				if n.indices[i] == '/' {
					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(n.path) == len(path)+1 && n.path[len(path)] == '/' &&
				path == n.path[:len(n.path)-1] && n.handlers != nil)
		return
	}
}

二 路由的注册

路由的注册主要离不开Engine，通过路由的handle方法来注册路由。

func (group *RouterGroup) handle(httpMethod, relativePath string, handlers HandlersChain) IRoutes {
......
// 将这个route加入到engine.tree
    group.engine.addRoute(httpMethod, absolutePath, handlers)
}

func (engine *Engine) addRoute(method, path string, handlers HandlersChain) {
......
 root.addRoute(path, handlers)
}

三 查找路由

// Engine 会为每一类请求方法（get,post,put)生成一颗路由树，查找路由总体来说就是找到对应的路由树，然后根据路径层层查找。
func (engine *Engine) handleHTTPRequest(c *Context) {
}

参考：gin 源码分析
git源码
路由基树
Go高级编程