Go ServeMux.Handler 怎样预览请求将匹配的路由

如果正在排查一条 HTTP 请求为什么没有进入预期处理器，直接看注册表往往不够：真正决定结果的是请求的 method、host 和 URL path。Go 的 net/http.ServeMux 提供了一个适合做“路由预览”的方法：

handler, pattern := mux.Handler(r)

handler 是这次请求将使用的处理器，始终非空；pattern 是匹配到的已注册模式。若路径需要规范化重定向，它会返回重定向后将匹配的路径；如果没有适用的处理器，则返回非空的 404/405 处理器和空 pattern。这个调用只帮助观察选择结果，不会替你执行处理器，也不会修改请求。

官方文档：https://pkg.go.dev/net/http#ServeMux.Handler

把 Handler 当成一次路由选择预览

我在写请求日志和路由测试时，更愿意把 mux.Handler(r) 看成一个只读的选择器。它回答的是“如果现在交给这个 mux，会选择谁”，而不是“已经完成了一次 HTTP 派发”。因此最小的观察代码只保留两个结果：

package main

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

// 预览请求会选择哪个处理器，不调用 handler.ServeHTTP。
func preview(mux *http.ServeMux, method, target string) {
	r := httptest.NewRequest(method, target, nil)
	h, pattern := mux.Handler(r)
	// h 由 ServeMux 保证非空；pattern 用来区分注册模式或边界结果。
	fmt.Printf("method=%s target=%s handler=%T pattern=%q\n", method, target, h, pattern)
}

func main() {
	mux := http.NewServeMux()
	mux.HandleFunc("/api/users/", func(http.ResponseWriter, *http.Request) {})
	mux.HandleFunc("/", func(http.ResponseWriter, *http.Request) {})

	// 这些调用只读取匹配结果，适合放在调试或测试辅助代码里。
	preview(mux, http.MethodGet, "http://example.test/api/users/42")
	preview(mux, http.MethodGet, "http://example.test/unknown")
}

示例的关键不是打印格式，而是没有调用 h.ServeHTTP。如果调试辅助函数为了“确认命中”而执行处理器，就会产生响应写入、业务副作用或重复统计，路由预览反而变成了一次真实请求。

在生产日志中也不建议直接打印整个 Request。记录 method、host、经过脱敏的 path、返回的 pattern 和结果类别，通常足以回答“选路是否符合预期”。

请求的哪些字段会影响预览结果

ServeMux.Handler 会结合 r.Method、r.Host 和 r.URL.Path 进行选择。也就是说，同一个 mux 上，换一个 method 或 host，预览结果可能不同；不能只拿 path 字符串去猜。

Host 匹配时会忽略端口。普通请求的 path 和 host 按路由匹配规则参与判断；CONNECT 请求是一个需要单独留意的边界，文档明确说明 path 和 host 会按 CONNECT 的方式保持不变。做测试时，应该用真实意图构造 http.Request，不要只改一处字段却保留与场景不相称的请求状态。

直接命中和规范化重定向要分开看

路由预览最容易误判的地方，是把返回的 pattern 一律当成“当前 URL 已经直接命中”。当路径不是规范形式时，ServeMux 可能返回内部生成的重定向处理器；这时 pattern 表示重定向后会匹配的规范路径，而不是一次普通注册命中。

// classifyPreview 把返回值转换成便于日志聚合的类别。
func classifyPreview(mux *http.ServeMux, r *http.Request) string {
	h, pattern := mux.Handler(r)
	if pattern == "" {
		// 空 pattern 仍可能对应非空的404或405处理器。
		return fmt.Sprintf("fallback handler=%T", h)
	}
	if r.URL.Path != pattern {
		// 路径与pattern不同，只能提示可能存在规范化或路径形态差异。
		return fmt.Sprintf("selected pattern=%q path=%q", pattern, r.URL.Path)
	}
	return fmt.Sprintf("selected pattern=%q", pattern)
}

