Go httptest.NewRequest 与 http.NewRequest 测试服务端请求时有什么区别

给 HTTP handler 写测试时，最容易混淆的就是这两个名字很像的 API：httptest.NewRequest 和 http.NewRequest。它们都返回 *http.Request，但服务的方向不同：前者构造“发给服务端 handler 的入站请求”，后者构造“准备交给客户端发送的出站请求”。

测试 handler、路由、Host 或 TLS 分支时优先用 httptest.NewRequest；测试客户端中间件、请求头或重定向重放时使用 http.NewRequest。不要因为返回类型相同，就把两者当成可互换的工厂函数。

先按请求角色选择构造器

把测试拆成两类后，判断就简单了。服务端测试的对象是 http.Handler：请求已经“到达”服务，只需要把方法、request-target 和 body 交给 handler。客户端测试的对象是 http.Client 或自定义 RoundTripper：请求还在发送前，需要完整 URL、可选的可重放 body，以及面向出站连接的字段。

因此，看到测试函数接收的是 handler，就从 httptest.NewRequest 开始；看到测试函数要把请求交给 client、Transport 或 RoundTripper，就从 http.NewRequest 开始。

httptest.NewRequest 会准备哪些服务端默认值

httptest.NewRequest 的文档明确说明，它返回适合传给 http.Handler 测试的入站 server Request。target 可以写成路径，也可以写成绝对 URL：写绝对 URL 时，Host 来自 URL；只写路径时，Host 使用 example.com。target 的 scheme 是 https 时，TLS 字段会被设置为非 nil 的哑值，便于测试 HTTPS 分支。

它还把 Proto 固定为 HTTP/1.1；空 method 按 GET 处理。body 可以是 nil，使用 bytes.Reader、strings.Reader、bytes.Buffer 或 http.NoBody 时，ContentLength 会被设置。构造过程中出错会 panic，这种行为适合测试代码里快速准备请求。

package httptestdemo

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

func TestHandlerRequestShape(t *testing.T) {
    handler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        // handler 看到的是服务端入站请求，可以直接读取 Host、TLS 和 Body。
        if r.Host != "api.example.test" {
            t.Errorf("unexpected host: %q", r.Host)
        }
        if r.TLS == nil {
            t.Error("expected HTTPS request")
        }
        body, err := io.ReadAll(r.Body)
        if err != nil {
            t.Fatalf("read request body: %v", err)
        }
        // 这里把输入回写，便于断言 handler 的读取结果；测试结束后关闭 body。
        _, _ = w.Write(body)
    })

    req := httptest.NewRequest("POST", "https://api.example.test/users", strings.NewReader("alice"))
    rec := httptest.NewRecorder()
    handler.ServeHTTP(rec, req)

    if got := rec.Body.String(); got != "alice" {
        t.Fatalf("unexpected response body: %q", got)
    }
    // 请求由测试代码创建，显式关闭 Body 可保持资源生命周期清楚。
    _ = req.Body.Close()
}

这个例子关注的是 handler 能看到什么：Host、TLS、Proto 和 Body 都是入站语义。它没有调用 http.Client.Do，所以不需要把请求写成客户端发送模型。

http.NewRequest 更像客户端发送前的草稿

http.NewRequest 返回的是给定 method、URL 和可选 body 的请求。URL 是它的核心输入；body 如果是 *bytes.Buffer、*bytes.Reader 或 *strings.Reader，标准库会设置精确的 ContentLength，填充 GetBody 以支持 307/308 重定向时重放，并在长度为零时把 Body 设为 http.NoBody。

这套字段组合更适合测试客户端中间件：例如检查签名代码是否读取 URL 和 Header，或检查重定向前后 body 是否可重新取得。若只想调用一个 handler，却用 http.NewRequest，代码也许能编译，但你测试的对象已经从“服务端收到的请求”偏向“客户端即将发送的请求”。

func TestClientMiddlewareRequest(t *testing.T) {
    // 客户端请求使用完整 URL，适合交给 RoundTripper 或 Client 检查。
    req, err := http.NewRequest(http.MethodPost, "https://api.example.test/users", strings.NewReader("alice"))
    if err != nil {
        t.Fatalf("build client request: %v", err)
    }
    // 可识别的 strings.Reader 会带来 ContentLength 和 GetBody，方便测试重放语义。
    if req.ContentLength != int64(len("alice")) || req.GetBody == nil {
        t.Fatalf("request body metadata is incomplete: length=%d getBody=%v", req.ContentLength, req.GetBody != nil)
    }
    // 这里只检查请求对象，不真的访问网络；调用方负责关闭最终使用的 Body。
    _ = req.Body.Close()
}

body 类型会改变你看到的字段

两者都会接受 io.Reader，但不要把“body 可读”误认为“所有元数据都一样”。可以把差异记成三层：输入类型、请求字段、测试目标。

如果 body 来自一个只实现了 io.Reader 的自定义类型，标准库通常无法凭空知道长度，也不能自动生成 GetBody。需要精确测试这些字段时，选择文档中能识别的 body 类型，或在测试里显式设置你真正要验证的字段。

最后用一张判断表收口

写测试时只问两个问题：请求是“送进 handler”还是“交给 client”？断言的是“入站环境”还是“出站元数据”？前一个答案指向 httptest.NewRequest，后一个答案指向 http.NewRequest。

官方参考：https://pkg.go.dev/net/http/httptest#NewRequest、https://pkg.go.dev/net/http#NewRequest。它们名字相似，但 API 设计目标不同；理解请求角色，比记住某个默认字段更重要。

相关问题

为什么 handler 测试通常不用 http.Client？

直接调用 handler 可以把断言集中在入站请求和响应上，不需要引入网络传输层；只有要测试 client、Transport 或真实连接行为时，才使用客户端路径。

httptest.NewRequest 的 target 为什么可以只写路径？

它面向服务端 request-target，路径形式足以构造入站请求；如果测试依赖具体 Host 或 HTTPS，就使用绝对 URL，让 Host 和 TLS 语义明确。

ContentLength 为零时为什么 Body 可能是 http.NoBody？

这是标准库对已知空 body 的特殊表示。测试时应关注请求语义，而不是把空 body 强行当成一个仍需读取的普通流。