gorilla/mux 路由实战指南:在 Docker Engine 中掌握 Go 的 HTTP 请求路由与分发

原创2026-10-13 09:55:041,907 阅读
文章标签:容器运行时云原生

gorilla/mux 路由实战指南:在 Docker Engine 中掌握 Go 的 HTTP 请求路由与分发

本文以 docker-ce 仓库中 vendor 的 gorilla/mux 使用文档 为核心,完整讲解 mux 的安装、路由注册、多重匹配器、子路由、URL 反向构建、中间件与 CORS 等全部核心能力,并结合 Docker Engine API 服务器对 mux 的真实调用(如 components/engine/api/server/server.go 中基于 mux 构建的全部 REST 端点)进行源码级印证。读完本文,你既能从零上手 mux,也能理解 Docker 引擎路由层 createMux() 背后的匹配机制。

一、mux 是什么:HTTP 请求路由器与分发器

gorilla/mux 实现了一个请求路由器(router)与分发器(dispatcher),用于将进入的 HTTP 请求匹配到对应的处理函数。mux 是 "HTTP request multiplexer"(HTTP 请求多路复用器)的缩写。与 Go 标准库的 http.ServeMux 类似,mux.Router 将传入请求与一组已注册的路由做匹配,并为匹配到 URL 或其他条件的路由调用对应 handler。

mux 的核心特性(可在 mux.go 源码中逐一验证):

  • 兼容标准库:实现了 http.Handler 接口,可直接作为 http.ServeMux 的替代或嵌套使用。
  • 丰富的匹配维度:可按 URL host、path、path 前缀、scheme、header 值、query 值、HTTP method 匹配请求,也支持自定义匹配函数。
  • 路由变量与正则:URL host、path 与 query 值可以定义变量,并可选地附加正则表达式约束。
  • URL 反向构建:已注册的 URL 可以被 "反转"(reversed)构建出来,方便维护资源引用。
  • 子路由(subrouter):嵌套路由仅当父路由匹配时才被测试,便于为共享相同条件(如 host、path 前缀等)的路由分组,同时优化请求匹配性能。

从源码结构看,包内共 5 个 Go 文件各司其职:mux.go(Router 与上下文)、route.go(Route 及所有 matcher)、regexp.go(模板编译与变量提取)、middleware.go(中间件与 CORS),另有 doc.go 与 test_helpers.go。

二、安装与引入

在配置好 Go 工具链后,通过如下命令安装:

go get -u github.com/gorilla/mux

在 docker-ce 仓库中,mux 并非通过 go module 直接引入,而是作为 vendor 目录下的第三方依赖随 Docker Engine 一起分发(见 components/engine/vendor/github.com/gorilla/mux/)。Docker Engine 在 components/engine/api/server/server.go 中通过 "github.com/gorilla/mux" 导入并使用它。

三、基础用法:注册路径与处理器

先注册一组 URL 路径与对应的处理器:

func main() {
    r := mux.NewRouter()
    r.HandleFunc("/", HomeHandler)
    r.HandleFunc("/products", ProductsHandler)
    r.HandleFunc("/articles", ArticlesHandler)
    http.Handle("/", r)
}

这里注册了三条路径到处理器的映射,工作方式与 http.HandleFunc() 等价:当请求 URL 命中其中某个路径时,对应处理器被调用,并以 (http.ResponseWriter, *http.Request) 作为参数。