这里的比较适合做粗粒度日志，但不要把 r.URL.Path != pattern 当成官方的重定向判定 API。更严谨的做法是把 handler 类型和实际响应行为交给专门测试确认；Handler 本身只承诺返回“将使用的 handler”和对应 pattern。

另外，pattern 为空时，可能是“没有任何注册模式适用”，也可能是 method 不支持。两个场景都需要结合请求 method、测试断言或响应语义进一步区分，不能仅凭空字符串下结论。

空 pattern 不等于空 handler

这是我最常见的一个小误读：拿到空 pattern 后顺手判断 h == nil，然后把它当成 ServeMux 没找到处理器。官方契约恰恰相反，Handler 总是返回非空 handler；无匹配时它会返回内部的“page not found”或“method not supported”处理器，pattern 才为空。

// previewResult 把空pattern保留为可观察状态，而不是伪造一个nil handler。
func previewResult(mux *http.ServeMux, r *http.Request) (string, http.Handler) {
	h, pattern := mux.Handler(r)
	if pattern == "" {
		// 调用方可以把空pattern交给统一的404/405分类逻辑。
		return "no-registered-pattern", h
	}
	return pattern, h
}

如果业务只想记录“有没有命中自己的注册模式”，判断 pattern != "" 比判断 handler 是否为空更合适。如果还要区分 404 与 405，应通过真实响应层或明确的测试样例分开记录。

Handler 不会替你填充 PathValue

Go 的新式路径模式可以包含 named wildcard，但调用 mux.Handler(r) 只是在做路由选择，不会把 wildcard 值写入请求。因此即使 pattern 已经显示为包含变量的模式，紧接着读取 r.PathValue("id") 也不能得到“刚刚匹配出来的值”。

// 只做路由预览；这里故意不把PathValue当成预览结果的一部分。
func previewWithoutPathValue(mux *http.ServeMux, r *http.Request) {
	h, pattern := mux.Handler(r)
	_ = h
	fmt.Printf("pattern=%q pathValue=%q\n", pattern, r.PathValue("id"))
	// Handler不会填充named wildcard，PathValue不能用来证明预览已执行派发。
}

如果真正进入注册处理器，处理器内部可以按正常派发流程读取路径值；但“预览路由”和“执行处理器”是两个阶段。把它们混在一个调试函数里，往往会让测试既有路由判断又有业务副作用，最后很难判断失败来自哪一层。

把这个模式放进日志和测试时的判断清单

ServeMux.Handler 适合做路由观察器，尤其适合在中间件日志、表驱动路由测试和问题复现工具中输出选择结果。它的价值在于复用 ServeMux 自己的匹配规则，而不是在业务代码中重新实现一套字符串比较。

• 要看请求将选择谁：调用 h, pattern := mux.Handler(r)。
• 要判断是否有自己的注册模式：先看 pattern 是否为空。
• 要排查重定向：关注非规范 path、返回 handler 和规范化后的 pattern，不把字符串差异直接等同于重定向。
• 要识别 method 不支持：为不支持的 method 写单独测试，不把空 pattern 直接归类为 404。
• 要拿 wildcard 值：不要依赖 Handler 预览，必须在真正的 handler 执行阶段处理。
• 要避免副作用：预览阶段不调用 h.ServeHTTP，也不把它当成响应生成器。

一句话总结：ServeMux.Handler 返回的是“这条请求会选中的处理器和模式”，不是一次派发结果。把 handler、pattern、空 pattern、规范化重定向和 PathValue 分开理解，路由日志和测试就不会因为一个看似简单的返回值而误判。

常见问题

ServeMux.Handler 返回的 handler 可以直接执行吗？

技术上它是可调用的 handler，但路由预览场景不应为了观察结果而执行它；执行可能写响应或触发业务副作用。

pattern 为空时是不是 handler 为 nil？

不是。Handler 的契约是始终返回非空 handler；空 pattern 表示没有适用的注册模式，可能对应 404 或 405 处理器。

为什么匹配到 wildcard 之后 PathValue 还是空？

因为 Handler 不修改请求，也不会填充 named wildcard。PathValue 应在真正进入注册处理器后读取。