Go http.ServeMux 如何让子路由继承方法匹配规则

我第一次把 Go 服务从自写的路径判断换成 http.ServeMux 时，最容易误解的就是“子路由继承父路由的方法”。准确说，ServeMux 不会把父路由的配置复制给每个子路由；带尾斜杠的父模式会覆盖一棵路径子树，而更具体的子模式会在重叠时胜出。方法也必须写在实际模式里。

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

想让子路由稳定继承父级的路径范围，父级使用 /api/ 这样的子树模式；想让某个子路由只接受 GET，就显式注册 GET /api/users。最终选择遵循“匹配集合更小者优先”，与注册先后无关。

先把父路由和子路由写成可比较的模式

在生产代码里，我会先把“宽范围兜底”和“具体资源入口”分开写。父级的 /api/ 是子树模式，能覆盖 /api/users、/api/orders/42 等路径；精确的 /api/users 只覆盖这一条路径。下面的注册关系表达的是静态范围，不是注册顺序：

mux := http.NewServeMux()

// 父级子树模式承接没有更具体匹配的 /api/ 子路径。
mux.HandleFunc("GET /api/", apiRead)
mux.HandleFunc("POST /api/", apiWrite)

// 具体子路由只对自己的路径和方法负责。
mux.HandleFunc("GET /api/users", listUsers)
mux.HandleFunc("GET /api/users/{id}", getUser)

这里的 /api/、/api/users、GET /api/、GET /api/users、请求路径、具体性 和 Handler 构成了第一层判断：请求路径同时落入多个范围时，范围更窄的模式优先。于是 GET /api/users 不会被父级的 GET 处理器抢走；没有单独注册的其他子路径，才回到父级子树。

用方法和路径的具体性决定最终处理器

方法匹配可以看成另一层范围。对 GET /api/users 来说，它比无方法的 /api/ 更窄，所以会优先；对 POST /api/users 来说，如果没有 POST 的具体子路由，就会尝试 POST /api/。这就是大家口中的“继承”：继承的是父级子树的覆盖范围，不是把 GET 或 POST 隐式灌入子路由。

因此不要用多个“看起来差不多”的无方法模式碰运气。Go 1.22 之后，ServeMux 依据模式表示的请求集合选择更具体者；两个模式互相覆盖、却没有谁更具体时，注册阶段可能直接产生冲突 panic。

用通配符承接真正的动态子路由

用户 ID 这种动态段不要再手工切字符串。{id} 只匹配一个路径段，处理器通过 PathValue 取值；如果要承接剩余多段路径，可使用结尾的 {path...}。

func getUser(w http.ResponseWriter, r *http.Request) {
	// PathValue 读取 GET /api/users/{id} 捕获的一段动态路径。
	id := r.PathValue("id")
	if id == "" {
		// 空值通常意味着模式或请求路径没有按预期绑定。
		http.Error(w, "missing user id", http.StatusBadRequest)
		return
	}
	fmt.Fprintf(w, "user=%s", id)
}

这里不要把 /api/users/{id} 当成 /api/users/ 的文字替换。前者要求固定的两级路径并捕获一段，后者是更宽的子树范围；二者职责不同，读者也更容易从模式本身看懂路由表。

用 405 和 Allow 判断方法是否漏配

排查时先看状态码而不是马上改父级路径。如果路径能匹配到某个方法模式，但当前请求方法没有处理器，ServeMux 会返回 405 Method Not Allowed，并通过 Allow 头列出可用方法。若完全没有路径匹配，通常则是 404。这个差异能快速说明问题是在路径还是在方法注册。

还要记住 GET 的特殊规则：它会匹配 GET 和 HEAD。若接口只想允许 GET 语义，通常不必重复注册 HEAD；若需要独立的 HEAD 行为，再显式写出单独模式。生产日志里可以把请求方法、r.Pattern 和响应状态放在一起记录，方便确认究竟是父级还是子级处理器接住了请求。

上线前检查重叠模式和尾斜杠

最后我会做一张小的路由清单：每个子树是否以 / 结尾，动态段是否只出现一次，方法是否显式声明，是否存在两个都能匹配却无法比较具体性的模式。尤其要区分 /api 与 /api/：注册了子树后，请求没有尾斜杠的根路径可能被重定向到带尾斜杠的形式；如果只想匹配 /api/ 本身，可以考虑 /api/{$}。

我的经验是把“父级兜底、具体子级、动态资源、异常方法”分别列出，再启动服务。这样方法继承关系是可读的，注册顺序也不会成为隐藏依赖。

相关问题

子路由不写 GET，会自动继承父路由的 GET 吗？

不会自动复制方法。只有请求仍然落在父级子树范围内时，父级的 GET 模式才可能处理它；子路由若要限定 GET，应显式注册对应模式。

为什么 GET 注册后 HEAD 也能访问？

这是 ServeMux 的专门规则：GET 模式同时匹配 HEAD。其他方法不会因为路径相同而自动互相继承。

两个路由都匹配时，谁先注册谁生效吗？

不是。ServeMux 按匹配集合判断具体性；如果两个模式互不更具体，注册时会被视为冲突，应改成边界清楚的模式。