【服务计算】gorilla/mux源码分析

目录

gorilla/mux与http.SeverMux
gorilla/mux的主要特点
使用实例
源码分析

1. mux.go
2. route.go

总结
参考资料

gorilla/mux与http.SeverMux

golang自带的http.SeverMux路由实现简单,本质是一个map[string]Handler,是请求路径与该路径对应的处理函数的映射关系。实现简单功能也比较单一：

1. 不支持正则路由， 这个是比较致命的
2. 只支持路径匹配，不支持按照Method，header，host等信息匹配，所以也就没法实现RESTful架构

而gorilla/mux是一个强大的路由，小巧但是稳定高效，不仅可以支持正则路由还可以按照Method，header，host等信息匹配，可以从我们设定的路由表达式中提取出参数方便上层应用，而且完全兼容http.ServerMux

---

gorilla/mux的主要特点

• 实现了http.Handler接口，因此可以兼容标准的http.ServeMux。
• 可以匹配URL 主机，路径，路径前缀，头部，查询值，HTTP方法或用户自定义的匹配。
• URL 主机、路径、查询值可以使用正则表达式匹配。
• 可以使用子路由。只有当父路由匹配成功后，子路由才会进行匹配。这种嵌套的路由可以加快匹配速度。

---

使用实例

package main

import (
    "net/http"
    "log"
    "github.com/gorilla/mux"
)

func YourHandler(w http.ResponseWriter, r *http.Request) {
    w.Write([]byte("Gorilla!\n"))
}

func main() {
    r := mux.NewRouter()
    // Routes consist of a path and a handler function.
    r.HandleFunc("/", YourHandler)

    // Bind to a port and pass our router in
    log.Fatal(http.ListenAndServe(":8000", r))
}

---

源码分析

主要是四个模块：mux.go，route.go，middleware.go，regexp.go，其中，middleware.go是中间件的相关定义，regexp.go是正则处理的相关定义。我们主要分析mux.go和route.go。

---

1 mux.go

mux是整个模块的入口。

---

NewRouter创建router实例：

// NewRouter returns a new router instance.
func NewRouter() *Router {
	return &Router{namedRoutes: make(map[string]*Route), KeepContext: false}
}

我们看看router的数据结构：

type Router struct {
	// Configurable Handler to be used when no route matches.
	NotFoundHandler http.Handler

	// Configurable Handler to be used when the request method does not match the route.
	MethodNotAllowedHandler http.Handler

	// Parent route, if this is a subrouter.
	parent parentRoute
	// Routes to be matched, in order.
	routes []*Route
	// Routes by name for URL building.
	namedRoutes map[string]*Route
	// See Router.StrictSlash(). This defines the flag for new routes.
	strictSlash bool
	// See Router.SkipClean(). This defines the flag for new routes.
	skipClean bool
	// If true, do not clear the request context after handling the request.
	// This has no effect when go1.7+ is used, since the context is stored
	// on the request itself.
	KeepContext bool
	// see Router.UseEncodedPath(). This defines a flag for all routes.
	useEncodedPath bool
	// Slice of middlewares to be called after a match is found
	middlewares []middleware
}

主要关注 routes 、parent 以及三个 flag：strictSlash、skipClean、useEncodedPath。

路由信息存放在routes中；如果只关心流程，可以先忽略这些flag。

strictSlash

// StrictSlash defines the trailing slash behavior for new routes. The initial
// value is false.
//
// When true, if the route path is "/path/", accessing "/path" will perform a redirect
// to the former and vice versa. In other words, your application will always
// see the path as specified in the route.
//
// When false, if the route path is "/path", accessing "/path/" will not match
// this route and vice versa.
//
// The re-direct is a HTTP 301 (Moved Permanently). Note that when this is set for
// routes with a non-idempotent method (e.g. POST, PUT), the subsequent re-directed
// request will be made as a GET by most clients. Use middleware or client settings
// to modify this behaviour as needed.
//
// Special case: when a route sets a path prefix using the PathPrefix() method,
// strict slash is ignored for that route because the redirect behavior can't
// be determined from a prefix alone. However, any subrouters created from that
// route inherit the original StrictSlash setting.
func (r *Router) StrictSlash(value bool) *Router {
	r.strictSlash = value
	return r
}

按照上面的英文注释，可以看到StrictSlash定义了一种对于斜杠的行为:

• true：当path为“/path/”时，访问“/path”的时候会被重定向到“/path/”。就是说程序的是路由中指定的路径

• false：当path为“/path”时，访问“/path/”的时候将不会被此路由匹配。

• 特殊情况：当路由设置了PathPrefix方法时，此路由将忽略此flag。

---

SkipClean

