一步一步分析Gin框架路由原始碼及radix tree基數樹

九卷發表於2022-03-06

Gin 簡介

Gin is a HTTP web framework written in Go (Golang). It features a Martini-like API with much better performance -- up to 40 times faster. If you need smashing performance, get yourself some Gin.

-- 這是來自 github 上 Gin 的簡介

Gin 是一個用 Go 寫的 HTTP web 框架，它是一個類似於 Martini 框架，但是 Gin 用了 httprouter 這個路由，它比 martini 快了 40 倍。如果你追求高效能，那麼 Gin 適合。

當然 Gin 還有其它的一些特性：

路由效能高
支援中介軟體
路由組
JSON 驗證
錯誤管理
可擴充套件性

Gin 文件：

Gin 快速入門 Demo

我以前也寫過一些關於 Gin 應用入門的 demo，在這裡。

Gin v1.7.0 , Go 1.16.11

官方的一個 quickstart：

package main

import "github.com/gin-gonic/gin"

// https://gin-gonic.com/docs/quickstart/
func main() {
	r := gin.Default()
	r.GET("/ping", func(c *gin.Context) {
		c.JSON(200, gin.H{
			"message": "pong",
		})
	})

	r.Run() // 監聽在預設埠8080， 0.0.0.0:8080
}

上面就完成了一個可執行的 Gin 程式了。

分析上面的 Demo

第一步：gin.Default()

Engine struct 是 Gin 框架裡最重要的一個結構體，包含了 Gin 框架要使用的許多欄位，比如路由(組)，配置選項，HTML等等。

New() 和 Default() 這兩個函式都是初始化 Engine 結構體。

RouterGroup struct 是 Gin 路由相關的結構體，路由相關操作都與這個結構體有關。

A. Default() 函式

這個函式在 gin.go/Default()，它例項化一個 Engine，呼叫 New() 函式:

// https://github.com/gin-gonic/gin/blob/v1.7.0/gin.go#L180

// 例項化 Engine，預設帶上 Logger 和 Recovery 2 箇中介軟體，它是呼叫 New()
// Default returns an Engine instance with the Logger and Recovery middleware already attached.
func Default() *Engine {
	debugPrintWARNINGDefault() // debug 程式
    engine := New() // 新建 Engine 例項，原來 Default() 函式是最終是呼叫 New() 新建 engine 例項
	engine.Use(Logger(), Recovery()) // 使用一些中介軟體
	return engine
}

Engine 又是什麼？

B. Engine struct 是什麼和 New() 函式:

gin.go/Engine:

Engine 是一個 struct 型別，裡面包含了很多欄位，下面程式碼只顯示主要欄位：

// https://github.com/gin-gonic/gin/blob/v1.7.0/gin.go#L57

// gin 中最大的一個結構體，儲存了路由，設定選項和中介軟體
// 呼叫 New() 或 Default() 方法例項化 Engine struct
// Engine is the framework's instance, it contains the muxer, middleware and configuration settings.
// Create an instance of Engine, by using New() or Default()
type Engine struct {
    RouterGroup // 組路由(路由相關欄位)
    
    ... ...

	HTMLRender       render.HTMLRender
	FuncMap          template.FuncMap
	allNoRoute       HandlersChain
	allNoMethod      HandlersChain
	noRoute          HandlersChain
	noMethod         HandlersChain
	pool             sync.Pool
	trees            methodTrees
	maxParams        uint16
	trustedCIDRs     []*net.IPNet
}

type HandlersChain []HandlerFunc

gin.go/New() 例項化 gin.go/Engine struct，簡化的程式碼如下：

這個 New 函式，就是初始化 Engine struct，

// https://github.com/gin-gonic/gin/blob/v1.7.0/gin.go#L148

