Go ServeMux 路径模式未命中的匹配规则

Go 的 http.ServeMux 没有命中预期处理器时，先不要只改字符串。Go 1.22 以后，模式同时包含方法、主机和路径；路径还要按段匹配，尾斜杠、通配符以及转义字符都会改变结果。最实用的排查顺序是：先确认请求方法和 Host，再逐段对照 PATH，最后用 mux.Handler(req) 看 ServeMux 认为哪条模式匹配。

官方地址：https://pkg.go.dev/net/http#ServeMux

如果请求路径“看起来一样”却没有命中，优先检查模式是否把精确路径误写成子树、通配符是否占完整路径段，以及请求是否被尾斜杠重定向或按方法判定为 405。

先把 ServeMux 模式拆成三部分

ServeMux 的模式可以写成 [METHOD ][HOST]/[PATH]。三部分都可以省略，只有路径的 /orders 表示任意方法、任意主机下的精确路径；GET /orders/{id} 则增加了方法限制和一个路径通配符。

package main

import "net/http"

func register(mux *http.ServeMux) {
	// 只匹配精确路径 /health，不会覆盖 /health/live。
	mux.HandleFunc("/health", func(w http.ResponseWriter, r *http.Request) {})

	// GET 也包含 HEAD；其他方法必须精确相同。
	mux.HandleFunc("GET /orders/{id}", func(w http.ResponseWriter, r *http.Request) {})

	// 主机写入模式后，只接受 api.example.com 这个主机。
	mux.HandleFunc("api.example.com/metrics", func(w http.ResponseWriter, r *http.Request) {})
}

因此，先问三个问题：请求方法是不是模式要求的方法？Host 是否符合？路径段的数量和字面内容是否一致？这三项中任意一项不满足，后面的“更具体模式”规则都不会帮你补救。

精确路径、子树路径和 {$} 不是一回事

不带尾斜杠的路径通常是精确匹配。/api 只对应 /api，不会自然覆盖 /api/users。以斜杠结尾的 /api/ 表示子树前缀，能够匹配它下面的路径；请求 /api 时，ServeMux 默认会把它重定向到 /api/，除非你另外注册了 /api。

如果只想匹配带尾斜杠的根节点，可以用 /api/{$}。它不会匹配 /api，也不会匹配 /api/users。这个写法适合需要把“集合入口”和“集合子路径”分开处理的场景。

package main

import "net/http"

func routes() *http.ServeMux {
	mux := http.NewServeMux()

	// 精确匹配 /api；/api/users 不会进入这个处理器。
	mux.HandleFunc("/api", func(w http.ResponseWriter, r *http.Request) {})
	// 子树匹配 /api/ 以及后面的路径段。
	mux.HandleFunc("/api/", func(w http.ResponseWriter, r *http.Request) {})
	// 仅匹配带尾斜杠的 /docs/ 根节点。
	mux.HandleFunc("/docs/{$}", func(w http.ResponseWriter, r *http.Request) {})
	return mux
}

排障时要把客户端是否自动跟随重定向也算进去。服务端的第一响应可能是 301/307，而客户端继续请求后的最终路径才进入子树处理器；如果你观察的是最终结果，容易误以为原始模式直接命中了。

通配符必须占据完整路径段

{id} 只匹配一个路径段，遇到下一个字面斜杠就结束；{path...} 匹配剩余路径，并且只能出现在模式末尾。通配符名称必须是合法 Go 标识符，不能把它嵌在普通文字中。

package main

import "net/http"

func wildcardRoutes() *http.ServeMux {
	mux := http.NewServeMux()

	// /users/42 可以命中；/users/42/profile 不符合单段边界。
	mux.HandleFunc("/users/{id}", func(w http.ResponseWriter, r *http.Request) {
		// PathValue 返回已解码的 id；空字符串仍需结合业务规则判断。
		id := r.PathValue("id")
		_ = id
	})

	// /files/a/b.txt 可以命中，余下路径包含中间的斜杠。
	mux.HandleFunc("/files/{path...}", func(w http.ResponseWriter, r *http.Request) {
		// 余下路径只能从这个末尾通配符读取。
		path := r.PathValue("path")
		_ = path
	})
	return mux
}

常见误写是 /users/{id}/profile 与 /users/42/profile 进行对照时，把 {id} 当成“任意剩余字符串”。它只代表一个段；如果要接收后面的多个段，应把 {rest...} 放在最后，例如 /users/{id}/files/{rest...}。

方法不匹配时可能是 405，Host 不匹配时则不会命中

模式没有方法时匹配所有方法；写成 GET 时还包含 HEAD，其他方法不会自动放行。如果路径与某条模式相同，但请求方法不允许，Go 1.22 的 ServeMux 可以返回 405，并通过 Allow 告知可用方法。把“没进处理器”直接判断成 404，会漏掉这类情况。

Host 模式是另一层限制。api.example.com/ 只接收该主机；Host 中的端口会在匹配时忽略。反向代理没有正确转发 Host，或本地请求使用了 localhost，都可能让路径看起来正确却落不到带 Host 的模式。