// SkipClean defines the path cleaning behaviour for new routes. The initial
// value is false. Users should be careful about which routes are not cleaned
//
// When true, if the route path is "/path//to", it will remain with the double
// slash. This is helpful if you have a route like: /fetch/http://xkcd.com/534/
//
// When false, the path will be cleaned, so /fetch/http://xkcd.com/534/ will
// become /fetch/http/xkcd.com/534
func (r *Router) SkipClean(value bool) *Router {
	r.skipClean = value
	return r
}

按照注释，可以看到SkipClean定义清洗path的行为:

• true：当path为/path//to的时候，将会保留其中的多个斜杠

• false：当path为/fetch/http://xkcd.com/534 将会被清理掉，变成/fetch/http/xkcd.com/534

所以按照自己的需求来设置。

---

UseEncodePath

// UseEncodedPath tells the router to match the encoded original path
// to the routes.
// For eg. "/path/foo%2Fbar/to" will match the path "/path/{var}/to".
//
// If not called, the router will match the unencoded path to the routes.
// For eg. "/path/foo%2Fbar/to" will match the path "/path/foo/bar/to"
func (r *Router) UseEncodedPath() *Router {
	r.useEncodedPath = true
	return r
}

直接看注释的例子吧：

1、 true："/path/foo%2Fbar/to"will match the path “/path/{var}/to”.

2、 False："/path/foo%2Fbar/to"will match the path “/path/foo/bar/to”

---

接着看ServeHTTP：

// ServeHTTP dispatches the handler registered in the matched route.
//
// When there is a match, the route variables can be retrieved calling
// mux.Vars(request).
func (r *Router) ServeHTTP(w http.ResponseWriter, req *http.Request) {
	if !r.skipClean {
		path := req.URL.Path
		if r.useEncodedPath {
			path = req.URL.EscapedPath()
		}
		// Clean path to canonical form and redirect.
		if p := cleanPath(path); p != path {

			// Added 3 lines (Philip Schlump) - It was dropping the query string and #whatever from query.
			// This matches with fix in go 1.2 r.c. 4 for same problem.  Go Issue:
			// http://code.google.com/p/go/issues/detail?id=5252
			url := *req.URL
			url.Path = p
			p = url.String()

			w.Header().Set("Location", p)
			w.WriteHeader(http.StatusMovedPermanently)
			return
		}
	}
	var match RouteMatch
	var handler http.Handler
	if r.Match(req, &match) {
		handler = match.Handler
		req = setVars(req, match.Vars)
		req = setCurrentRoute(req, match.Route)
	}

	if handler == nil && match.MatchErr == ErrMethodMismatch {
		handler = methodNotAllowedHandler()
	}

	if handler == nil {
		handler = http.NotFoundHandler()
	}

	if !r.KeepContext {
		defer contextClear(req)
	}

	handler.ServeHTTP(w, req)
}

首先进行flag处理，接着寻找匹配的路由，然后进入对应匹配路由所对应的handler。

---

我们看看match是如何匹配的：

