Go http.Request.SetPathValue 怎样在测试中注入路径变量

在 Go 1.22 及更高版本里，如果处理器依赖 r.PathValue("id") 读取 ServeMux 路径变量，单元测试不必真的启动 HTTP 服务，也不必强行走一遍路由匹配。直接用 httptest.NewRequest 创建请求，再调用 SetPathValue 写入测试数据，处理器就能按生产代码的方式读取它。

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

先分清 PathValue 的两个来源

生产请求通常先经过 ServeMux 的模式匹配。例如模式 /users/{id} 命中后，标准库会把 id 的值提供给处理器，处理器再通过 r.PathValue("id") 取出它。单独调用处理器时没有这一步匹配，因此新建的测试请求读取不到任何命名路径变量，返回值就是空字符串。

SetPathValue(name, value) 就是为这种场景准备的测试和适配入口：它把指定名称和值保存到当前请求中，使之后的 PathValue(name) 返回该值。这个方法不会改变 URL.Path，也不会替你校验路径模式是否存在，所以它适合验证处理器逻辑，不适合代替路由器测试。

用 httptest.NewRequest 创建最小测试请求

请求本身只需要满足处理器的输入约定。使用 httptest.NewRequest 可以得到带有方法、URL 和上下文的服务端请求；如果处理器还会读取请求头或查询参数，再在这个对象上补充即可。这里不需要监听端口，也不需要创建真实客户端。

package handler_test

import (
    "net/http/httptest"
    "testing"
)

func TestUserHandler_readsPathValue(t *testing.T) {
    // 只创建服务端请求，路径先保留为处理器关心的基础 URL。
    req := httptest.NewRequest("GET", "/users/42", nil)

    // 测试目标是处理器读取变量，因此直接注入匹配后的值。
    req.SetPathValue("id", "42")

    if got := req.PathValue("id"); got != "42" {
        t.Fatalf("PathValue(id) = %q, want %q", got, "42")
    }
}

这个最小例子先验证注入和读取的契约。注意 SetPathValue 写的是请求内部的路径变量集合，不是把 42 拼回 URL，也不会改变 req.URL.Path 的文本。

在处理器测试中注入一个或多个变量

更常见的写法是把请求传给真正的处理器，并用 httptest.NewRecorder 接住响应。下面的处理器同时读取 scope 和 id，因此测试显式注入两个变量，避免测试依赖隐含的路由状态。

package handler_test

import (
    "fmt"
    "net/http"
    "net/http/httptest"
    "testing"
)

func userHandler(w http.ResponseWriter, r *http.Request) {
    scope := r.PathValue("scope")
    id := r.PathValue("id")

    // 缺少任一路径变量都视为请求不完整，避免拼出误导性的资源标识。
    if scope == "" || id == "" {
        http.Error(w, "missing path value", http.StatusBadRequest)
        return
    }

    // 这里仅输出处理器消费到的变量，方便测试断言结果。
    fmt.Fprintf(w, "%s:%s", scope, id)
}

func TestUserHandler_withInjectedPathValues(t *testing.T) {
    req := httptest.NewRequest("GET", "/users/42", nil)
    req.SetPathValue("scope", "admin")
    req.SetPathValue("id", "42")
    rec := httptest.NewRecorder()

    userHandler(rec, req)

    if rec.Code != http.StatusOK {
        t.Fatalf("status = %d, want %d", rec.Code, http.StatusOK)
    }
    if got := rec.Body.String(); got != "admin:42" {
        t.Fatalf("body = %q, want %q", got, "admin:42")
    }
}

每个变量都用自己的名称写入，处理器只通过公共的 PathValue 接口读取。这样测试关注的是“给定路径变量时，业务响应是否正确”，而不是把路由注册、匹配优先级和业务断言揉在同一个测试里。

什么时候应该让 ServeMux 参与测试

如果要验证的是模式是否正确、通配符名称是否拼写正确、方法匹配是否生效，就不要手动注入后直接调用处理器。此时应把处理器注册到 ServeMux，再让 mux 处理请求，因为只有它真正匹配请求后，路径变量才代表完整的路由行为。

func TestMux_populatesPathValue(t *testing.T) {
    mux := http.NewServeMux()
    mux.HandleFunc("GET /users/{id}", userHandler)

    req := httptest.NewRequest("GET", "/users/42", nil)
    rec := httptest.NewRecorder()

    // 让 ServeMux 完成模式匹配，测试路由层和处理器之间的真实连接。
    mux.ServeHTTP(rec, req)

    if rec.Code != http.StatusBadRequest {
        t.Fatalf("status = %d, want %d", rec.Code, http.StatusBadRequest)
    }
}

上面的路由只注册了 id，而处理器还要求 scope，所以响应会进入缺少变量的分支。这个结果正好说明两种测试的边界：手动 SetPathValue 用于处理器单元测试，真实 ServeMux 用于路由集成测试。

空值、覆盖和编码是最容易误判的地方

尤其要注意编码边界：官方文档说明 PathValue 从 ServeMux 匹配结果读取时会返回未转义的值，但 SetPathValue 本身不会解码传入字符串。测试中如果写入 "a/b"，读取到的就是 "a/b"；如果写入 "a%2Fb"，读取到的仍是 "a%2Fb"。

一套实用的测试拆分方式

可以把测试分成两层：第一层直接调用处理器，为每个用例创建独立请求并用 SetPathValue 注入数据，快速覆盖成功、空值和非法值；第二层通过 ServeMux.ServeHTTP 验证模式、方法和 URL 编码。这样失败时能马上知道是处理器逻辑还是路由注册出了问题。

func newPathRequest(method, target string, values map[string]string) *http.Request {
    req := httptest.NewRequest(method, target, nil)
    // 用 map 集中准备变量，调用方可以复用同一套测试夹具。
    for name, value := range values {
        req.SetPathValue(name, value)
    }
    return req
}

这个辅助函数只适合测试代码。生产代码仍应让实际路由层负责产生路径变量，不能为了方便而在业务入口人为覆盖请求数据。测试夹具也不要跨用例复用同一个可变请求对象，否则前一个用例写入的变量可能污染后一个用例。

常见问题

SetPathValue 需要先注册 ServeMux 吗？

不需要。它直接写入当前 *http.Request，适合脱离路由层测试处理器。只有测试路由匹配本身时，才需要注册并调用 ServeMux.ServeHTTP。

为什么 PathValue 读出来是空字符串？

常见原因是没有调用 SetPathValue，名称与注入时不一致，或者只调用了 ServeMux.Handler 而没有让 mux 真正处理请求。

能用 SetPathValue 模拟第三方路由器吗？

这篇方法只针对标准库请求对象和 PathValue。第三方路由器可能把参数保存在自己的上下文结构里，应使用该路由器提供的测试工具或适配层，不要假设它会读取标准库的路径变量集合。

SetPathValue 会修改 URL.Path 吗？

不会。它只影响后续的 PathValue(name) 读取结果；如果断言 URL 文本，还要单独检查 req.URL.Path。

归纳起来，处理器单元测试只需“创建请求、注入变量、调用处理器、断言响应”四步；路由行为再交给 ServeMux 集成测试。把这两类职责拆开，既能减少测试准备代码，也能让失败定位更直接。