package main

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

func methodAndHostExample() {
	mux := http.NewServeMux()
	// GET 模式也允许 HEAD，但不会接收 POST。
	mux.HandleFunc("GET api.example.com/reports/{name}", func(w http.ResponseWriter, r *http.Request) {})

	// 用测试请求明确设置方法和 Host，避免排查时只看 URL。
	req := httptest.NewRequest(http.MethodPost, "https://api.example.com/reports/daily", nil)
	// Handler 返回的是 ServeMux 选择的处理器和模式，不会填充 PathValue。
	handler, pattern := mux.Handler(req)
	_ = handler
	_ = pattern
}

这段代码只是展示检查维度：实际服务中仍由 ServeHTTP 负责分发。若请求方法、Host 和路径都符合预期，却得到 405 或默认处理器，先把请求对象的三个维度打印到你自己的诊断日志中，再对照注册模式。

百分号转义和路径清理会改变段的含义

ServeMux 按路径段逐段解码，而不是先把整条路径当成一个字符串。%2F 在一个段内部仍可表示斜杠字符，但不会凭空变成新的分隔符；所以 /a%2Fb/100%25 会被看成两个段，不能拿 /a/b/ 的三段直觉去比较。

同时，ServeMux 会清理重复斜杠以及 .、.. 段，并可能将请求重定向到规范路径。若业务必须保留原始编码形式，先确认上游是否已经解码或规范化，再决定模式应该写字面值还是按段匹配。

这里尤其要避免把“URL 显示相同”当成“路由输入相同”：浏览器、代理、测试客户端和 Go 的 URL.Path 可能分别保留或解码不同层次的内容。

用 mux.Handler 看 ServeMux 实际选了什么

ServeMux.Handler 会依据请求的 Method、Host 和 URL.Path 返回处理器与已匹配的模式。路径不规范时，它也可能返回内部重定向处理器和规范化后的模式；没有适用注册项时，返回默认的未找到或方法不支持处理器，模式字符串为空。

package main

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

func explain(mux *http.ServeMux, method, target string) {
	req := httptest.NewRequest(method, target, nil)
	// Handler 只用于判断选中的模式；它不会为请求填充命名通配符。
	handler, pattern := mux.Handler(req)
	if pattern == "" {
		// 空模式表示没有找到已注册的适用模式，或进入方法不支持处理器。
		fmt.Printf("method=%s host=%s path=%s handler=%T pattern=\n", method, req.Host, req.URL.Path, handler)
		return
	}
	fmt.Printf("method=%s host=%s path=%s pattern=%q handler=%T\n", method, req.Host, req.URL.Path, pattern, handler)
}

这个检查能快速回答“到底没有匹配，还是匹配到了另一条更具体模式”。注意 Handler 本身不会填充 PathValue；只有真正通过 ServeHTTP 分发到处理器的请求，才按处理模式提供通配符值。

最具体模式优先，但冲突模式不能靠注册顺序解决

当多条模式都能匹配时，ServeMux 选择匹配请求集合更小的“最具体”模式。例如 /images/thumbnails/ 比 /images/ 更具体。方法限制也参与具体性判断，GET /posts/{id} 比不限制方法的 /posts/{id} 更具体。

如果两条模式互相覆盖、却没有谁是另一条的严格子集，注册时会被视为冲突并 panic，而不是用“后注册覆盖前注册”的规则解决。尤其不要把通配符名字改掉当成避开冲突的方法；名字不改变它匹配的请求集合。

从 Go 1.21 升级到 1.22 时还要注意：大括号从普通字面量变成通配符语法，非法模式可能在注册时 panic，路径段解码规则也发生了变化。若必须暂时保持旧行为，可以了解 GODEBUG=httpmuxgo121=1 的兼容开关，但更稳妥的是逐条检查旧模式是否表达了新的意图。

一张速查表定位“为什么没命中”

结语：先判断集合边界，再修改模式

ServeMux 的路径未命中通常不是“少写了一个通配符”这么简单。把模式看成请求集合：精确路径限制集合，尾斜杠扩大到子树，单段通配符只覆盖一个段，... 才覆盖余下路径；方法和 Host 又会进一步缩小集合。配合 mux.Handler 打印实际选择的模式，基本可以把 404、405、重定向和冲突分开处理。

相关问题

• 为什么注册 / 后很多路径都能进入同一个处理器？ 因为它是覆盖范围很大的根模式；如果只处理首页，应在处理器内判断路径，或使用更精确的 /{$}。
• GET 模式是否需要再注册 HEAD？ 通常不需要，ServeMux 的 GET 模式也匹配 HEAD。
• mux.Handler 返回空模式就一定是 404 吗？ 不一定，方法不支持处理器也可能对应空模式，要结合响应状态和 Allow 头判断。
• 能否通过调整注册顺序解决模式冲突？ 不能。冲突模式会在注册时 panic，应该改变请求集合或删除重叠注册。