Go / 系统课时

测试 HTTP Handler

测试 HTTP Handler

本节用 net/http/httptest 在进程内构造请求与响应记录器,直接调用 Handler,并同时校验状态码、响应头和响应体。完成后,你可以在不启动真实端口的情况下,为 HTTP 接口建立快速、稳定且可重复的单元测试。

学习目标

  • 使用 httptest.NewRequest 和 httptest.NewRecorder 构造一次完整的 Handler 调用
  • 对状态码、响应头和响应体编写明确断言
  • 理解直接测试 Handler 能覆盖什么,以及它与真实 HTTP 服务测试的边界

Handler 测试的核心对象

httptest.NewRequest 会创建适合测试的 *http.Request,httptest.NewRecorder 则实现 http.ResponseWriter,把 Handler 写出的状态码、响应头和响应体保存在内存中。测试只需调用一次 handler.ServeHTTP(recorder, request),无需监听端口,也不会产生真实网络连接。

这种方式特别适合验证纯 Handler 行为:给定请求后,是否返回正确状态、内容类型和正文。若目标是验证客户端传输、连接、TLS 或真实服务器路由,则应使用 httptest.Server,而不是只调用 Handler。

编写一个可运行的 Handler 测试

下面的测试文件同时包含被测 Handler 和测试函数。把它保存为 Go 模块中的 handler_test.go,即可直接运行。Handler 只接受 GET,成功时返回 JSON;其他方法返回 405 Method Not Allowed。

go
package httpdemo

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

func pingHandler(w http.ResponseWriter, r *http.Request) {
	if r.Method != http.MethodGet {
		http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
		return
	}

	w.Header().Set("Content-Type", "application/json")
	w.WriteHeader(http.StatusOK)
	_, _ = io.WriteString(w, `{"message":"pong"}`)
}

func TestPingHandler(t *testing.T) {
	req := httptest.NewRequest(http.MethodGet, "/ping", nil)
	rec := httptest.NewRecorder()

	// 直接调用 Handler,测试过程不启动真实 HTTP 服务器。
	http.HandlerFunc(pingHandler).ServeHTTP(rec, req)
	res := rec.Result()
	defer res.Body.Close()

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

	body, err := io.ReadAll(res.Body)
	if err != nil {
		t.Fatal(err)
	}
	if got, want := string(body), `{"message":"pong"}`; got != want {
		t.Fatalf("body = %q, want %q", got, want)
	}
}

预期结果:测试函数没有触发 t.Fatal 或 t.Fatalf,说明三类断言全部通过。

运行指定测试:

bash
go test -run TestPingHandler -v

预期输出:

text
=== RUN   TestPingHandler
--- PASS: TestPingHandler (<TIME>)
PASS
ok   <MODULE_PATH>   <TIME>

其中 <MODULE_PATH> 和 <TIME> 会随模块路径与运行环境变化。

正确读取 Recorder 的结果

httptest.ResponseRecorder 本身暴露了 Code、Header() 和 Body,但在测试接近真实响应语义时,更推荐调用 rec.Result() 得到 *http.Response。这样读取状态、响应头和响应体的方式与客户端侧代码一致,也便于显式关闭 Body。

不要只断言状态码。一个 Handler 即使返回 200,也可能遗漏 Content-Type,或输出了错误的 JSON。对外契约包含哪些字段,测试就应检查哪些字段;同时避免断言与契约无关的实现细节,例如内部函数调用次数。

什么时候需要更高一层测试

直接调用 Handler 不会覆盖真实监听端口、客户端传输层、代理行为或 TLS 握手,也不会自动证明生产中的完整中间件链已接入。如果问题属于“Handler 给定请求后如何响应”,优先使用 NewRequest 加 NewRecorder;如果问题属于“客户端发出的 HTTP 请求经过服务器后如何返回”,再升级到 httptest.Server。

按自己的节奏,确认真正理解。

目录与阅读设置

记录一个想法

测试 HTTP Handler

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通