路由调用逻辑
gin 对外宣传的高效，很大一部分是说其路由效率。本文内容包括：
- 路由API介绍
- 路由调用实现逻辑
- 路由的内部实现
## 路由API
### 设置路由
```
// routergroup.go:20
type IRoutes interface {
Use(handlers ...HandlerFunc) IRoutes
Handle(httpMethod, relativePath string, handlers ...HandlerFunc) IRoutes
Any(relativePath string, handlers ...HandlerFunc) IRoutes
GET(relativePath string, handlers ...HandlerFunc) IRoutes
POST(relativePath string, handlers ...HandlerFunc) IRoutes
DELETE(relativePath string, handlers ...HandlerFunc) IRoutes
PATCH(relativePath string, handlers ...HandlerFunc) IRoutes
PUT(relativePath string, handlers ...HandlerFunc) IRoutes
OPTIONS(relativePath string, handlers ...HandlerFunc) IRoutes
HEAD(relativePath string, handlers ...HandlerFunc) IRoutes
StaticFile(relativePath, filepath string) IRoutes
Static(relativePath, root string) IRoutes
StaticFS(relativePath string, fs http.FileSystem) IRoutes
}
// routergroup.go:15
type IRouter interface {
IRoutes
Group(string, ...HandlerFunc) *RouterGroup
}
```
### RouteGroup的获取
- Engine嵌入了RouteGroup，它本身就实现了IRoutes接口，gin.New() 和 gin.Default() 可以得到Engine对象
- Engine.Group(relativePath string, handlers ...HandlerFunc)可以得到一个新的RouteGroup
### 路由的命中
初始化时将 `gin.go:handleHTTPRequest` 设置为http请求的处理者，它会将请求进行预处理后去处查找命中的处理者（列表），然后去执行。
这个是调用逻辑，我们讲具体实现。
## 路由的调用逻辑
### 背景知识
我们先看 `Engine` 结构体和路由有关的字段
```
gin.go:50
type Engine struct {
RouterGroup
// 如果true，当前路由匹配失败但将路径最后的 / 去掉时匹配成功时自动匹配后者
// 比如：请求是 /foo/ 但没有命中，而存在 /foo，
// 对get method请求，客户端会被301重定向到 /foo
// 对于其他method请求，客户端会被307重定向到 /foo
RedirectTrailingSlash bool
// 如果true，在没有处理者被注册来处理当前请求时router将尝试修复当前请求路径
// 逻辑为：
// - 移除前面的 ../ 或者 //
// - 对新的路径进行大小写不敏感的查询
// 如果找到了处理者，请求会被301或307重定向
// 比如： /FOO 和 /..//FOO 会被重定向到 /foo
// RedirectTrailingSlash 参数和这个参数独立
RedirectFixedPath bool
// 如果true，当路由没有被命中时，去检查是否有其他method命中
// 如果命中，响应405 （Method Not Allowed）
// 如果没有命中，请求将由 NotFound handler 来处理
HandleMethodNotAllowed bool
// 如果true， url.RawPath 会被用来查找参数
UseRawPath bool
// 如果true， path value 会被保留
// 如果 UseRawPath是false(默认)，UnescapePathValues为true
// url.Path会被保留并使用
UnescapePathValues bool
allNoRoute HandlersChain
allNoMethod HandlersChain
noRoute HandlersChain
noMethod HandlersChain
//每个http method对应一棵树
trees methodTrees
}
// gin.go:30
type HandlerFunc func(*Context)
type HandlersChain []HandlerFunc
// routergroup.go:40
type RouterGroup struct {
// 这个路由会参与处理的函数列表
Handlers HandlersChain
basePath string
// 单例存在
engine *Engine
// 是否是根
root bool
}
```
### 添加路由
```
// routergroup.go:70
func (group *RouterGroup) handle(httpMethod, relativePath string, handlers HandlersChain) IRoutes {
// 将basePath和relativePath加起来得到最终的路径
absolutePath := group.calculateAbsolutePath(relativePath)
// 将现有的 Handlers 和 handlers合并起来
handlers = group.combineHandlers(handlers)
// 将这个route加入到engine.tree
group.engine.addRoute(httpMethod, absolutePath, handlers)
// 返回
return group.returnObj()
}
```
上面的 `addRoute()` 的实现：
```
func (engine *Engine) addRoute(method, path string, handlers HandlersChain) {
// 常规检查
assert1(path[0] == '/', "path must begin with '/'")
assert1(method != "", "HTTP method can not be empty")
assert1(len(handlers) > 0, "there must be at least one handler")
debugPrintRoute(method, path, handlers)
// 维护engine.trees
root := engine.trees.get(method)
if root == nil {
root = new(node)
engine.trees = append(engine.trees, methodTree{method: method, root: root})
}
// 核心，后面一起来讲
root.addRoute(path, handlers)
}
```
### 查找路由
我们看看路由查找逻辑：
```
gin.go:340
func (engine *Engine) handleHTTPRequest(c *Context) {
httpMethod := c.Request.Method
path := c.Request.URL.Path
unescape := false
// 看是否使用 RawPath
if engine.UseRawPath && len(c.Request.URL.RawPath) > 0 {
path = c.Request.URL.RawPath
unescape = engine.UnescapePathValues
}
t := engine.trees
// 根据 http method 得到目标树
for i, tl := 0, len(t); i < tl; i++ {
if t[i].method == httpMethod {
// 目标树找到了，为本次请求路由树的根节点
root := t[i].root
// 根据path查找节点
// 核心，后面来讲
handlers, params, tsr := root.getValue(path, c.Params, unescape)
if handlers != nil {
c.handlers = handlers
c.Params = params
c.Next()
c.writermem.WriteHeaderNow()
return
}
if httpMethod != "CONNECT" && path != "/" {
// 如果 trailing slash redirect，就重定向出去
if tsr && engine.RedirectTrailingSlash {
redirectTrailingSlash(c)
return
}
// fix path
if engine.RedirectFixedPath && redirectFixedPath(c, root, engine.RedirectFixedPath) {
return
}
}
// 没找到
break
}
}
// 如果是因为HTTP method有误，回复这个
if engine.HandleMethodNotAllowed {
for _, tree := range engine.trees {
if tree.method != httpMethod {
if handlers, _, _ := tree.root.getValue(path, nil, unescape); handlers != nil {
c.handlers = engine.allNoMethod
serveError(c, 405, default405Body)
return
}
}
}
}
// 交给 NotRoute （404）
c.handlers = engine.allNoRoute
serveError(c, 404, default404Body)
}
```
