gorilla/mux 完全指南:用 Go 打造高性能 HTTP 路由与请求分发器
gorilla/mux 完全指南:用 Go 打造高性能 HTTP 路由与请求分发器
gorilla/mux 是 Go 生态中最流行的 HTTP 请求路由器(request router)与分发器(dispatcher)之一,它为开发者提供了一套远比标准库 net/http 更强大、更灵活的路由匹配机制。本文将以仓库中 vendor/github.com/gorilla/mux/README.md 为核心骨架,并结合 vendor/github.com/gorilla/mux 下的真实源码实现(mux.go、route.go、middleware.go、regexp.go),系统讲解 mux 的安装、路由匹配、静态文件服务、SPA 托管、URL 反转、中间件、CORS 处理与测试方法论,让你不仅能快速上手,还能理解其底层原理。该库也是本仓库 devspace 项目的间接依赖(见 go.mod,版本 v1.8.0)。
mux 是什么:HTTP 请求多路复用器
mux 这个名字来自 "HTTP request multiplexer"(HTTP 请求多路复用器)。与标准库 http.ServeMux 类似,mux.Router 会把进入的请求与一组已注册的路由逐一匹配,并将请求交给匹配成功的路由所对应的 handler 处理。但相比标准库,mux 具备以下核心特性(对应 README 的 Features 列表):
- 完整实现
http.Handler接口,因此可以与标准库http.ServeMux无缝共存、互相嵌套; - 支持丰富的匹配维度:URL 主机(host)、路径(path)、路径前缀(prefix)、协议 scheme、请求头(header)、查询参数(query value)、HTTP 方法,甚至自定义匹配函数;
- 变量化匹配:URL 主机、路径和查询参数都可以定义变量,变量可附带可选的正则表达式约束;
- URL 反向构建(reverse building):可以根据已注册的路由"反向"生成 URL,便于在代码中维护对资源的引用;
- 子路由(subrouter)机制:只有父路由匹配后才会测试嵌套的子路由,既能共享公共匹配条件,又能显著优化匹配性能。
在源码层面,路由匹配的核心实现位于 mux.go 的 Router.Match:它会按注册顺序遍历所有路由,一旦某个 Route.Match 返回 true 且无匹配错误,就构建中间件链并把 handler 填入 RouteMatch。找不到路由时返回 ErrNotFound,方法不匹配时返回 ErrMethodMismatch(定义见 mux.go)。
安装与最小可用示例
安装
在配置好 Go 工具链的环境中执行:
go get -u github.com/gorilla/mux
在本仓库中,gorilla/mux 以 v1.8.0 版本被引入(见 go.mod),可直接查看其源码文件:mux.go、route.go、middleware.go、regexp.go。
注册路径与 handler
下面这段代码注册了三个路由,把 URL 路径映射到对应的 handler:
func main() {
r := mux.NewRouter()
r.HandleFunc("/", HomeHandler)
r.HandleFunc("/products", ProductsHandler)
r.HandleFunc("/articles", ArticlesHandler)
http.Handle("/", r)
}
这与标准库 http.HandleFunc() 的工作方式等价:当请求 URL 与其中某个路径匹配时,对应 handler 会被调用,参数为 (http.ResponseWriter, *http.Request)。NewRouter() 的源码见 mux.go,它初始化了一个带 namedRoutes 空映射的 Router。
路径变量与正则约束
路径中可以定义变量,语法为 {name} 或 {name:pattern}。如果不写正则,变量会匹配到下一个斜杠为止的所有内容:
r := mux.NewRouter()
r.HandleFunc("/products/{key}", ProductHandler)
r.HandleFunc("/articles/{category}/", ArticlesCategoryHandler)
r.HandleFunc("/articles/{category}/{id:[0-9]+}", ArticleHandler)
/products/{key}:key匹配任意非斜杠片段,例如/products/42;/articles/{category}/{id:[0-9]+}:id仅匹配一位或多位数字。
变量名会被收集进一个路由变量映射中,在 handler 里通过 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 的 newRouteRegexp 中被解析。对于 path 类型,变量默认匹配模式为 <a href="https://link.gitcode.com/i/f999da0de47a52e606e4ab2f79f7179c" target="_blank">^/]+(直到下一个斜杠);对于 host 类型默认是 [^.]+(直到下一个点);对于 query 类型默认是 .*。解析器会同时生成三样东西:用于匹配的正则(带 ^...$ 锚点)、用于反向构建 URL 的模板、以及用于校验构建时变量值的正则(^pattern$)。路径必须以 / 开头,否则会报错(见 [route.go)。
多维度的路由匹配
除了路径,mux 允许在一条路由上叠加多种匹配条件。
主机(Host)匹配与变量化子域
r := mux.NewRouter()
// 仅当域名为 "www.example.com" 时匹配
r.Host("www.example.com")
// 匹配动态子域
r.Host("{subdomain:[a-z]+}.example.com")
路径前缀、方法、协议、请求头、查询参数
// 路径前缀
r.PathPrefix("/products/")
// HTTP 方法
r.Methods("GET", "POST")
// URL scheme
r.Schemes("https")
// 请求头值
r.Headers("X-Requested-With", "XMLHttpRequest")
// 查询参数
r.Queries("key", "value")
// 自定义匹配函数
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")
底层原理:每种匹配条件都实现了 matcher 接口(Match(*http.Request, *RouteMatch) bool,定义见 route.go)。路由按注册顺序依次执行这些 matcher,全部通过才算匹配成功(见 route.go 的 Route.Match)。其中:
Methods()内部会把方法名统一转为大写后存入methodMatcher(见 route.go);Schemes()会转小写,并把第一个 scheme 记录为 URL 构建时的默认 scheme;请求里没有 scheme 时,依据req.TLS是否为 nil 推断为 http 或 https(见 route.go);Headers()使用mapFromPairsToString把成对参数变成 map,空字符串值表示"只要该 key 存在即匹配"(见 route.go 与 mux.go)。
匹配顺序:先注册者优先
路由按照注册顺序被测试,如果两条路由都匹配,先注册的那条胜出:
r := mux.NewRouter()
r.HandleFunc("/specific", specificHandler)
r.PathPrefix("/").Handler(catchAllHandler)
因此务必将更具体的路由注册在前面,把兜底路由(catch-all)放在最后。
子路由(Subrouter):分组与性能优化
反复设置相同匹配条件很繁琐,mux 提供了子路由机制把共享条件分组。例如,要求所有路由仅在主机为 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 时才被测试——因为父路由(host matcher)先被测试。这不仅是便利,还能优化匹配性能。子路由可以基于路由支持的任何属性匹配器创建,常用于构建域名命名空间或路径命名空间。
当子路由带有路径前缀时,内部路由会以前缀为基准拼接路径:
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() 会把子路由器本身作为一个 matcher 注册到父路由上(见 route.go)。Router.Match 按顺序遍历路由,父路由匹配成功后,其内部的子路由器 matcher 才会继续被测试,这正是"嵌套路由只有父路由匹配才被测试"的实现基础。此外,路由的路径模板拼接逻辑在 route.go:当路由已有 path 正则时,新模板会去掉旧模板尾部的 / 再拼接。父路由的配置(如 strictSlash、useEncodedPath)会通过 copyRouteConf 深拷贝给子路由(见 mux.go)。
静态文件服务
注意:传给 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())
}
这里 http.StripPrefix 负责去掉 /static/ 前缀,http.FileServer 负责从目录中定位文件。注意 README 中的 PathPrefix 注释指出:前缀匹配不会特殊处理斜杠("/foobar/" 会被前缀 "/foo" 匹配),所以如需按目录前缀匹配,建议带上结尾斜杠;另外 Router.StrictSlash() 对带 PathPrefix 的路由不生效(见 route.go)。
同时托管 SPA 与 API
大多数场景下,把单页应用(SPA)放在独立的 Web 服务器上、API 放在另一个服务器更合理;但有时也希望二者同源部署。mux 允许你用简单 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 请求。
// staticPath 指向静态资源目录,indexPath 是该目录内的入口文件。
type spaHandler struct {
staticPath string
indexPath string
}
// ServeHTTP 先检查 URL 路径是否对应静态目录中的真实文件;
// 若文件存在则直接服务,否则回退到 index.html(SPA 路由回退)。
func (h spaHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
// 获取绝对路径以防目录穿越攻击
path, err := filepath.Abs(r.URL.Path)
if err != nil {
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 {
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())
}
核心思路:API 路由(如 /api/health)由 mux 精确匹配;其余所有路径通过 PathPrefix("/") 交给 spaHandler,它检查磁盘上是否有真实文件,有则返回文件,没有则返回 index.html,从而把前端路由(如 React/Vue/Ember)的后端回退逻辑统一收口。注意代码中用 filepath.Abs 防止目录穿越。
注册 URL 与反向构建(Registered URLs)
反向构建 URL 是 mux 的招牌能力:它让你在代码中不硬编码 URL 字符串,而是根据路由定义"生成" URL,从而保证 URL 与路由始终一致。
命名路由
路由可以命名,命名后就能反向构建 URL:
r := mux.NewRouter()
r.HandleFunc("/articles/{category}/{id:[0-9]+}", ArticleHandler).
Name("article")
命名通过 Name() 完成(见 route.go),名字会被登记在 Router 的 namedRoutes map 中。同一条路由重复命名会报错("route already has name")。
使用 URL() 构建完整 URL
通过 r.Get("article") 取回命名路由,再调用 URL() 并以键值对形式传入变量:
url, err := r.Get("article").URL("category", "technology", "id", "42")
结果为 url.URL,其 Path 为:
"/articles/technology/42"
主机变量和查询变量同样支持:
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(),见 route.go),这类路由永远不会参与请求匹配,只用于构建 URL。
底层原理:URL() 的实现位于 route.go。它通过 prepareVars 把键值对转成 map(可叠加 BuildVarsFunc 自定义转换,见 route.go),再分别调用 host、path、query 各自正则对象的 url(values) 方法填充模板并校验变量值。URL 的 scheme 默认为 http,若路由设置了 Schemes() 则取第一个 scheme;当只构建 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")
请求头的正则匹配
mux 也支持对请求头做正则匹配:
r.HeadersRegexp("Content-Type", "application/(text|json)")
上面这条路由会同时匹配 Content-Type 为 application/json 与 application/text 的请求。HeadersRegexp 的实现见 route.go,它把值编译成正则后使用 matchMapWithRegex 做匹配;若需要用精确匹配,请给正则加上 ^ 与 $ 锚点。
遍历路由(Walking Routes)
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 的实现在 mux.go,它按注册顺序、深度优先地遍历路由树:对每条路由先调用 walkFn,若返回 SkipRouter 则跳过其子路由器继续;否则继续深入该路由内部的子路由器(matcher 为 *Router 的情形或 handler 为 *Router 的情形)。GetPathTemplate、GetPathRegexp、GetQueriesTemplates、GetQueriesRegexp、GetMethods 等取值方法见 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, // 将我们的 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
// 创建超时 deadline
ctx, cancel := context.WithTimeout(context.Background(), wait)
defer cancel()
// 无连接时不会阻塞,否则会一直等待到超时
srv.Shutdown(ctx)
log.Println("shutting down")
os.Exit(0)
}
要点:
- 通过
signal.Notify捕获os.Interrupt; srv.Shutdown(ctx)会等待在途连接处理完成,或在wait超时后强制退出;- 若需要在多个服务间协调,可把
srv.Shutdown放入 goroutine,并阻塞等待<-ctx.Done()。
中间件(Middleware)
mux 支持为 Router 添加中间件,匹配成功时按添加顺序执行(包括其子路由)。中间件是典型的"处理链"小片段:接收一个请求、做点什么、再传给下一个中间件或最终 handler。常见用途包括请求日志、请求头修改、ResponseWriter 包装(hijacking)等。
mux 中间件采用事实标准类型定义:
type MiddlewareFunc func(http.Handler) http.Handler
通常返回的 handler 是一个闭包:它处理传入的 http.ResponseWriter 和 *http.Request,然后调用作为参数传入的 handler。这充分利用了 Go 闭包可以访问其创建上下文变量的能力,同时保持接收者所要求的签名。
一个记录请求 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)
一个更复杂的、把会话 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 {
// token 命中,放行
log.Printf("Authenticated user %s\n", user)
next.ServeHTTP(w, r)
} else {
// 写入错误并中断处理链
http.Error(w, "Forbidden", http.StatusForbidden)
}
})
}
使用方式:
r := mux.NewRouter()
r.HandleFunc("/", handler)
amw := authenticationMiddleware{}
amw.Populate()
r.Use(amw.Middleware)
底层原理与重要注意点:
- 中间件定义与
Use()实现见 middleware.go:Router.middlewares是切片,按Use()调用顺序追加; - 在 mux.go 的
Router.Match中,一旦命中路由且无匹配错误,会从后往前遍历中间件切片并逐层包裹 handler,从而保证执行顺序与添加顺序一致; - 如果某个中间件不调用
next.ServeHTTP(),处理链就会被终止——这可用于主动中断请求。若中间件要终止请求,应当向ResponseWriter写入内容;若不断言终止,则不应写入,以免产生误导性的响应。
处理 CORS 请求
CORSMethodMiddleware 旨在简化严格设置 Access-Control-Allow-Methods 响应头的工作:
- 其他 CORS 响应头(如
Access-Control-Allow-Origin)仍需由你自己的 CORS handler 负责设置; - 该中间件会把路由上所有方法匹配器(例如
r.Methods(http.MethodGet, http.MethodPut, http.MethodOptions)→Access-Control-Allow-Methods: GET,PUT,OPTIONS)合并后写入响应头; - 若路由未指定任何方法,必须存在
OPTIONS方法匹配器,中间件才会设置该响应头。
完整示例:
package main
import (
"net/http"
"github.com/gorilla/mux"
)
func main() {
r := mux.NewRouter()
// 重要:必须指定 OPTIONS 方法匹配器,中间件才会设置 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 请求 /foo:
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
可以看到响应头中自动出现了 Access-Control-Allow-Methods: GET,PUT,PATCH,OPTIONS,与路由上注册的方法完全一致。
底层原理:CORSMethodMiddleware 的实现见 middleware.go。它内部通过 getAllMethodsForRoute 遍历所有路由,找出与当前请求匹配(或仅方法不匹配)的路由,收集其方法匹配器集合;只有当集合中出现 OPTIONS 时,才把全部方法以逗号连接写入 Access-Control-Allow-Methods。随后继续调用 next.ServeHTTP,所以自定义 handler 中仍需自己设置 Access-Control-Allow-Origin 等头。
测试 handler(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。目前没有查询参数,第三个参数传 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))
}
// 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)
}
}
}
关键点:这里必须使用 mux.NewRouter() 并调用 router.ServeHTTP(rr, req) 派发请求,因为路由变量是通过请求 context 传递的——Router.ServeHTTP 内部在匹配成功后调用 requestWithVars 把变量写入 request context(见 mux.go),handler 再通过 mux.Vars(r) 从 context 读取(见 mux.go)。如果直接调用 handler 的 ServeHTTP,则无法访问这些变量。
完整可运行示例(Full Example)
一个基于 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))
}
路由匹配的执行流程小结
结合源码梳理一次完整请求的处理链路(对应 mux.go 的 ServeHTTP):
- 默认对请求路径做规范化清理(
cleanPath,消除./..等冗余片段),若清理后路径变化则返回 301 重定向(可通过SkipClean()关闭清理,UseEncodedPath()改为按编码路径匹配); - 调用
Router.Match(req, &match)按注册顺序测试每条路由(Route.Match逐个执行其 matcher); - 匹配成功:从后往前包装中间件得到最终 handler,把
Vars与Route写入 request context; - 匹配失败:若原因与方法相关(
ErrMethodMismatch)且设置了MethodNotAllowedHandler则使用之,否则返回 405;无任何匹配则使用NotFoundHandler,未设置时回退到标准库的http.NotFoundHandler()(404)。
此外,Router 还提供 StrictSlash()(控制尾斜杠 301 重定向行为,注意它对带 PathPrefix 的路由不生效)、SkipClean()、UseEncodedPath() 等配置开关(见 mux.go),可在实际项目中按需组合使用。
在 devspace 中的引用关系
gorilla/mux 在本仓库中以 v1.8.0 版本作为间接依赖引入(见 go.mod),其完整源码位于 vendor/github.com/gorilla/mux。如果你正在开发 devspace 或任何需要复杂 HTTP 路由的 Go 服务,这份指南中的模式(子路由分组、路径变量、URL 反转、中间件链、CORS 中间件与 httptest 测试)都可直接套用。许可证方面,gorilla/mux 采用 BSD 许可,详见 vendor/github.com/gorilla/mux/LICENSE。