// 初始化 Engine，例項化一個 engine
// New returns a new blank Engine instance without any middleware attached.
// By default the configuration is:
// - RedirectTrailingSlash:  true
// - RedirectFixedPath:      false
// - HandleMethodNotAllowed: false
// - ForwardedByClientIP:    true
// - UseRawPath:             false
// - UnescapePathValues:     true
func New() *Engine {
	debugPrintWARNINGNew()
	engine := &Engine{
		RouterGroup: RouterGroup{
			Handlers: nil,
			basePath: "/",
			root:     true,
		},
		FuncMap:                template.FuncMap{},
		... ...
		trees:                  make(methodTrees, 0, 9),
		delims:                 render.Delims{Left: "{{", Right: "}}"},
		secureJSONPrefix:       "while(1);",
	}
	engine.RouterGroup.engine = engine // RouterGroup 裡的 engine 在這裡賦值，下面分析 RouterGroup 結構體
	engine.pool.New = func() interface{} {
		return engine.allocateContext()
	}
	return engine
}

C. RouterGroup

gin.go/Engine struct 裡的 routergroup.go/RouterGroup struct 這個與路由有關的欄位，它也是一個結構體，程式碼如下：

//https://github.com/gin-gonic/gin/blob/v1.7.0/routergroup.go#L41
// 配置儲存路由
// 路由後的處理函式handlers(中介軟體)
// RouterGroup is used internally to configure router, a RouterGroup is associated with
// a prefix and an array of handlers (middleware).
type RouterGroup struct {
	Handlers HandlersChain // 儲存處理路由
	basePath string
	engine   *Engine  // engine
	root     bool
}

// https://github.com/gin-gonic/gin/blob/v1.7.0/gin.go#L34
type HandlersChain []HandlerFunc

https://github.com/gin-gonic/gin/blob/v1.7.0/gin.go#L31
// HandlerFunc defines the handler used by gin middleware as return value.
type HandlerFunc func(*Context)

第二步：r.GET()

r.GET() 就是路由註冊和路由處理handler。

routergroup.go/GET()，handle() -> engine.go/addRoute()

// https://github.com/gin-gonic/gin/blob/v1.7.0/routergroup.go#L102
// GET is a shortcut for router.Handle("GET", path, handle).
func (group *RouterGroup) GET(relativePath string, handlers ...HandlerFunc) IRoutes {
	return group.handle(http.MethodGet, relativePath, handlers)
}

handle 處理函式：

// https://github.com/gin-gonic/gin/blob/v1.7.0/routergroup.go#L72
func (group *RouterGroup) handle(httpMethod, relativePath string, handlers HandlersChain) IRoutes {
	absolutePath := group.calculateAbsolutePath(relativePath)
	handlers = group.combineHandlers(handlers)
	group.engine.addRoute(httpMethod, absolutePath, handlers)
	return group.returnObj()
}

combineHandlers() 函式把所有路由處理handler合併起來。

addRoute() 這個函式把方法，URI，處理handler 加入進來，這個函式主要程式碼如下：

// https://github.com/gin-gonic/gin/blob/v1.7.0/gin.go#L276

func (engine *Engine) addRoute(method, path string, handlers HandlersChain) {
	... ...
    
    // 每一個http method(GET, POST, PUT...)都構建一顆基數樹
    root := engine.trees.get(method) // 獲取方法對應的基數樹
    if root == nil { // 如果沒有就建立一顆新樹
        root = new(node) // 建立基數樹的根節點
        root.fullPath = "/"
        engine.trees = append(engine.trees, methodTree{method: method, root: root})
    }
    root.addRoute(path, handlers)
    
    ... ...
}

上面這個root.addRoute函式在 tree.go 裡，而這裡的程式碼多數來自 httprouter 這個路由庫。

gin 裡號稱 40 times faster。

到底是怎麼做到的？

httprouter 路由資料結構Radix Tree

httprouter文件

在 httprouter 文件裡，有這樣一句話：

The router relies on a tree structure which makes heavy use of common prefixes, it is basically a compact prefix tree (or just Radix tree)

用了 prefix tree 字首樹或 Radix tree 基數樹。與 Trie 字典樹有關。

Radix Tree 叫基數特里樹或壓縮字首樹，是一種更節省空間的 Trie 樹。

Trie 字典樹

Trie，被稱為字首樹或字典樹，是一種有序樹，其中的鍵通常是單詞和字串，所以又有人叫它單詞查詢樹。