从源码看,Router.HandleFunc 实际上是 NewRoute().Path(path).HandlerFunc(f) 的组合调用(见 mux.go)。NewRouter() 内部会初始化 namedRoutes: make(map<a href="https://link.gitcode.com/i/44da9599ed44f986a1c0100fa735515e" target="_blank">string]*Route),用于按名查找路由([mux.go)。

3.1 路径变量

路径可以包含变量,使用 {name} 或 {name:pattern} 格式定义。若未指定正则模式,变量将匹配到下一个斜杠之前的所有内容。例如:

r := mux.NewRouter()
r.HandleFunc("/products/{key}", ProductHandler)
r.HandleFunc("/articles/{category}/", ArticlesCategoryHandler)
r.HandleFunc("/articles/{category}/{id:[0-9]+}", ArticleHandler)

变量名会组成一个路由变量 map,通过 mux.Vars() 获取:

func ArticlesCategoryHandler(w http.ResponseWriter, r *http.Request) {
    vars := mux.Vars(r)
    w.WriteHeader(http.StatusOK)
    fmt.Fprintf(w, "Category: %v\n", vars["category"])
}

默认模式与正则约束的源码依据:在 regexp.go 中,不同位置的变量使用不同的默认正则:

  • path 变量:[^/]+(匹配到下一个斜杠)
  • query 变量:.*
  • host 变量:[^.]+(匹配到下一个点)

同时,模板解析要求变量名与正则都不能为空、变量名不能包含冒号(: 用于分隔名称与正则),且不允许在正则中使用捕获组 (...)——必须写成非捕获组 (?:...)(regexp.go)。mux.Vars() 的底层实现是把变量 map 写入 request context 的 varsKey,再用 r.Context().Value(varsKey) 读出(mux.go)。

四、多种匹配器:把路由限定到更精确的条件

路由可以被限制到特定域名或子域名,host 模式同样支持变量:

r := mux.NewRouter()
// 仅当域名为 "www.example.com" 时匹配
r.Host("www.example.com")
// 匹配动态子域名
r.Host("{subdomain:[a-z]+}.example.com")

除此之外,mux 还提供以下常用匹配器:

匹配器 用途 示例
PathPrefix 匹配路径前缀 r.PathPrefix("/products/")
Methods 匹配 HTTP 方法 r.Methods("GET", "POST")
Schemes 匹配 URL scheme r.Schemes("https")
Headers 匹配请求头键值 r.Headers("X-Requested-With", "XMLHttpRequest")
Queries 匹配 query 键值 r.Queries("key", "value")
MatcherFunc 自定义匹配函数 见下文
HeadersRegexp 用正则匹配请求头 r.HeadersRegexp("Content-Type", "application/(text|json)")

自定义匹配函数的签名是 func(*http.Request, *RouteMatch) bool:

r.MatcherFunc(func(r *http.Request, rm *RouteMatch) bool {
    return r.ProtoMajor == 0
})

组合多个匹配器,同一路由可以同时满足多个条件:

r.HandleFunc("/products", ProductsHandler).
  Host("www.example.com").
  Methods("GET").
  Schemes("http")

实现细节:各匹配器在 route.go 中实现为不同的 matcher 类型(headerMatcher、methodMatcher、schemeMatcher 等),Route 内部持有一个 matchers <a href="https://link.gitcode.com/i/a5d13b33676f43ded756b9b7eb58ed26" target="_blank">]matcher 切片,Route.Match 会依次执行全部 matcher,任何一个不通过即整体不匹配([route.go)。

几个容易踩坑的细节:

  • Methods() 内部会将方法名统一转大写(route.go)。
  • Schemes() 会转小写,且第一个 scheme 会作为反向构建 URL 时的默认 scheme(route.go)。
  • Headers() 的值为空字符串时,仅检查该 header 键是否存在,不校验具体值(route.go 注释)。
  • PathPrefix() 不会把斜杠当作特殊分隔符——"/foobar/" 也会被前缀 "/foo" 命中,因此建议前缀以尾斜杠结尾(route.go)。
  • Methods matcher 失败时返回 ErrMethodMismatch;无任何匹配时返回 ErrNotFound(mux.go)。

五、匹配顺序与子路由

路由按照注册顺序依次测试。若两个路由都匹配,先注册的优先:

r := mux.NewRouter()
r.HandleFunc("/specific", specificHandler)
r.PathPrefix("/").Handler(catchAllHandler)

当多个路由需要共享相同的匹配条件时,可以创建子路由(subrouter)。例如让一组 URL 只在 host 为 www.example.com 时被匹配:

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)

上面三条路径只有域名是 www.example.com 时才会被测试,因为子路由本身被优先测试。这不仅方便,还能优化匹配性能。子路由可以基于任意 Route 支持的匹配器创建。

