Go ServeMux 怎样读取路径通配符的 PathValue

Go ServeMux 读取路径通配符的做法是：在路由中声明 {名称}，在匹配后的处理器里调用 r.PathValue("名称")。例如资源架上的物品接口 GET /shelves/{shelf}/items/{item}，处理器分别用 PathValue("shelf") 和 PathValue("item") 取得两个字符串。

PathValue 读取的是路由命名捕获值。参数名需要与模式一致；查询字符串应从 URL.Query 读取。先让请求经过 ServeMux 匹配，再在处理器里取值。

该能力从 Go 1.22 引入，以下示例使用这一套路由语义，并未在这里实际启动服务。官方文档：https://pkg.go.dev/net/http。

先把路径拆分交给 ServeMux

维护一个资源详情接口时，手动裁掉路径前缀、按斜杠切分、再检查段数，容易让处理器同时承担路由与业务约束。命名通配符将“哪一个位置属于哪个字段”放在路由声明中，处理器只需要读取字段并检查其业务含义。这是 Go 1.22 路由增强的实际价值。

示例路由中的 shelf 是资源架标识，item 是物品标识；它们都只是字符串，不自动关联任何数据库，也不自动确认当前用户是否有权查看资源。名称只是模式中的稳定标识，读取时不要写成带花括号的 PathValue("{item}")。

用资源详情接口读取命名值

下面是一份独立的 main.go 阅读示例。两个命名字段都在路由内声明，查询参数 view 只控制展示视图，不参与路径标识。斜杠限制是这个接口自行制定的字段规则，并非 ServeMux 自动附带的业务限制。

package main

import (
    "encoding/json"
    "log"
    "net/http"
    "strings"
    "time"
)

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

    // 路由负责定位两个路径段；处理器负责业务字段约束。
    mux.HandleFunc("GET /shelves/{shelf}/items/{item}", func(w http.ResponseWriter, r *http.Request) {
        shelf := r.PathValue("shelf")
        item := r.PathValue("item")
        // 解码后的值可能包含斜杠，这个示例要求标识符不能包含它。
        if shelf == "" || item == "" || strings.ContainsAny(shelf+item, "/\\") {
            http.Error(w, "invalid resource identifier", http.StatusBadRequest)
            return
        }
        w.Header().Set("Content-Type", "application/json; charset=utf-8")
        if err := json.NewEncoder(w).Encode(map[string]string{
            "shelf": shelf,
            "item": item,
            "view": r.URL.Query().Get("view"),
        }); err != nil {
            // 响应可能已经写出，此处记录错误，不再追加另一份错误响应。
            log.Printf("encode response: %v", err)
        }
    })

    // 仅作为本机阅读示例，实际服务另行配置超时、鉴权与存储查询。
    server := &http.Server{
        Addr: "127.0.0.1:8080",
        Handler: mux,
        ReadHeaderTimeout: 5 * time.Second,
    }
    log.Fatal(server.ListenAndServe())
}

对路径 /shelves/reading/items/manual?view=compact，按示例逻辑，响应字段 shelf 对应 reading，item 对应 manual，view 对应 compact。这是由代码与路由规则推导的预期行为，并非实测输出。即使查询串额外带有 item=other，它也不会替换路径捕获的 item。

如果标识符要求正整数，应在取出字符串后另做解析并检查有效范围；如果是普通文本键，则按产品定义检查长度、允许字符与权限。本文保留文本标识，避免把字符串读取与数字转换混成一个问题。

区分单段、余段和解码后的字符串

{item} 捕获一个路径段；如果资源定位确实需要保留后续层级，可以另用末尾的 {rest...}。例如模式 GET /collections/{collection}/entries/{rest...} 中，collection 是单段名称，rest 是剩余路径，余段通配符必须放在模式末尾。它与本例资源架接口属于两种不同的数据约定。

尤其要注意，ServeMux 对匹配段进行 URL 解码后提供 PathValue。如果模式中 item 对应的请求段写成 a%2Fb，读到的字符串可以是 a/b；不能因为使用了单段通配符，就认定返回值绝不含斜杠。示例中的 ContainsAny 因此会拒绝这个标识。

取值后不要惯性地再做一次 PathUnescape，否则包含百分号转义字面内容的标识可能被再次解释。如果准备把值用于文件路径、数据库查询或授权判断，应继续按该用途处理，路径匹配本身不能替代这些约束。

旧代码迁移时保留真实的匹配入口

把旧路由 /shelves/ 的处理器改成 PathValue 取值，并不会自动声明 shelf 与 item。应同时改为明确的命名模式，并让请求通过注册该模式的 ServeMux。只创建一个 Request，随后直接调用处理器，不会触发路由匹配。

请求矩阵应覆盖完整入口。若以后编写路由测试，应把请求交给 mux.ServeHTTP；若只隔离处理器测试，可以明确使用 SetPathValue 注入字段，但那只说明处理器读字段的行为，不说明真实模式能够匹配。SetPathValue 也不替调用者进行 URL 解码。

版本方面，项目需要支持 Go 1.22 及之后的相关 API。若进程启用了 GODEBUG=httpmuxgo121=1，则恢复旧 ServeMux 行为，不能再按新命名通配符语义理解模式；这个设置在进程启动时读取。迁移时先统一运行环境和路由声明，再调整处理器。

如果在外层中间件里、调用 mux 之前就读取 PathValue，命名字段尚未由 mux 填好。将依赖字段的检查放到已匹配路由内部，或用包裹目标处理器的中间件。不要在外层读取失败后，改从查询参数补一个同名值来掩盖入口错误。

用请求矩阵检查取值边界与常见疑问

下面给出上述资源架接口的阅读检查表，可作为自行运行时的观察目标。这里没有增加余段路由，所有判断都针对完整示例。

PathValue 为空，是否表示 URL 里没有这个字符串？

不能这样判断。常见原因是名称拼错、模式没有这个名称、请求尚未经过匹配，或正在读取可以为空的余段。先核对声明与入口，再判断是否真的缺少业务值。

要不要先调用 ParseForm？

读取命名路径值不需要。表单解析与路由捕获是不同的数据入口；本例 view 通过 URL.Query 获取。

注册 GET 模式后，HEAD 会怎样？

ServeMux 的 GET 方法模式也匹配 HEAD。业务若依赖请求方法，应保留这一规则意识，不要把 GET 模式理解成只能接收 GET 字面方法。

已有第三方路由器可以直接换成 PathValue 吗？

先确认该路由器是否会设置标准 Request 的路径值。仅修改读取方法不会迁移第三方路由器自己的参数存储。可由适配层显式设置，但真实匹配语义仍由原路由器决定。

资源详情接口的核心分工是：模式定义位置和名称，PathValue 取得字符串，处理器定义字段是否合法以及谁能访问资源。保持这三处责任清楚，读取路径值就不必依赖手工切分 URL。

相关官方资料：https://pkg.go.dev/net/http#Request.PathValue；路由设计背景：https://go.dev/blog/routing-enhancements；版本说明：https://go.dev/doc/go1.22。