httptestNewTestServer测试HTTP处理器

如果一个 HTTP 处理器已经写好，测试时最容易走偏的方式是直接调用函数，然后把路由、请求方法、响应头和响应体的差异都藏掉。httptest.NewTestServer 更适合做这一层测试：把现有的 http.Handler 接入测试服务器，再用它提供的客户端发起真实的 HTTP 请求。这样测试关注的是处理器对请求的完整响应，而不是某个内部函数恰好返回了什么。

核心写法是 server := httptest.NewTestServer(handler)，随后用 server.Client() 请求并检查 status、header、body。使用 Go 测试中的 NewTestServer 时，测试结束会自动清理服务器，通常不需要自己调用 Close。

先把处理器接到测试服务器

NewTestServer 接收一个 http.Handler。它可以是 http.HandlerFunc、带路由的 ServeMux，也可以是项目自己的处理器类型。下面的例子只保留一个可观察的行为：当请求路径为 /health 时返回 JSON 和状态码。

package handler_test

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

func healthHandler() http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        // 先限制测试场景的请求方法，避免把错误请求误判成成功。
        if r.Method != http.MethodGet {
            http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
            return
        }
        // 明确响应类型，测试才能同时覆盖状态码、Header 和正文。
        w.Header().Set("Content-Type", "application/json")
        w.WriteHeader(http.StatusOK)
        _, _ = w.Write([]byte(`{"status":"ok"}`))
    })
}

func TestHealthHandler(t *testing.T) {
    server := httptest.NewTestServer(healthHandler())
    client := server.Client()

    // Client 会把请求路由到测试服务器；URL 只作为测试目标地址示例。
    resp, err := client.Get(server.URL + "/health")
    if err != nil {
        t.Fatalf("request health endpoint: %v", err)
    }
    // 无论断言是否提前失败，都要关闭响应体，避免连接资源悬挂。
    defer resp.Body.Close()

    if resp.StatusCode != http.StatusOK {
        t.Fatalf("status = %d, want %d", resp.StatusCode, http.StatusOK)
    }
    if got := resp.Header.Get("Content-Type"); got != "application/json" {
        t.Fatalf("content type = %q, want application/json", got)
    }

    body, err := io.ReadAll(resp.Body)
    if err != nil {
        t.Fatalf("read response body: %v", err)
    }
    if got := string(body); !strings.Contains(got, `"status":"ok"`) {
        t.Fatalf("body = %q, want status ok", got)
    }
}

这里有三个值得固定下来的判断。第一，NewTestServer 不是把处理器改写成另一套接口，而是提供一个可请求的测试服务器。第二，server.Client() 是与该服务器配套的客户端，适合直接发送请求。第三，响应体仍然是流，读完或断言前后都应关闭它。

用响应对象覆盖真正关心的结果

HTTP 处理器测试不必把每个内部实现细节都写进断言。更稳定的断言通常按“协议结果”分层：状态码说明请求是否被接受，Header 说明协商结果，正文说明业务输出。若只比较正文，处理器把错误请求错误地返回为 200 时，测试可能仍然通过。

func TestHealthHandlerRejectsPost(t *testing.T) {
    server := httptest.NewTestServer(healthHandler())
    resp, err := server.Client().Post(server.URL+"/health", "text/plain", strings.NewReader("x"))
    if err != nil {
        t.Fatalf("post health endpoint: %v", err)
    }
    // 关闭正文流，避免失败测试留下未释放的 HTTP 资源。
    defer resp.Body.Close()

    if resp.StatusCode != http.StatusMethodNotAllowed {
        t.Fatalf("status = %d, want %d", resp.StatusCode, http.StatusMethodNotAllowed)
    }
}

如果处理器需要认证头、查询参数或 JSON 请求体，仍然使用标准的 http.NewRequest 和 client.Do 即可。把请求构造和断言拆开，能让“输入是什么”和“结果应该是什么”更容易复用；不要为了测试方便，绕过路由直接调用处理器内部的私有函数。

区分内存网络与手动生命周期

NewTestServer 的重要边界是它面向测试的生命周期。当前官方文档说明，使用它创建的服务器会注册测试清理函数；同时，测试服务器可以使用内存网络，配套的客户端会把请求导向这个服务器，不需要把请求目标理解成一次真实的外部联网访问。文章中的 server.URL 只是稳定的测试地址字段。

如果你确实需要自己决定何时启动、使用 HTTP 还是 HTTPS，才考虑 NewServer 或 NewUnstartedServer：

func TestManualServerLifecycle(t *testing.T) {
    server := httptest.NewUnstartedServer(healthHandler())
    // Start 或 StartTLS 应在第一次使用客户端前完成，配置也应在这里完成。
    server.Start()
    // 手动启动的 Server 不享受 NewTestServer 的自动清理责任。
    defer server.Close()

    resp, err := server.Client().Get(server.URL + "/health")
    if err != nil {
        t.Fatalf("request manual server: %v", err)
    }
    // 读取结果前先登记关闭动作，保证错误分支也能释放连接。
    defer resp.Body.Close()
    if resp.StatusCode != http.StatusOK {
        t.Fatalf("status = %d, want %d", resp.StatusCode, http.StatusOK)
    }
}

一个常见误区是创建了 NewTestServer，又把它当作手动服务器反复调用 Start。如果测试只需要请求处理器，直接使用 NewTestServer 更清楚；只有在需要控制监听方式、TLS 或启动时机时，才切换到手动模式。

选择哪种 httptest 工具

因此，标题里的“测试 HTTP 处理器”如果强调真实请求边界，就从 NewTestServer 开始；如果只验证一个分支的写入结果，ResponseRecorder 可能更轻；如果测试 TLS 或启动配置，再选择手动服务器。选择工具的依据是测试边界，而不是代码看起来更短。

常见问题

NewTestServer 还需要调用 Close 吗？

使用测试函数中的 NewTestServer(t, handler) 时，官方实现会注册清理动作，通常不需要重复手动关闭。若使用不接收测试对象的 NewServer 或未启动服务器，则应由测试显式负责关闭。

为什么请求成功了，测试仍然应该关闭 Body？

http.Response.Body 是资源流。即使只断言状态码，也应关闭它；如果还需要正文，就先读取需要的内容，再关闭流。这样多个测试并行运行时，连接资源不会因为遗漏清理而积累。

什么时候应该用 ResponseRecorder？

当目标是验证处理器直接写出的状态码、Header 和正文，且不需要客户端行为、路由装配或连接层边界时，ResponseRecorder 更轻量。要覆盖完整 HTTP 请求路径，则使用 NewTestServer。

参考资料

• https://pkg.go.dev/net/http/httptest
• https://pkg.go.dev/net/http#Handler
• https://go.dev/src/net/http/httptest/server.go