Golang httprouter 源碼閱讀

一、httprouter特點介紹

• 輕量、高性能的route框架
• 顯示匹配
• 不關注請求路徑尾部 \
• 路徑自動矯正
• 支持url參數
• 零字節垃圾
• 性能優越
• 不會服務器崩潰
• 完美的API支持

二、httprouter如何工作

此路由器依賴大量使用公共前綴的樹形結構，它是基於壓縮前綴樹或者叫基數樹。有共同父元素的節點有相同前綴。以下是GET請求方法樹結構的樣子：

Priority   Path             Handle
9          \                *<1>
3          ├s               nil
2          |├earch\         *<2>
1          |└upport\        *<3>
2          ├blog\           *<4>
1          |    └:post      nil
1          |         └\     *<5>
2          ├about-us\       *<6>
1          |        └team\  *<7>
1          └contact\        *<8>

// 這個圖相當於註冊了下面這幾個路由
GET("/search/", func1)
GET("/support/", func2)
GET("/blog/:post/", func3)
GET("/about-us/", func4)
GET("/about-us/team/", func5)
GET("/contact/", func6)

每個* 代表一個handler function的內存地址。如果你跟蹤這顆樹的根節點到葉子節點，你會得到完整的路由路徑，例如：\blog:post\，在這裏:post只是一個佔位符，它實際上是一個文章的名稱。不像hash-map，這種樹形結構允許我們使用動態參數例如:post，因爲httprouter是直接與請求路徑匹配而不是匹配路徑的哈希值。在benchmarks的測試中展現出httprouter非常高效。

因爲url路徑是分層結構，並且使用的字符集是有限的，所以它們很可能有很多公共的前綴。這樣就可以使我們減少路由到更小的問題中。而且此路由器還對每種請求方法都有一顆樹。首先它比每個節點都保存handle要更節省空間，並且在前綴樹開始查詢會較少很多問題。

爲了更好的伸縮性，在每個樹層級上，子節點都通過優先級排序，這裏的優先級是註冊在此節點的handle的數量（子，孫等等往下的節點）：

1. 有最多路由路徑的節點先被搜索。這樣可以幫助儘可能快的搜索到handle。
2. 這比較像成本補償，最長可達路徑總是優先被搜索。以下是可視化的樹形結構，節點的搜索順序爲從上到下，從左到右。

   ├------------
   ├---------
   ├-----
   ├----
   ├--
   ├--
   └-
   

三、httprouter如何初始化（構造樹結構）

route框架最重要就是兩點，一是如何初始化，二是用戶請求來後如何分發（其他比如中間件也是一些重要的點）。
先從官方的server demo看如何初始化：

package main

import (
    "fmt"
    "github.com/julienschmidt/httprouter"
    "net/http"
    "log"
)

func Index(w http.ResponseWriter, r *http.Request, _ httprouter.Params) {
    fmt.Fprint(w, "Welcome!\n")
}

func Hello(w http.ResponseWriter, r *http.Request, ps httprouter.Params) {
    fmt.Fprintf(w, "hello, %s!\n", ps.ByName("name"))
}

func main() {
    router := httprouter.New()
    router.GET("/", Index)
    router.GET("/hello/:name", Hello)

    log.Fatal(http.ListenAndServe(":8080", router))
}

這裏從httprouter.New()跟蹤進去可以發現兩個重要的struct，一個是Router，一個是node。
先看一下Router

