gorilla/mux 路由实战指南:在 Docker Engine 中掌握 Go 的 HTTP 请求路由与分发
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)。Methodsmatcher 失败时返回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。其中三个关键设计直接对应本文前述概念:
- 路由变量正则:
versionMatcher定义为/v{version:<a href="https://link.gitcode.com/i/1307c64299e24bac8f391a818b9bc40d" target="_blank">0-9.]+},即用 mux 的{name:pattern}语法为 API 版本号设置正则约束([server.go)。同一端点同时注册"带版本"与"不带版本"两个路径。 - 变量提取:
makeHTTPHandler在调用真正的 handler 前调用mux.Vars(r)取出路由变量,一并传给httputils.APIFunc(server.go)。 - 兜底 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 文件。