子路由还可以用来创建域名或路径 "namespace":在中心位置定义子路由,应用的其他部分可相对某个子路由注册各自路径。

路径前缀的继承:当子路由有路径前缀时,内部路由会以它为基准拼合路径:

r := mux.NewRouter()
s := r.PathPrefix("/products").Subrouter()
// "/products/"
s.HandleFunc("/", ProductsHandler)
// "/products/{key}/"
s.HandleFunc("/{key}/", ProductHandler)
// "/products/{key}/details"
s.HandleFunc("/{key}/details", ProductDetailsHandler)

源码依据:Subrouter() 通过 copyRouteConf 深拷贝父路由的配置(包括 strictSlash、useEncodedPath、matchers 等)并共享命名路由表(route.go);Router.Match 按顺序遍历 routes,命中后若 MatchErr == nil 才构建中间件链(mux.go)。

5.1 Router 的三个关键开关

在 mux.go 中还提供了三个路由行为开关,README 虽未展开,但生产中十分常用:

  • StrictSlash(true):当路由路径为 /path/ 时,访问 /path 会 301 重定向到 /path/(反之亦然)。注意对 POST/PUT 等非幂等方法,多数客户端会在重定向后改用 GET,需用中间件或客户端设置调整。对使用 PathPrefix() 的路由,strict slash 会被忽略(因为前缀无法决定重定向行为),但其派生的子路由会继承原设置。
  • SkipClean(true):关闭路径清洗,使 /path//to 保留双斜杠(对类似 /fetch/http://xkcd.com/534/ 的路由有用)。
  • UseEncodedPath():按编码后的原始路径匹配,例如 /path/foo%2Fbar/to 可命中 /path/{var}/to。

六、静态文件服务