// Router 是一個 http.Handler 可以通過定義的路由將請求分發給不同的函數
type Router struct {
    trees map[string]*node

    // 這個參數是否自動處理當訪問路徑最後帶的 /，一般爲 true 就行。
    // 例如： 當訪問 /foo/ 時， 此時沒有定義 /foo/ 這個路由，但是定義了 
    // /foo 這個路由，就對自動將 /foo/ 重定向到 /foo (GET 請求
    // 是 http 301 重定向，其他方式的請求是 http 307 重定向）。
    RedirectTrailingSlash bool

    // 是否自動修正路徑， 如果路由沒有找到時，Router 會自動嘗試修復。
    // 首先刪除多餘的路徑，像 ../ 或者 // 會被刪除。
    // 然後將清理過的路徑再不區分大小寫查找，如果能夠找到對應的路由， 將請求重定向到
    // 這個路由上 ( GET 是 301， 其他是 307 ) 。
    RedirectFixedPath bool

    // 用來配合下面的 MethodNotAllowed 參數。 
    HandleMethodNotAllowed bool

    // 如果爲 true ，會自動回覆 OPTIONS 方式的請求。
    // 如果自定義了 OPTIONS 路由，會使用自定義的路由，優先級高於這個自動回覆。
    HandleOPTIONS bool

    // 路由沒有匹配上時調用這個 handler 。
    // 如果沒有定義這個 handler ，就會返回標準庫中的 http.NotFound 。
    NotFound http.Handler

    // 當一個請求是不被允許的，並且上面的 HandleMethodNotAllowed 設置爲 ture 的時候，
    // 如果這個參數沒有設置，將使用狀態爲 with http.StatusMethodNotAllowed 的 http.Error
    // 在 handler 被調用以前，爲允許請求的方法設置 "Allow" header 。
    MethodNotAllowed http.Handler

    // 當出現 panic 的時候，通過這個函數來恢復。會返回一個錯誤碼爲 500 的 http error 
    // (Internal Server Error) ，這個函數是用來保證出現 painc 服務器不會崩潰。
    PanicHandler func(http.ResponseWriter, *http.Request, interface{})
}

再看node

type node struct {
    // 當前節點的 URL 路徑
    // 如上面圖中的例子的首先這裏是一個 /
    // 然後 children 中會有 path 爲 [s, blog ...] 等的節點 
    // 然後 s 還有 children node [earch,upport] 等，就不再說明了
    path      string

    // 判斷當前節點路徑是不是含有參數的節點, 上圖中的 :post 的上級 blog 就是wildChild節點
    wildChild bool

    // 節點類型: static, root, param, catchAll
    // static: 靜態節點, 如上圖中的父節點 s （不包含 handler 的)
    // root: 如果插入的節點是第一個, 那麼是root節點
    // catchAll: 有*匹配的節點
    // param: 參數節點，比如上圖中的 :post 節點
    nType     nodeType

    // path 中的參數最大數量，最大隻能保存 255 個（超過這個的情況貌似太難見到了）
    // 這裏是一個非負的 8 進制數字，最大也只能是 255 了
    maxParams uint8

    // 和下面的 children 對應，保留的子節點的第一個字符
    // 如上圖中的 s 節點，這裏保存的就是 eu （earch 和 upport）的首字母 
    indices   string

    // 當前節點的所有直接子節點
    children  []*node

    // 當前節點對應的 handler
    handle    Handle

    // 優先級，查找的時候會用到,表示當前節點加上所有子節點的數目
    priority  uint32
}

從httprouter.New()方法進入可以看到

func (r *Router) GET(path string, handle Handle) {
	r.Handle("GET", path, handle)
}

func (r *Router) Handle(method, path string, handle Handle) {
	if path[0] != '/' {
		panic("path must begin with '/' in path '" + path + "'")
	}

	if r.trees == nil {
		r.trees = make(map[string]*node)
	}

	// 從這裏可以看出每種http方法（也可以是自定義的方法）都在同一顆樹，作爲不同根節點。
	root := r.trees[method]
	if root == nil {
		// 初始化各個方法的根節點
		root = new(node)
		r.trees[method] = root
	}
	// addRoute方法是把handle添加到路徑對應的節點上
	root.addRoute(path, handle)
}

接着看addRoute

func (n *node) addRoute(path string, handle Handle) {
	fullPath := path
	n.priority++
	numParams := countParams(path)

	// 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 ':' 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
			if i < len(n.path) {
				child := node{
					path:      n.path[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
			}

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

				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)] &&
						// 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
						if n.nType == catchAll {
							pathSeg = path
						} else {
							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 {
					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] {
						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,
					}
					n.children = append(n.children, child)
					n.incrementChildPrio(len(n.indices) - 1)
					n = child
				}
				n.insertChild(numParams, path, fullPath, handle)
				return

			} else if i == len(path) { // Make node a (in-path) leaf
				if n.handle != nil {
					panic("a handle is already registered for path '" + fullPath + "'")
				}
				n.handle = handle
			}
			return
		}
	} else { // Empty tree
		n.insertChild(numParams, path, fullPath, handle)
		n.nType = root
	}
}