// Match attempts to match the given request against the router's registered routes.
//
// If the request matches a route of this router or one of its subrouters the Route,
// Handler, and Vars fields of the the match argument are filled and this function
// returns true.
//
// If the request does not match any of this router's or its subrouters' routes
// then this function returns false. If available, a reason for the match failure
// will be filled in the match argument's MatchErr field. If the match failure type
// (eg: not found) has a registered handler, the handler is assigned to the Handler
// field of the match argument.
func (r *Router) Match(req *http.Request, match *RouteMatch) bool {
	for _, route := range r.routes {
		if route.Match(req, match) {
			// Build middleware chain if no error was found
			if match.MatchErr == nil {
				for i := len(r.middlewares) - 1; i >= 0; i-- {
					match.Handler = r.middlewares[i].Middleware(match.Handler)
				}
			}
			return true
		}
	}
...

原来就是遍历 Router 下的所有 route， 一个一个找，直到找到可以匹配上的。

---

下面这两个是最常规的两个构建接口，此外还有针对path，pathprefix，queries，schemes等等的接口。

// Handle registers a new route with a matcher for the URL path.
// See Route.Path() and Route.Handler().
func (r *Router) Handle(path string, handler http.Handler) *Route {
	return r.NewRoute().Path(path).Handler(handler)
}

// HandleFunc registers a new route with a matcher for the URL path.
// See Route.Path() and Route.HandlerFunc().
func (r *Router) HandleFunc(path string, f func(http.ResponseWriter,
	*http.Request)) *Route {
	return r.NewRoute().Path(path).HandlerFunc(f)
}

---

2 route.go

要想知道mux为何强大，还是得看route.go。

---

// Route stores information to match a request and build URLs.
type Route struct {
	// Parent where the route was registered (a Router).
	parent parentRoute
	// Request handler for the route.
	handler http.Handler
	// List of matchers.
	matchers []matcher
	// Manager for the variables from host and path.
	regexp *routeRegexpGroup
	// If true, when the path pattern is "/path/", accessing "/path" will
	// redirect to the former and vice versa.
	strictSlash bool
	// If true, when the path pattern is "/path//to", accessing "/path//to"
	// will not redirect
	skipClean bool
	// If true, "/path/foo%2Fbar/to" will match the path "/path/{var}/to"
	useEncodedPath bool
	// The scheme used when building URLs.
	buildScheme string
	// If true, this route never matches: it is only used to build URLs.
	buildOnly bool
	// The name used to build URLs.
	name string
	// Error resulted from building a route.
	err error

	buildVarsFunc BuildVarsFunc
}

其中最重要的是handler和matchers。当然，还有一个regexp。

结构体里还有一些flag，都是从router中传入的。

---

Match：

// Match matches the route against the request.
func (r *Route) Match(req *http.Request, match *RouteMatch) bool {
	if r.buildOnly || r.err != nil {
		return false
	}

	var matchErr error

	// Match everything.
	for _, m := range r.matchers {
		if matched := m.Match(req, match); !matched {
			if _, ok := m.(methodMatcher); ok {
				matchErr = ErrMethodMismatch
				continue
			}
			matchErr = nil
			return false
		}
	}

	if matchErr != nil {
		match.MatchErr = matchErr
		return false
	}

	if match.MatchErr == ErrMethodMismatch {
		// We found a route which matches request method, clear MatchErr
		match.MatchErr = nil
		// Then override the mis-matched handler
		match.Handler = r.handler
	}

	// Yay, we have a match. Let's collect some info about it.
	if match.Route == nil {
		match.Route = r
	}
	if match.Handler == nil {
		match.Handler = r.handler
	}
	if match.Vars == nil {
		match.Vars = make(map[string]string)
	}

	// Set variables.
	if r.regexp != nil {
		r.regexp.setMatch(req, match, r)
	}
	return true
}

从上面可以看到，buildonly模式的话，不做匹配，只做url生成用。

当我们添加路由限定条件时，就是往matcher数组中增加一个限定函数。 当请求到来时，Route.Match()会遍历matcher数组，只有数组中所有的元素都返回true时则说明此请求满足该路由的限定条件。

下面就是matcher的接口定义以及addMatcher：

// matcher types try to match a request.
type matcher interface {
	Match(*http.Request, *RouteMatch) bool
}

// addMatcher adds a matcher to the route.
func (r *Route) addMatcher(m matcher) *Route {
	if r.err == nil {
		r.matchers = append(r.matchers, m)
	}
	return r
}

---

接着看下handler的赋值接口：

// Handler sets a handler for the route.
func (r *Route) Handler(handler http.Handler) *Route {
	if r.err == nil {
		r.handler = handler
	}
	return r
}

// HandlerFunc sets a handler function for the route.
func (r *Route) HandlerFunc(f func(http.ResponseWriter, *http.Request)) *Route {
	return r.Handler(http.HandlerFunc(f))
}

// GetHandler returns the handler for the route, if any.
func (r *Route) GetHandler() http.Handler {
	return r.handler
}

将handler保存在变量route的handler中。

---

子路由Subrouter：

// Subrouter creates a subrouter for the route.
//
// It will test the inner routes only if the parent route matched. For example:
//
//     r := mux.NewRouter()
//     s := r.Host("www.example.com").Subrouter()
//     s.HandleFunc("/products/", ProductsHandler)
//     s.HandleFunc("/products/{key}", ProductHandler)
//     s.HandleFunc("/articles/{category}/{id:[0-9]+}"), ArticleHandler)
//
// Here, the routes registered in the subrouter won't be tested if the host
// doesn't match.
func (r *Route) Subrouter() *Router {
	router := &Router{parent: r, strictSlash: r.strictSlash}
	r.addMatcher(router)
	return router
}

只有在父路由成功匹配后，才会转发给对应的子路由继续匹配。Router实现了一个Match方法，因此可以作为一个matcher对象加入到matchers中。当请求到达的时，router的ServeHTTP会找到Host注册的一个Route，Route在调用自己的Match方法时会遍历自己的matchers表，如果发现一个可以处理的子路由，就递归式地调用Match方法，直到找到对应的Handle。

---

总结

1. 使用 Router 的 HandleFunc 、Host 、 Methods 、 Schemes 、 Headers 等方法可以创建一个路由，并为其添加相应的 matcher。也可以使用 MatcherFunc 来创建自己的 matcher。

2. 我们可以把代码写成这样的形式来添加matcher：r.NewRoute().Path(path).HandlerFunc(f)

3. 当我们添加路由限定条件时，就是往matcher数组中增加一个限定函数。 当请求到来时，Route.Match()会遍历matcher数组，只有数组中所有的元素都返回true时则说明此请求满足该路由的限定条件。

---

参考资料

Gorilla源码分析之gorilla/mux源码分析
mux源码解读
gorilla/mux类库解析
[服务计算] gorilla/mux源码阅读
服务计算学习之路-开发 web 服务程序
服务计算 | gorilla/mux 源码解析