Go net/http ServeMux 路径参数怎么读取：通配符、清理规则与兼容写法

如果接口从旧式的 /users/ 路由迁移到带参数的 /users/{id}，Go 1.22 及以上版本可以直接让标准库 ServeMux 识别通配符，再用 r.PathValue("id") 取出路径参数。关键是记住它按路径段匹配：单段参数用 {id}，剩余路径用结尾的 {path...}，而转义后的斜杠不会自动变成新的段。

最小写法是注册 GET /users/{id}，在处理函数中读取 r.PathValue("id")；如果程序还要兼容 Go 1.21，先把路由语法和构建版本一起验收。

先把路径参数读取写到能验收

下面的例子把用户编号放进 URL，并同时检查空值。实际项目中，参数是否存在由路由保证，但格式校验仍属于业务层责任。

package main

import (
    "fmt"
    "net/http"
)

func main() {
    mux := http.NewServeMux()
    mux.HandleFunc("GET /users/{id}", func(w http.ResponseWriter, r *http.Request) {
        id := r.PathValue("id")
        if id == "" {
            http.Error(w, "missing user id", http.StatusBadRequest)
            return
        }
        fmt.Fprintf(w, "user=%s", id)
    })
    http.ListenAndServe(":8080", mux)
}

访问 /users/42 时，处理器得到的值是 42。建议在测试中直接用 httptest.NewRequest 和 httptest.NewRecorder，这样能同时验证状态码和响应体，而不是只看浏览器是否返回 200。

单段通配符和剩余路径不是一回事

/files/{name} 只匹配一个段，例如 /files/readme.txt；/files/{path...} 才能接住 /files/docs/go/net-http.md 这类多段路径。省略号通配符只能出现在模式末尾，放到中间会让路由注册直接失败。

mux.HandleFunc("GET /files/{path...}", func(w http.ResponseWriter, r *http.Request) {
    path := r.PathValue("path")
    fmt.Fprintln(w, path)
})

不要把 PathValue 当成原始 URL 字符串。官方规则会按段处理转义：请求里的 /files/a%2Fb 仍是一个名为 path 的值，读取后可能得到 a/b。如果下游把这个值当作文件名或对象键，还要继续做业务层的允许范围校验。

路由冲突和方法匹配要提前暴露

ServeMux 会按“更具体的模式优先”选择处理器。例如 GET /users/{id} 比仅有路径前缀的 /users/ 更具体。两个模式如果既不能互相包含，又没有明确优先级，就可能在注册时产生冲突。

方法也属于模式的一部分。注册 GET /users/{id} 后，GET 请求能命中；GET 还会按标准规则覆盖 HEAD。对 POST、PUT 等方法不要假设会自动复用 GET 处理器，最好分别写测试，确认不支持的方法得到预期的 405 或业务响应。

兼容 Go 1.21 时该怎么处理

命名通配符和 PathValue 是 Go 1.22 引入的 ServeMux 能力。在旧版本里，{id} 不是参数语法，可能只是普通文本；直接把新路由部署到旧编译环境，结果不是取不到参数，而是整个匹配模型不同。

短期过渡可以使用 GODEBUG=httpmuxgo121=1 恢复旧行为，但它需要在进程启动时确定，不能在服务运行中动态切换。更稳妥的迁移做法是：先把 go.mod、构建镜像和 CI 的 Go 版本统一到 1.22 以上，再用路由测试覆盖旧路径、新路径、错误方法和转义段。

一组小测试能挡住大多数回归

func TestUserRoute(t *testing.T) {
    mux := http.NewServeMux()
    mux.HandleFunc("GET /users/{id}", func(w http.ResponseWriter, r *http.Request) {
        fmt.Fprint(w, r.PathValue("id"))
    })

    req := httptest.NewRequest(http.MethodGet, "/users/a%2Fb", nil)
    rec := httptest.NewRecorder()
    mux.ServeHTTP(rec, req)

    if got := rec.Body.String(); got != "a/b" {
        t.Fatalf("path value = %q, want %q", got, "a/b")
    }
}

验收时至少检查四件事：单段参数是否取对，多段参数是否只在末尾生效，转义段是否按预期解码，旧版本构建是否被明确阻止。这里别只测一条 200 路径，路由迁移最容易漏掉的恰好是方法和边界。

常见问题

PathValue 读不到值通常是什么原因？

先确认请求确实经过这个 ServeMux，而不是被另一个处理器接管；再检查名称是否和模式中的通配符完全一致。调用 mux.Handler(r) 做诊断时不会填充命名通配符，因此不要用它的结果代替真实的 ServeHTTP 流程。

为什么通配符不能放在路径中间？

带省略号的通配符代表剩余所有路径段，只有放在末尾才有确定边界。中间再出现固定路径会造成语义不清，ServeMux 会在注册阶段拒绝这种模式。

项目还在 Go 1.21，能先写新模式吗？

不建议。先升级编译链并为路由补测试；如果暂时不能升级，应继续使用旧版 ServeMux 的显式路径解析方式，不能把 PathValue 当作兼容 API。

收尾：把路由语法当成接口契约

ServeMux 的新模式减少了手动切割 URL 的代码，但也把方法、通配符、转义和冲突规则变成了接口契约。把这些边界写进测试，再统一构建版本，路径参数才不容易在上线后变成一类难排查的 404。