注意,PathPrefix() 提供的路径代表一种 "通配":调用 PathPrefix("/static/").Handler(...) 意味着任何匹配 /static/* 的请求都会交给该 handler。这使静态文件服务变得非常简单:

func main() {
    var dir string

    flag.StringVar(&dir, "dir", ".", "the directory to serve files from. Defaults to the current dir")
    flag.Parse()
    r := mux.NewRouter()

    // 在 http://localhost:8000/static/<filename> 下提供服务
    r.PathPrefix("/static/").Handler(http.StripPrefix("/static/", http.FileServer(http.Dir(dir))))

    srv := &http.Server{
        Handler:      r,
        Addr:         "127.0.0.1:8000",
        // 良好实践:为创建的服务器强制设置超时!
        WriteTimeout: 15 * time.Second,
        ReadTimeout:  15 * time.Second,
    }

    log.Fatal(srv.ListenAndServe())
}

七、服务单页应用(SPA)

多数情况下,把 SPA 放在独立的 Web 服务器上、与 API 分开是合理的;但有时也希望能从一个入口同时提供两者。可以编写一个简单 handler 来服务 SPA(例如配合 React Router 的 BrowserRouter),并利用 mux 强大的路由来服务 API 端点:

package main

import (
	"encoding/json"
	"log"
	"net/http"
	"os"
	"path/filepath"
	"time"

	"github.com/gorilla/mux"
)

// spaHandler 实现 http.Handler 接口,用于响应 HTTP 请求。
// 静态目录路径和其中的 index 文件路径用于在给定静态目录中服务 SPA。
type spaHandler struct {
	staticPath string
	indexPath  string
}

// ServeHTTP 检查 URL 路径,在静态目录中定位文件。
// 若找到文件则直接服务;若未找到,则服务 index 文件。
// 这正适合服务 SPA(单页应用)。
func (h spaHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
	// 获取绝对路径,防止目录遍历
	path, err := filepath.Abs(r.URL.Path)
	if err != nil {
		// 获取绝对路径失败,返回 400 并终止
		http.Error(w, err.Error(), http.StatusBadRequest)
		return
	}

	// 将路径与静态目录路径拼接
	path = filepath.Join(h.staticPath, path)

	// 检查该路径下是否存在文件
	_, err = os.Stat(path)
	if os.IsNotExist(err) {
		// 文件不存在,服务 index.html
		http.ServeFile(w, r, filepath.Join(h.staticPath, h.indexPath))
		return
	} else if err != nil {
		// 其他错误:返回 500 并终止
		http.Error(w, err.Error(), http.StatusInternalServerError)
		return
	}

	// 否则用 http.FileServer 服务静态目录
	http.FileServer(http.Dir(h.staticPath)).ServeHTTP(w, r)
}

func main() {
	router := mux.NewRouter()

	router.HandleFunc("/api/health", func(w http.ResponseWriter, r *http.Request) {
		// 示例 API handler
		json.NewEncoder(w).Encode(map[string]bool{"ok": true})
	})

	spa := spaHandler{staticPath: "build", indexPath: "index.html"}
	router.PathPrefix("/").Handler(spa)

	srv := &http.Server{
		Handler: router,
		Addr:    "127.0.0.1:8000",
		// 良好实践:为创建的服务器强制设置超时!
		WriteTimeout: 15 * time.Second,
		ReadTimeout:  15 * time.Second,
	}

	log.Fatal(srv.ListenAndServe())
}

八、命名路由与 URL 反向构建

路由可以被命名。定义了名称的路由即可被 "反转"(构建)出 URL。用 Name() 命名路由:

r := mux.NewRouter()
r.HandleFunc("/articles/{category}/{id:[0-9]+}", ArticleHandler).
  Name("article")

构建 URL 时,通过 Get("article") 取回路由,调用 URL() 并传入路由变量键值对序列:

url, err := r.Get("article").URL("category", "technology", "id", "42")

得到如下 path 的 url.URL:

"/articles/technology/42"

对 host 变量和 query 变量同样适用:

r := mux.NewRouter()
r.Host("{subdomain}.example.com").
  Path("/articles/{category}/{id:[0-9]+}").
  Queries("filter", "{filter}").
  HandlerFunc(ArticleHandler).
  Name("article")

// url.String() 将为 "http://news.example.com/articles/technology/42?filter=gorilla"
url, err := r.Get("article").URL("subdomain", "news",
                                 "category", "technology",
                                 "id", "42",
                                 "filter", "gorilla")

路由定义的所有变量都是必需的,且其值必须符合对应正则模式。这些要求保证了生成的 URL 一定匹配已注册的路由——唯一例外是显式定义的 "build-only" 路由,它们永远不会被匹配(BuildOnly() 将 buildOnly 置为 true,Route.Match 会直接返回 false,见 route.go)。

请求头也支持正则匹配:

r.HeadersRegexp("Content-Type", "application/(text|json)")

该路由既能匹配 Content-Type: application/json,也能匹配 application/text。若值设置为空字符串,则只检查键是否存在;可用 ^ 与 $ 锚点精确匹配(route.go)。

只构建 host 或 path:分别使用 URLHost() 或 URLPath():

// "http://news.example.com/"
host, err := r.Get("article").URLHost("subdomain", "news")

// "/articles/technology/42"
path, err := r.Get("article").URLPath("category", "technology", "id", "42")

在子路由中分别定义的 host 与 path 也可构建:

r := mux.NewRouter()
s := r.Host("{subdomain}.example.com").Subrouter()
s.Path("/articles/{category}/{id:[0-9]+}").
  HandlerFunc(ArticleHandler).
  Name("article")

// "http://news.example.com/articles/technology/42"
url, err := r.Get("article").URL("subdomain", "news",
                                 "category", "technology",
                                 "id", "42")

源码细节:URL() 构建时,host 存在则 scheme 默认为 http,若调用过 Schemes(...) 则取第一个作为 scheme;query 变量会先经 url.QueryEscape 编码;生成结果会与完整正则复核,不匹配时再逐个变量校验并给出精确错误信息(route.go、regexp.go)。此外 BuildVarsFunc 可在构建前改写变量 map,多次调用时会依次复合(route.go)。注意:同一路由调用两次 Name() 会报错(route.go)。

九、Walking Routes:遍历已注册路由

mux.Router 的 Walk 函数可用于访问路由器上注册的所有路由。例如下面的程序打印所有注册路由:

package main

import (
	"fmt"
	"net/http"
	"strings"

	"github.com/gorilla/mux"
)

func handler(w http.ResponseWriter, r *http.Request) {
	return
}

func main() {
	r := mux.NewRouter()
	r.HandleFunc("/", handler)
	r.HandleFunc("/products", handler).Methods("POST")
	r.HandleFunc("/articles", handler).Methods("GET")
	r.HandleFunc("/articles/{id}", handler).Methods("GET", "PUT")
	r.HandleFunc("/authors", handler).Queries("surname", "{surname}")
	err := r.Walk(func(route *mux.Route, router *mux.Router, ancestors []*mux.Route) error {
		pathTemplate, err := route.GetPathTemplate()
		if err == nil {
			fmt.Println("ROUTE:", pathTemplate)
		}
		pathRegexp, err := route.GetPathRegexp()
		if err == nil {
			fmt.Println("Path regexp:", pathRegexp)
		}
		queriesTemplates, err := route.GetQueriesTemplates()
		if err == nil {
			fmt.Println("Queries templates:", strings.Join(queriesTemplates, ","))
		}
		queriesRegexps, err := route.GetQueriesRegexp()
		if err == nil {
			fmt.Println("Queries regexps:", strings.Join(queriesRegexps, ","))
		}
		methods, err := route.GetMethods()
		if err == nil {
			fmt.Println("Methods:", strings.Join(methods, ","))
		}
		fmt.Println()
		return nil
	})

	if err != nil {
		fmt.Println(err)
	}

	http.Handle("/", r)
}

源码依据:Walk 按注册顺序、深度优先遍历路由树,子路由会被递归访问;WalkFunc 返回 mux.SkipRouter 可跳过进入某个子路由(mux.go)。GetPathTemplate、GetPathRegexp、GetQueriesTemplates、GetQueriesRegexp、GetMethods、GetHostTemplate 等方法(route.go)官方注释表明它们适合用于生成 REST API 文档或对接第三方监控/埋点系统。

十、优雅关闭(Graceful Shutdown)

Go 1.8 起 *http.Server 支持优雅关闭。结合 mux 的实现方式如下:

package main

import (
    "context"
    "flag"
    "log"
    "net/http"
    "os"
    "os/signal"
    "time"

    "github.com/gorilla/mux"
)

func main() {
    var wait time.Duration
    flag.DurationVar(&wait, "graceful-timeout", time.Second * 15, "the duration for which the server gracefully wait for existing connections to finish - e.g. 15s or 1m")
    flag.Parse()

    r := mux.NewRouter()
    // 按需添加路由

    srv := &http.Server{
        Addr:         "0.0.0.0:8080",
        // 设置超时以防 Slowloris 攻击
        WriteTimeout: time.Second * 15,
        ReadTimeout:  time.Second * 15,
        IdleTimeout:  time.Second * 60,
        Handler: r, // 将 gorilla/mux 实例传入
    }

    // 在 goroutine 中运行服务器以免阻塞
    go func() {
        if err := srv.ListenAndServe(); err != nil {
            log.Println(err)
        }
    }()

    c := make(chan os.Signal, 1)
    // 通过 SIGINT (Ctrl+C) 触发优雅关闭
    // SIGKILL、SIGQUIT 或 SIGTERM (Ctrl+/) 不会被捕获
    signal.Notify(c, os.Interrupt)

    // 阻塞直到收到信号
    <-c

    // 创建等待截止时间
    ctx, cancel := context.WithTimeout(context.Background(), wait)
    defer cancel()
    // 无连接时立即返回,否则等待直到超时截止
    srv.Shutdown(ctx)
    // 可选:若应用需基于 context 取消等待其他服务收尾,
    // 可在 goroutine 中运行 srv.Shutdown 并阻塞于 <-ctx.Done()
    log.Println("shutting down")
    os.Exit(0)
}

十一、中间件(Middleware)

mux 支持向 Router 添加中间件,中间件按添加顺序执行,命中路由(包括其子路由)时生效。中间件通常是处理单个请求的小段代码:处理请求、执行某些操作,然后传给下一个中间件或最终 handler。常见用途包括请求日志、header 修改、ResponseWriter 劫持等。

mux 中间件采用事实标准类型:

type MiddlewareFunc func(http.Handler) http.Handler

通常返回的 handler 是一个闭包:对传入的 http.ResponseWriter 与 http.Request 做些处理,然后调用作为参数传入的 handler。闭包可以访问其创建时所在作用域的变量,同时保持接收者强制要求的签名。

一个记录请求 URI 的基础中间件:

func loggingMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        // 在此执行操作
        log.Println(r.RequestURI)
        // 调用下一个 handler——可能是链中另一个中间件,或最终 handler
        next.ServeHTTP(w, r)
    })
}

通过 Router.Use() 添加中间件:

r := mux.NewRouter()
r.HandleFunc("/", handler)
r.Use(loggingMiddleware)

一个更复杂的认证中间件——将 session token 映射到用户:

// 定义结构体
type authenticationMiddleware struct {
	tokenUsers map[string]string
}

// 初始化
func (amw *authenticationMiddleware) Populate() {
	amw.tokenUsers["00000000"] = "user0"
	amw.tokenUsers["aaaaaaaa"] = "userA"
	amw.tokenUsers["05f717e5"] = "randomUser"
	amw.tokenUsers["deadbeef"] = "user0"
}

// 中间件函数,每个请求都会调用
func (amw *authenticationMiddleware) Middleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        token := r.Header.Get("X-Session-Token")

        if user, found := amw.tokenUsers[token]; found {
        	// 在 map 中找到 token
        	log.Printf("Authenticated user %s\n", user)
        	// 将请求传递给下一个中间件(或最终 handler)
        	next.ServeHTTP(w, r)
        } else {
        	// 写错误并终止 handler 链
        	http.Error(w, "Forbidden", http.StatusForbidden)
        }
    })
}
r := mux.NewRouter()
r.HandleFunc("/", handler)

amw := authenticationMiddleware{}
amw.Populate()

r.Use(amw.Middleware)

重要注意:如果中间件没有用相应参数调用 next.ServeHTTP(),handler 链将停止。这可用于中间件主动终止请求。中间件若打算终止请求则应写入 ResponseWriter,若不打算终止则不应写入。

执行顺序的源码印证:Router.Use() 将中间件追加到 middlewares 切片(middleware.go);Router.Match 在命中后从切片尾部向前逐层包装 handler(mux.go),因此实际执行顺序与 Use 的添加顺序一致,且中间件只作用于匹配成功的请求。

十二、处理 CORS 请求

CORSMethodMiddleware 用于简化 Access-Control-Allow-Methods 响应头的严格设置:

  • 其他 CORS 头(如 Access-Control-Allow-Origin)仍需自备 CORS handler 设置。
  • 该中间件会把路由上所有方法 matcher 合并设置到 Access-Control-Allow-Methods 头。例如 r.Methods(http.MethodGet, http.MethodPut, http.MethodOptions) 会得到 Access-Control-Allow-Methods: GET,PUT,OPTIONS。
  • 若不显式指定方法,则 路由上必须存在 OPTIONS 方法 matcher,中间件才会设置响应头。

结合自定义 OPTIONS handler 设置全部 CORS 头的完整示例:

package main

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

func main() {
    r := mux.NewRouter()

    // 重要:必须指定 OPTIONS 方法 matcher,中间件才会设置 CORS 头
    r.HandleFunc("/foo", fooHandler).Methods(http.MethodGet, http.MethodPut, http.MethodPatch, http.MethodOptions)
    r.Use(mux.CORSMethodMiddleware(r))

    http.ListenAndServe(":8080", r)
}

func fooHandler(w http.ResponseWriter, r *http.Request) {
    w.Header().Set("Access-Control-Allow-Origin", "*")
    if r.Method == http.MethodOptions {
        return
    }

    w.Write([]byte("foo"))
}

用 curl 发起请求:

curl localhost:8080/foo -v

响应类似:

*   Trying ::1...
* TCP_NODELAY set
* Connected to localhost (::1) port 8080 (#0)
> GET /foo HTTP/1.1
> Host: localhost:8080
> User-Agent: curl/7.59.0
> Accept: */*
>
< HTTP/1.1 200 OK
< Access-Control-Allow-Methods: GET,PUT,PATCH,OPTIONS
< Access-Control-Allow-Origin: *
< Date: Fri, 28 Jun 2019 20:13:30 GMT
< Content-Length: 3
< Content-Type: text/plain; charset=utf-8
<
* Connection #0 to host localhost left intact
foo

