net/http ServeMux 方法与路径模式的匹配设计

如果你把 ServeMux 当成“注册顺序决定结果”的字符串表，排查路由时很容易走偏。更稳妥的理解是：一个模式可以同时约束 HTTP 方法、Host 和路径；请求进入后，ServeMux 会在匹配的模式中选择覆盖请求集合更小、也就是更具体的那个。

本文只讨论标准库 net/http 的新式模式语法。实际设计时，先把模式写成 [METHOD ][HOST]/[PATH]，再检查路径段和方法边界，最后处理 404、405、重定向与版本兼容。

一、先把 ServeMux 模式拆成方法、主机和路径

模式的三部分都是可选的，/ 本身也是合法模式。没有方法表示所有方法；没有 Host 表示所有主机；没有额外限制的路径会覆盖更大的请求集合。

代码注册时，方法后必须至少有一个空格或制表符。建议把公共兜底模式 / 放在注册清单的最后阅读，而不是依赖注册顺序：真正决定结果的是匹配集合的具体程度。

二、路径段决定通配范围，PathValue 只读取命名段

普通字面量按大小写敏感的路径段匹配。{name} 只匹配一个路径段，{name...} 匹配剩余路径并且只能出现在模式末尾；{$} 则只匹配 URL 的结尾。

例如，下面的三个注册分别表达“单个对象”“对象下的任意剩余层级”和“集合根路径”。代码中的中文注释说明了读取值和资源边界，示例没有依赖第三方路由器。

package main

import (
	"fmt"
	"net/http"
)

func main() {
	mux := http.NewServeMux()

	// 单段通配符只承接一个对象 ID，避免把下一级路径吞掉。
	mux.HandleFunc("GET /orders/{id}", func(w http.ResponseWriter, r *http.Request) {
		// PathValue 读取模式中的命名段，空值仍应交给业务层决定是否 404。
		fmt.Fprintf(w, "order=%s\\n", r.PathValue("id"))
	})

	// 多段通配符承接对象下的剩余路径，只能放在模式末尾。
	mux.HandleFunc("GET /assets/{path...}", func(w http.ResponseWriter, r *http.Request) {
		// path 可能包含斜杠，处理文件系统映射时仍要单独做权限边界。
		fmt.Fprintf(w, "asset=%s\\n", r.PathValue("path"))
	})

	// {$} 只表示集合根，不会把 /orders/123 也当成根请求。
	mux.HandleFunc("GET /orders/{$}", func(w http.ResponseWriter, r *http.Request) {
		// 这里适合返回集合入口，而不是解析某个订单 ID。
		fmt.Fprintln(w, "orders root")
	})

	_ = http.ListenAndServe(":8080", mux) // 示例省略启动错误上报，生产环境应记录 err。
}

路径匹配按段进行解码，所以编码斜杠不会简单等同于路由分隔符。涉及文件、对象名或外部标识时，不要把 PathValue 当成已经完成授权和规范化的结果。

三、用“请求集合更具体”理解优先级、冲突和异常

当多个模式都匹配时，ServeMux 选择匹配请求集合的严格子集。例如 /images/thumbnails/ 比 /images/ 更具体。方法也参与具体性判断，GET / 只覆盖 GET 和 HEAD，而无方法的 / 覆盖所有方法。

如果两个模式互不包含，ServeMux 会认为它们冲突；把第二个冲突模式注册进同一个 mux 会 panic。这个行为意味着路由表应该在启动阶段保持清晰，不能把“先注册哪个”当成消除冲突的技巧。

排查时可以按下面的生命周期判断：

• 没有任何适用模式：通常得到内部 404 处理器；
• 路径匹配但方法不适用，同时存在其他方法的处理器：得到 405，并由框架生成允许方法信息；
• 子树模式以斜杠结尾，而请求访问子树根却缺少斜杠：默认会重定向到带斜杠的路径；若另行注册无斜杠精确模式，可以覆盖这个行为。

因此，看到“接口返回 405”时，先不要只检查路径；看到“多了一次 301/308”时，也不要立即把它归因于业务中间件，尾斜杠子树本身就可能触发规范化。

四、Go 1.22 之后的兼容清单

ServeMux 的模式语法和匹配行为在 Go 1.22 有明显变化。新代码可以使用命名通配符、PathValue 和方法模式；如果老项目必须暂时维持旧行为，可以在进程启动时设置 GODEBUG=httpmuxgo121=1，但这个设置只在启动时读取，运行中修改不会生效。

上线前建议把路由表按“方法 + 主机 + 路径”列成清单，并逐项确认：通配符是否完整占据一个路径段、{name...} 是否位于末尾、集合根是否需要 {$}、是否有意接受 HEAD，以及无方法兜底模式是否会扩大覆盖范围。注册冲突应在启动阶段暴露，而不是靠线上请求猜测。

常见问题

为什么注册两个看起来不同的模式仍然 panic？

因为 ServeMux 比较的是它们覆盖的请求集合，而不是字符串外观。如果双方都能匹配一部分请求、又没有严格的包含关系，就属于冲突。

GET 模式为什么能处理 HEAD？

标准库把带 GET 的模式视为同时覆盖 GET 和 HEAD；如果业务必须区分响应行为，应在处理器内部检查方法，而不是再注册一个会产生冲突的重复路径。