Go 测试通过 ResponseRecorder 却漏掉真实服务器差异怎么办

如果测试把 ResponseRecorder 的正文、状态码都断言正确，却仍然漏掉线上响应差异，先检查测试到底覆盖了哪一层。直接调用处理器，只能说明它在这个记录器上产生了哪些写入；通过本地测试服务器发请求，才把服务器与客户端之间的 HTTP 行为纳入观察。两种测试不是替代关系，关键是把“处理器输出正确”和“客户端收到的结果正确”分别写成断言。

业务负载：先列出真正对外承诺的结果

普通 JSON 接口通常关心状态码、字段和响应头；下载接口还关心 HEAD 请求的正文约束；流式接口关心客户端是否能逐段读到数据。把这些承诺全部交给同一种记录器测试，测试会很简洁，但覆盖范围容易被高估。本文只讨论 Recorder 与服务器 ResponseWriter 的边界，不展开反向代理或生产网关配置。

建议先列两张清单：业务清单记录输入对应的响应内容，传输清单记录客户端应观察到的协议表现。前者适合大量快速用例，后者适合少量有针对性的本地服务器用例。这里的“架构”指测试分层，而不是为一个接口搭建新的云服务。

约束条件：记录器保存写入，不模拟完整连接

ResponseRecorder 在内存中承接处理器写操作，没有真实客户端连接，因此不能据此推断连接断开、网络背压或写入期限的表现。最直观的例子是 HEAD：处理器即使写入了字符串，记录器仍能留下这些字节；服务器对 HEAD 响应则不会把这些字节作为响应正文交给客户端。记录器看到非空正文，并不意味着真实 HEAD 响应一定发送了正文。

另一个约束是请求的形态。httptest.NewRequest 用于构造交给处理器的服务端请求；向测试服务器发起请求时，用 http.NewRequest 构造客户端请求。不要只替换 ResponseWriter，却继续把所有请求假设当成网络事实。

方案对比：用同一个 HEAD 处理器写两层测试

下面的示例可放入一个 Go 模块的 handler_test.go。示例没有依赖外部网站，也没有通过显式 HEAD 分支制造结果。第一项测试确认写入记录，第二项测试确认客户端所见正文。示例在本文制作过程中未实际执行，下面描述的是设计预期，不是运行日志。

package handler_test

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

// 同一个处理器不对 HEAD 做分支，便于观察服务器层的职责。
func greeting(w http.ResponseWriter, r *http.Request) {
    w.Header().Set("Content-Type", "text/plain; charset=utf-8")
    _, _ = io.WriteString(w, "hello")
}

func TestRecorderRecordsHandlerWrites(t *testing.T) {
    rec := httptest.NewRecorder()
    req := httptest.NewRequest(http.MethodHead, "/", nil)
    greeting(rec, req)

    // 这里断言处理器写过什么，不声明网络上的 HEAD 正文是什么。
    res := rec.Result()
    defer res.Body.Close()
    if res.StatusCode != http.StatusOK || rec.Body.String() != "hello" {
        t.Fatalf("处理器记录不符：状态=%d，正文=%q", res.StatusCode, rec.Body.String())
    }
}

func TestServerHeadHasNoResponseBody(t *testing.T) {
    srv := httptest.NewServer(http.HandlerFunc(greeting))
    defer srv.Close()

    // 真正发起客户端请求，设置期限避免网络异常时长期等待。
    client := srv.Client()
    client.Timeout = 3 * time.Second
    req, err := http.NewRequest(http.MethodHead, srv.URL, nil)
    if err != nil {
        t.Fatal(err)
    }
    res, err := client.Do(req)
    if err != nil {
        t.Fatal(err)
    }
    defer res.Body.Close()
    body, err := io.ReadAll(res.Body)
    if err != nil {
        t.Fatal(err)
    }
    // 断言客户端观察到的协议结果，而不是处理器内部写缓冲。
    if res.StatusCode != http.StatusOK || len(body) != 0 {
        t.Fatalf("HEAD 响应不符：状态=%d，正文长度=%d", res.StatusCode, len(body))
    }
}

预期第一项测试中的记录器正文为 hello，第二项测试中的客户端正文为空。这两个断言可以同时成立，因为它们观察的对象不同。不要把第一项改成“Recorder 正文必须为空”，那会把服务器职责错误地压到记录器上；也不要删掉第二项，仅用一个手写 mock 冒充完整的服务器行为。

示例有意忽略处理器写入字符串的返回值，因为它只演示测试边界，不将其作为生产错误处理模板。实际处理器应按业务需要记录或处理写错误；记录器写成功也不能证明真实连接上的写操作必然成功。

推荐架构：大量业务单测，少量边界集成测试

保留直接调用处理器的测试，用表驱动覆盖参数、权限分支和正文结构；在存在明确传输承诺的地方增加 NewServer 测试，例如 HEAD、重定向、Cookie 和实际路由中间件组合。服务器测试应挂载应用真实使用的处理器链，否则测试的仍是被简化的入口。

如果承诺涉及 TLS，选择 NewTLSServer 并使用该服务器提供的客户端。若涉及 HTTP/2，则需要显式配置对应的测试服务器能力，不能因为请求经过 NewServer 就声称覆盖了所有 HTTP 版本。每新增一种服务器测试，都应能说清它补的是哪一条断言。

风险点：头快照、Flush 与接口能力别混在一起

响应头断言应在处理器执行结束后读取 rec.Result().Header，而不是仅观察 rec.Header() 当前的可变映射。比如先 WriteHeader(200)，再 Set 一个普通头，当前映射可能有这个值，但它不代表这个头已成为对外响应的一部分；Trailer 有独立约定，不能套用普通头判断。不要在处理器仍写入时调用 Result，也不要对整个 Response 做 DeepEqual，应只检查自己承诺的字段。

rec.Flushed 表示是否调用过 Flush，不是“客户端已经收到一段数据”的证明。流式测试若只检查这个布尔值，会漏掉读取节奏问题。需要客户端可见性时，针对本地服务器设计有限数据、明确结束条件和超时的读取测试；本地通过仍不等于生产链路没有其他缓冲层。

ResponseWriter 的基础接口也不保证所有扩展能力。Flusher、Hijacker 等能力应按接口或控制器约定判断；HTTP/1 与 HTTP/2 的能力不同，中间件包装器也可能隐藏能力。因此别让测试把“这个记录器具备某个方法”当成业务入口在所有协议下都具备该能力的依据。

落地清单：从漏测现象回到观察对象

• 把失败描述改成客户端可观察的承诺，例如“HEAD 正文为空”，避免笼统写“HTTP 测试通过”。
• 保留业务内容的 Recorder 用例，使用 Result 读取最终断言所需的状态与头。
• 为传输承诺补一个本地服务器用例，使用真实处理器链和客户端请求。
• 明确协议、TLS、接口能力和超时条件，关闭响应体与测试服务器。
• 不把 Flush 标记、内存写成功或记录器字节等同于网络交付保证。

归根结底，ResponseRecorder 的价值是让处理器逻辑易于观察，而不是复刻完整 HTTP 服务器。把观察边界写进测试名和断言，才能让“测试通过”具有清晰含义。

官方资料

httptest 工具与 Result 约定：https://pkg.go.dev/net/http/httptest；记录器实现：https://go.dev/src/net/http/httptest/recorder.go；ResponseWriter 与扩展接口：https://pkg.go.dev/net/http。不同 Go 版本的实现细节可能变化，维护测试时以项目实际版本文档为准。