实现原理:CORSMethodMiddleware(r) 返回一个中间件,对每个请求调用 getAllMethodsForRoute,遍历所有路由(含命中但方法不匹配的 ErrMethodMismatch 路由)汇总其方法列表;若列表包含 OPTIONS 才写入 Access-Control-Allow-Methods(middleware.go)。

十三、测试处理器(Testing Handlers)

在 Go Web 应用中测试 handler 很直接,mux 不会让这件事变得更复杂。给定 endpoints.go 与 endpoints_test.go 两个文件:

先看简单的 HTTP handler:

// endpoints.go
package main

func HealthCheckHandler(w http.ResponseWriter, r *http.Request) {
    // 非常简单的健康检查
    w.Header().Set("Content-Type", "application/json")
    w.WriteHeader(http.StatusOK)

    // 未来可对 DB 或缓存(如 Redis)做简单 PING 并纳入响应
    io.WriteString(w, `{"alive": true}`)
}

func main() {
    r := mux.NewRouter()
    r.HandleFunc("/health", HealthCheckHandler)

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

对应测试代码:

// endpoints_test.go
package main

import (
    "net/http"
    "net/http/httptest"
    "testing"
)

func TestHealthCheckHandler(t *testing.T) {
    // 构造传入 handler 的请求。目前没有 query 参数,第三个参数传 'nil'
    req, err := http.NewRequest("GET", "/health", nil)
    if err != nil {
        t.Fatal(err)
    }

    // 创建 ResponseRecorder(实现了 http.ResponseWriter)记录响应
    rr := httptest.NewRecorder()
    handler := http.HandlerFunc(HealthCheckHandler)

    // handler 满足 http.Handler 接口,可直接调用其 ServeHTTP 方法
    handler.ServeHTTP(rr, req)

    // 检查状态码是否符合预期
    if status := rr.Code; status != http.StatusOK {
        t.Errorf("handler returned wrong status code: got %v want %v",
            status, http.StatusOK)
    }

    // 检查响应体是否符合预期
    expected := `{"alive": true}`
    if rr.Body.String() != expected {
        t.Errorf("handler returned unexpected body: got %v want %v",
            rr.Body.String(), expected)
    }
}

如果路由包含变量,可以把变量放进请求里测试,并可用表驱动测试(table-driven tests)覆盖多组可能的变量组合:

// endpoints.go
func main() {
    r := mux.NewRouter()
    // 带路由变量的路由:
    r.HandleFunc("/metrics/{type}", MetricsHandler)

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

测试文件,用表驱动测试 routeVariables:

// endpoints_test.go
func TestMetricsHandler(t *testing.T) {
    tt := []struct{
        routeVariable string
        shouldPass bool
    }{
        {"goroutines", true},
        {"heap", true},
        {"counters", true},
        {"queries", true},
        {"adhadaeqm3k", false},
    }

    for _, tc := range tt {
        path := fmt.Sprintf("/metrics/%s", tc.routeVariable)
        req, err := http.NewRequest("GET", path, nil)
        if err != nil {
            t.Fatal(err)
        }

        rr := httptest.NewRecorder()

	// 需要创建 router 并让请求经过它,这样变量才会被加入 context
	router := mux.NewRouter()
        router.HandleFunc("/metrics/{type}", MetricsHandler)
        router.ServeHTTP(rr, req)

        // 此处 MetricsHandler 对不认识的变量返回非 200
        if rr.Code == http.StatusOK && !tc.shouldPass {
            t.Errorf("handler should have failed on routeVariable %s: got %v want %v",
                tc.routeVariable, rr.Code, http.StatusOK)
        }
    }
}

注意测试中必须让请求经过 router.ServeHTTP(而非直接调用 handler),路由变量才会被写入 request context 并由 mux.Vars 取出。

十四、完整可运行示例

下面是一个完整可运行的小型 mux 服务器:

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()
    // 路由由路径和 handler 函数组成
    r.HandleFunc("/", YourHandler)

    // 绑定端口并将 router 传入
    log.Fatal(http.ListenAndServe(":8000", r))
}

十五、Docker Engine 中的真实应用:基于 mux 构建 REST API 服务器

mux 在 docker-ce 仓库中的核心用武之地是 Docker Engine API 服务器。components/engine/api/server/server.go 的 createMux() 以 mux 为骨干注册了全部引擎 API 端点:

// createMux 初始化服务器使用的主路由
func (s *Server) createMux() *mux.Router {
	m := mux.NewRouter()

	logrus.Debug("Registering routers")
	for _, apiRouter := range s.routers {
		for _, r := range apiRouter.Routes() {
			f := s.makeHTTPHandler(r.Handler())
			logrus.Debugf("Registering %s, %s", r.Method(), r.Path())
			m.Path(versionMatcher + r.Path()).Methods(r.Method()).Handler(f)
			m.Path(r.Path()).Methods(r.Method()).Handler(f)
		}
	}
	// ...debug 路由注册...

	notFoundHandler := httputils.MakeErrorHandler(pageNotFoundError{})
	m.HandleFunc(versionMatcher+"/{path:.*}", notFoundHandler)
	m.NotFoundHandler = notFoundHandler
	m.MethodNotAllowedHandler = notFoundHandler

	return m
}

见 components/engine/api/server/server.go。其中三个关键设计直接对应本文前述概念:

  1. 路由变量正则:versionMatcher 定义为 /v{version:<a href="https://link.gitcode.com/i/1307c64299e24bac8f391a818b9bc40d" target="_blank">0-9.]+},即用 mux 的 {name:pattern} 语法为 API 版本号设置正则约束([server.go)。同一端点同时注册"带版本"与"不带版本"两个路径。
  2. 变量提取:makeHTTPHandler 在调用真正的 handler 前调用 mux.Vars(r) 取出路由变量,一并传给 httputils.APIFunc(server.go)。
  3. 兜底 handler:NotFoundHandler 与 MethodNotAllowedHandler 被显式设置为统一错误处理器,同时注册 /{path:.*} 通配路由——这正是 PathPrefix/通配符路由在真实产品中的典型用法。

此外 httputils.MakeErrorHandler 也会读取 mux.Vars(r)<a href="https://link.gitcode.com/i/706fb2152069a2580b7922d55ff06c7f" target="_blank">"version"] 判断客户端使用的 API 版本是否支持 JSON 格式错误响应(1.23 及之后支持),从而选择 JSON 或纯文本错误格式([components/engine/api/server/httputils/httputils.go)。这展示了 mux.Vars 在跨多个 handler 复用路由上下文时的实际价值。

附:源码阅读地图

关注点 文件 关键内容
Router 主体 mux.go NewRouter、Match/ServeHTTP、Vars、StrictSlash、Walk
路由与匹配器 route.go Route、全部 matcher、Subrouter、URL 构建
模板编译 regexp.go 默认变量模式、正则编译、变量提取
中间件 middleware.go Use、MiddlewareFunc、CORSMethodMiddleware
Docker 引擎应用 api/server/server.go createMux、versionMatcher、makeHTTPHandler
错误响应应用 api/server/httputils/httputils.go 基于 mux.Vars 的版本判断

许可证:gorilla/mux 以 BSD 许可证发布,详见其 LICENSE 文件。

登录后查看全文
docker-ce