它是一顆多叉樹，即每個節點分支數量可能為多個，根節點不包含字串。

從根節點到某一節點，路徑上經過的字元連線起來，為該節點對應的字串。

除根節點外，每一個節點只包含一個字元。

每個節點的所有子節點包含的字元都不相同。

優點：利用字串公共字首來減少查詢時間，減少無謂的字串比較

Trie 樹圖示：

(為 b，abc，abd，bcd，abcd，efg，hii 這7個單詞建立的trie樹， https://baike.baidu.com/item/字典樹/9825209)

trie 樹的程式碼實現：https://baike.baidu.com/item/字典樹/9825209#5

Radix Tree基數樹

認識基數樹：

Radix Tree，基數特里樹或壓縮字首樹，是一種更節省空間的 Trie 樹。它對 trie 樹進行了壓縮。

看看是咋壓縮的，假如有下面一組資料 key-val 集合：

{
"def": "redisio", 
"dcig":"mysqlio", 
"dfo":"linux", 
"dfks":"tdb", 
"dfkz":"dogdb",
}

用上面資料中的 key 構造一顆 trie 樹：

現在壓縮 trie 樹(Compressed Trie Tree)中的唯一子節點，就可以構建一顆 radix tree 基數樹。

父節點下第一級子節點數小於 2 的都可以進行壓縮，把子節點合併到父節點上，把上圖 <2 子節點數壓縮，變成如下圖：

把 c，f 和 c，i，g 壓縮在一起，這樣就節省了一些空間。壓縮之後，分支高度也降低了。

這個就是對 trie tree 進行壓縮變成 radix tree。

在另外看一張出現次數比較多的 Radix Tree 的圖：

(圖Radix_tree 來自：https://en.wikipedia.org/wiki/Radix_tree)

基數樹唯一子節點都與其父節點合併，邊沿(edges)既可以儲存多個元素序列也可以儲存單個元素。比如上圖的 r, om，an，e。

基數樹的圖最下面的數字對應上圖的排序數字，比如，就是 ruber 字元，。

什麼時候使用基數樹合適：

字串元素個數不是很多，且有很多相同字首時適合使用基數樹這種資料結構。

基數樹的應用場景：

httprouter 中的路由器。

使用 radix tree 來構建 key 為字串的關聯陣列。

很多構建 IP 路由也用到了 radix tree，比如 linux 中，因為 ip 通常有大量相同字首。

Redis 叢集模式下儲存 slot 對應的所有 key 資訊，也用到了 radix tree。檔案 rax.h/rax.c 。

radix tree 在倒排索引方面使用也比較廣。

httprouter中的基數樹

node 節點定義：

// https://github.com/julienschmidt/httprouter/blob/v1.3.0/tree.go#L46
type node struct {
	path      string    // 節點對應的字串路徑
	wildChild bool      // 是否為引數節點，如果是引數節點，那麼 wildChild=true
    nType     nodeType  // 節點型別，有幾個列舉值可以看下面nodeType的定義
	maxParams uint8     // 節點路徑最大引數個數
	priority  uint32    // 節點權重，子節點的handler總數
	indices   string    // 節點與子節點的分裂的第一個字元
	children  []*node   // 子節點
	handle    Handle    // http請求處理方法
}

節點型別 nodeType 定義：

// https://github.com/julienschmidt/httprouter/blob/v1.3.0/tree.go#L39
// 節點型別
const (
    static nodeType = iota // default， 靜態節點，普通匹配(/user)
	root                   // 根節點
    param                 // 引數節點(/user/:id)
    catchAll              // 通用匹配，匹配任意引數(*user)
)

indices 這個欄位是快取下一子節點的第一個字元。

比如路由： r.GET("/user/one"), r.GET("/user/two"), indices 欄位快取的就是下一節點的第一個字元，即 "ot" 2個字元。這個就是對搜尋匹配進行了優化。

如果 wildChild=true，引數節點時，indices=""。

addRoute 新增路由:

addRoute()，新增路由函式，這個函式程式碼比較多，

分為空樹和非空樹時的插入。

空樹時直接插入：

n.insertChild(numParams, path, fullPath, handlers)
n.nType = root // 節點 nType 是 root 型別

非空樹的處理：

先是判斷樹非空（non-empty tree），接著下面是一個 for 迴圈，下面所有的處理都在 for 迴圈面。

更新 maxParams 欄位

尋找共同的最長字首字元

// https://github.com/julienschmidt/httprouter/blob/v1.3.0/tree.go#L100
// Find the longest common prefix. 尋找字元相同字首，用 i 數字表示
// This also implies that the common prefix contains no ':' or '*'，表示沒有包含特殊匹配 : 或 *
// 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 開始分裂節點

比如第一個路由 path 是 user，新增一個路由 uber，u 就是它們共同的部分(common prefix)，那麼就把 u 作為父節點，剩下的 ser，ber 作為它的子節點

// https://github.com/julienschmidt/httprouter/blob/v1.3.0/tree.go#L107
// Split edge
if i < len(n.path) {
    child := node{
        path:      n.path[i:], // 上面已經判斷了匹配的字元共同部分用i表示，[i:] 從i開始計算取字元剩下不同部分作為子節點
        wildChild: n.wildChild, // 節點型別
        nType:     static,      // 靜態節點普通匹配
        indices:   n.indices,
        children:  n.children,
        handle:    n.handle,
        priority:  n.priority - 1, // 節點降級
    }

    // 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.handle = nil
    n.wildChild = false
}

i<len(path)，將新節點作為子節點插入
https://github.com/julienschmidt/httprouter/blob/v1.3.0/tree.go#L137

4.1 n.wildChild = true，對特殊引數節點的處理，: 和 *

  // https://github.com/julienschmidt/httprouter/blob/v1.3.0/tree.go#L133
  if n.wildChild {
    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)] &&
    // Adding a child to a catchAll is not possible
    n.nType != catchAll &&
    // Check for longer wildcard, e.g. :name and :names
    (len(n.path) >= len(path) || path[len(n.path)] == '/') {
        continue walk
    } else {
        // Wildcard conflict
        var pathSeg string
        ... ...
    }
  }

