Go ServeMux 注册通配符后怎么读取路径参数

在 Go 1.22 及以上版本里，ServeMux 的命名通配符不是靠手动切字符串读取，而是直接调用 r.PathValue("参数名")。例如注册 GET /users/{id} 后，请求 /users/u-42 会让 r.PathValue("id") 返回 u-42。如果拿到空字符串，优先检查请求是否真的经过这个 ServeMux，以及读取的名字是否和模式完全一致。

最小可用写法是：在 ServeMux 模式中声明 {id}，在对应处理器里使用 r.PathValue("id")。需要跨越多个路径段时改用末尾的 {path...}。

Go ServeMux 通配符与 PathValue 的最小写法

先把路由模式和参数名写在一起，再在处理器内部读取同名参数。下面的示例只做一件事：从用户路径中取出 id，并把它放进响应。代码中的 GET 方法前缀和命名通配符都属于 Go 1.22 引入的新版 ServeMux 模式语法。

package main

import (
	"fmt"
	"net/http"
)

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

	// {id} 是命名通配符，只占用 /users/ 后面的一个路径段。
	mux.HandleFunc("GET /users/{id}", func(w http.ResponseWriter, r *http.Request) {
		id := r.PathValue("id")
		if id == "" {
			// 空参数通常表示模式或分发链路没有按预期生效。
			http.NotFound(w, r)
			return
		}
		fmt.Fprintf(w, "user=%s", id)
	})

	// 让 ServeMux 负责匹配模式并把命名参数写入请求。
	if err := http.ListenAndServe(":8080", mux); err != nil {
		panic(err)
	}
}

访问 http://localhost:8080/users/u-42 时，处理器会得到 u-42。这里不要改成读取 r.URL.Query().Get("id")：查询参数和路径参数是两套输入，前者对应 /users?id=u-42，并不会读取 /users/u-42 中的内容。

单段参数和剩余路径要用不同通配符

普通通配符只匹配一个路径段，遇到下一个斜杠就结束；末尾带三个点的通配符用于读取剩余路径。文件、对象键和文档路径这类参数，经常需要后者。

mux.HandleFunc("GET /files/{path...}", func(w http.ResponseWriter, r *http.Request) {
	// {path...} 必须位于模式末尾，返回 docs/go/route.md 这样的剩余路径。
	path := r.PathValue("path")
	if path == "" {
		// 空值代表没有匹配到命名通配符，不要把它当成根目录文件。
		http.NotFound(w, r)
		return
	}
	fmt.Fprintf(w, "file=%s", path)
})

可以用下面的表快速判断模式：

PathValue 返回的是未转义值。例如模式 /b/{bucket} 匹配 /b/a%2fb 时，读取结果是 a/b。这也是为什么不应在读取后再次用同样规则盲目解码。

路径参数为空时先检查路由分发边界

出现空值时，不要立即回到旧式的 strings.Split。先按下面的顺序排查：

1. 模式是否真的写了命名通配符，例如 {id}，而不是只注册了 /users/。
2. PathValue 的名字是否逐字匹配，PathValue("userID") 不会读取 {id}。
3. 请求是否通过 mux.ServeHTTP(w, r) 进入处理器。直接调用 mux.Handler(r) 只返回处理器和模式，不会填充命名通配符。
4. 是否把路径参数误当成查询参数，或者请求实际命中了另一个更具体的模式。

如果是自定义适配器先生成请求，再交给统一处理器，可以调用 r.SetPathValue("id", value) 写入值；但该方法不会自动转义传入内容，适配器应先明确自己的编码约定。

Go 1.22 之后的兼容与上线检查

新版 ServeMux 的通配符行为从 Go 1.22 开始生效。在 Go 1.21 中，/{id} 仍可能被当作普通字面路径；升级后它会变成单段通配符，原来依赖字面匹配的路由需要重新检查。新版还按路径段处理转义字符，包含 %2F 的对象键尤其值得补一条测试。

上线前可以留一张小清单：

• 版本：go.mod 与构建机使用的 Go 版本都支持目标模式。
• 模式：多段参数使用末尾 {name...}，不要把它放在中间。
• 分发：服务器的 Handler 指向注册过模式的同一个 ServeMux。
• 路径：补测普通字符、空参数、斜杠和转义斜杠的行为。

如果必须暂时兼容旧版匹配行为，官方文档提供了 GODEBUG=httpmuxgo121=1 的过渡开关；它在程序启动时读取，不适合作为运行中动态切换方案。更稳妥的做法是把路由模式和参数读取一起迁移，并保留请求级测试。

常见问题

PathValue 为什么一直返回空字符串？

最常见原因是请求没有命中带命名通配符的模式，或者参数名拼写不一致。还要确认请求确实由注册该模式的 ServeMux 分发。

{id} 能匹配带斜杠的值吗？

不能。它只匹配一个路径段；需要读取多个段时，将模式改成末尾的 {id...}，并接受返回值包含斜杠。

还需要手动解析 URL.Path 吗？

使用新版 ServeMux 的命名通配符时通常不需要。手动解析会重复承担路由匹配、转义和边界处理，只有在兼容旧版路由或处理非 ServeMux 请求时才考虑保留。

相关事实可在 Go 标准库 Request.PathValue 与 ServeMux 文档中继续核对。