net/http ServeMux 路径模式怎么区分尾斜杠

在 Go 的 net/http.ServeMux 中，路径最后有没有斜杠，不只是格式问题：它会改变模式代表的是“一个精确路径”还是“一个子树”。最容易混淆的是 /docs、/docs/ 和 /docs/{$}。按 Go 1.22 及之后的模式语义，可以先记住一句话：不带斜杠通常表示精确路径，带斜杠表示子树，{$} 才能把带尾斜杠的路径收紧为精确匹配。

如果希望 /docs 和 /docs/ 分别处理，就分别注册；如果希望只匹配带尾斜杠的根路径，就使用 /docs/{$}，不要把 /docs/ 当成精确路径。

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

先把三个路径模式分开

ServeMux 的模式可以理解成请求集合。/docs 只对应路径为 /docs 的请求；/docs/ 表示以该前缀开头的子树，因此 /docs/、/docs/api 和 /docs/api/v1 都可能落入它；/docs/{$} 则只对应完整路径 /docs/。

这三个模式并不是换一种写法而已。前两个的边界差异决定了是否允许继续向下匹配，最后一个则把“尾斜杠存在”变成了路径条件。

为什么 /docs 会被补成 /docs/

当你注册 /docs/ 时，ServeMux 把它视为一个子树入口。请求 /docs 缺少子树模式期待的尾斜杠，因此标准库会返回一个重定向，让客户端访问规范形式 /docs/。这也是很多人看到“明明没有写 /docs，为什么请求被跳转”的原因。

如果 /docs 本身也有业务含义，例如它是一个不跳转的目录摘要页，可以把无斜杠路径单独注册。这样它和 /docs/ 子树就分别承担两个入口：

package main

import (
	"fmt"
	"net/http"
)

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

	// 不带尾斜杠的注册只负责 /docs 这个精确路径。
	mux.HandleFunc("/docs", func(w http.ResponseWriter, r *http.Request) {
		fmt.Fprintln(w, "docs index without slash")
	})
	// 带尾斜杠的注册负责 /docs/ 及其下级路径。
	mux.HandleFunc("/docs/", func(w http.ResponseWriter, r *http.Request) {
		fmt.Fprintln(w, "docs subtree")
	})

	_ = http.ListenAndServe(":8080", mux) // 示例只展示注册关系，生产代码应处理启动错误。
}

这里的重点不是响应文字，而是两个模式的职责。若只注册 /docs/，就接受标准库的尾斜杠规范化；若额外注册 /docs，就把这个重定向入口变成了独立处理路径。

用 {$} 表达真正的尾斜杠边界

有时你需要的不是“整个 docs 子树”，而是只处理目录根 /docs/，让更深的路径交给别的模式。这时使用 /docs/{$}。其中 {$} 是特殊的末尾匹配标记，表示 URL 必须在这里结束。

mux := http.NewServeMux()

// {$} 把匹配范围收紧到完整的 /docs/，不会接收 /docs/api。
mux.HandleFunc("/docs/{$}", func(w http.ResponseWriter, r *http.Request) {
	fmt.Fprintln(w, "exact docs slash")
})

// 子树模式仍然可以单独承担更深路径。
mux.HandleFunc("/docs/api/", func(w http.ResponseWriter, r *http.Request) {
	fmt.Fprintln(w, "docs api subtree")
})

可以把选择压缩成一张表：

迁移和排查时看哪些边界

第一，确认项目的 Go 版本。ServeMux 的方法、通配符和精确尾部匹配语义在 Go 1.22 有过增强；如果旧项目依赖 1.21 的旧模式行为，升级时要把带花括号的旧字符串和路径转义规则列入回归范围。

第二，不要把根模式 / 当成只匹配首页。它是一个广泛的兜底模式；若只想匹配网站根路径，应使用 /{$}。否则一个本应返回 404 的路径，可能会被首页处理函数接住。

第三，注册重叠模式时按“更具体者优先”理解。/docs/api/ 比 /docs/ 更具体，而两个无法判断谁更具体的模式会在注册时产生冲突。排查时先列出每个模式覆盖的请求集合，再看是否需要把根入口写成 {$}。

最后，第三方路由器有自己的斜杠策略，不能把 ServeMux 的自动重定向规则直接迁移过去。本文只讨论标准库 ServeMux：精确路径用无斜杠模式，子树用尾斜杠模式，精确尾斜杠用 {$}。

相关问题

只注册 /docs/，请求 /docs 一定会跳转吗？

在 ServeMux 的标准子树语义下，会生成带尾斜杠的规范化重定向；如果同时注册了 /docs，这个精确路径可以由自己的处理函数接收。

/docs/{$} 能匹配 /docs 吗？

不能。它要求尾斜杠存在，/docs 与 /docs/ 是两个不同的路径边界。