4.2 開始處理 indices

// https://github.com/julienschmidt/httprouter/blob/v1.3.0/tree.go#L171
c := path[0] // 獲取第一個字元

// slash after param，處理nType為引數的情況
if n.nType == param && c == '/' && len(n.children) == 1

// Check if a child with the next path byte exists
// 判斷子節點是否和當前path匹配，用indices欄位來判斷
// 比如 u 的子節點為 ser 和 ber，indices 為 u，如果新插入路由 ubb，那麼就與子節點 ber 有共同部分 b，繼續分裂 ber 節點
for i := 0; i < len(n.indices); i++ {
    if c == n.indices[i] {
        i = n.incrementChildPrio(i)
        n = n.children[i]
        continue walk
    }
}

// Otherwise insert it
// indices 不是引數和通配匹配
if c != ':' && c != '*' {
    // []byte for proper unicode char conversion, see #65
    n.indices += string([]byte{c})
    child := &node{
        maxParams: numParams,
    }
    // 新增子節點
    n.children = append(n.children, child)
    n.incrementChildPrio(len(n.indices) - 1)
    n = child
}
n.insertChild(numParams, path, fullPath, handle)

i=len(path)路徑相同

如果已經有handler處理函式就報錯，沒有就賦值handler

insertChild 插入子節點：

insertChild

getValue 路徑查詢：

getValue

上面2個函式可以獨自分析下 - -!

視覺化radix tree操作

https://www.cs.usfca.edu/~galles/visualization/RadixTree.html

radix tree 的演算法操作可以看這裡，動態展示。

參考

https://github.com/gin-gonic/gin/tree/v1.7.0 gin 原始碼
https://github.com/julienschmidt/httprouter httprouter地址
https://github.com/julienschmidt/httprouter/blob/v1.3.0/tree.go httprouter tree原始碼
https://gin-gonic.com/docs/quickstart/ gin doc
https://www.cs.usfca.edu/~galles/visualization/RadixTree.html radix tree演算法步驟視覺化
https://baike.baidu.com/item/字典樹/9825209 百科基數樹
《演算法》 5.2 單詞查詢樹 trie tree 作者： Robert Sedgewick / Kevin Wayne
https://en.wikipedia.org/wiki/Trie 維基trie樹(en)
https://en.wikipedia.org/wiki/Radix_tree 維基radix tree(en)
https://zh.wikipedia.org/wiki/基數樹維基基數樹(zh)
https://github.com/redis/redis/blob/6.0.14/src/rax.c redis 中 radix tree 使用
https://github.com/redis/redis/blob/6.0.14/src/rax.h redis 中 radix tree 使用

一步一步分析Redux原始碼?
2018-04-16
Redux原始碼
Redis radix tree原始碼解析
2019-04-19
Redis原始碼
Nginx 原始碼完全剖析（10）ngx_radix_tree
2012-10-12
Nginx原始碼
通過原始碼一步一步分析 ArrayList 擴容機制
2020-10-07
原始碼
我們來一步一步分析koa2的原始碼?
2018-04-02
原始碼
Java集合原始碼分析之基礎（六）：紅黑樹（RB Tree）
2018-08-13
Java原始碼
Java集合原始碼分析之基礎（五）：平衡二叉樹（AVL Tree）
2019-03-01
Java原始碼二叉樹
httprouter框架 (Gin使用的路由框架)
2016-11-08
HTTP框架路由
HashMap實現原理一步一步分析(1-put方法原始碼整體過程)
2021-05-10
HashMap原始碼
一步一步帶你瞭解EventBus3.1.1 原始碼
2018-07-20
S3原始碼
【面試必備】透過原始碼角度一步一步帶你分析 ArrayList 擴容機制
2019-01-19
面試原始碼
gin框架post路由的使用
2018-10-27
框架路由
一步一步分析vue之observe
2019-02-28
Vue
Gin使用及原始碼簡析
2023-03-11
原始碼
一步一步分析vue之$mount(1)
2019-02-25
Vue
Gin 框架 - 安裝和路由配置
2019-07-17
框架路由
【React Native】從原始碼一步一步解析它的實現原理
2017-05-05
React Native原始碼
美團外賣開源路由框架 WMRouter 原始碼分析
2019-03-01
路由框架原始碼
一步一步分析vue之_data屬性
2017-12-11
Vue
一步步解析jQuery原始碼
2018-12-24
jQuery原始碼
ARouter路由框架原始碼解析
2018-08-14
路由框架原始碼
Laravel 路由原始碼分析
2019-02-27
Laravel路由原始碼
express原始碼分析-路由
2019-04-17
Express原始碼路由
從原始碼角度一步步分析AsyncTask的用法與原理
2016-10-08
原始碼
一步一步使用ABP框架搭建正式專案系列教程
2015-09-30
框架
帶你一步一步手撕Spring MVC原始碼加手繪流程圖
2019-10-13
SpringMVC原始碼流程圖
原始碼分析：同步基礎框架——AbstractQueuedSynchronizer(AQS)
2020-11-17
原始碼框架AQS
帶你一步一步手撕 Mybatis 原始碼加手繪流程圖——執行部分
2019-11-03
MyBatis原始碼流程圖
一步一步實現直播軟體原始碼的RTMP推流流媒體服務
2020-09-22
原始碼
Gin框架介紹及使用
2022-09-23
框架
Laravel 路由管道原始碼分析
2018-12-25
Laravel路由原始碼
一步步構建 iOS 路由
2016-12-24
iOS路由
go的web框架gin的使用（七）：多路由
2020-04-05
GoWeb框架路由
面試被問懵？帶你一步一步深入Handler原始碼，不信還拿不下面試官？
2020-01-10
面試原始碼
一步一步帶你封裝基於react的modal元件
2018-09-22
封裝React元件
Laravel Route(路由)匹配原始碼分析
2023-08-29
Laravel路由原始碼
一步一步搭建Flutter開發架子-國際化，路由，本地化，響應式
2021-03-01
Flutter路由
Rxjava 2.x 原始碼系列 - 基礎框架分析
2019-04-26
RxJava原始碼框架