Golang测试HTTP Handler的常见方式

推荐用 httptest.NewRecorder 轻量测试 Handler，模拟 ResponseWriter 和 Request；需路由或中间件时用 httptest.NewServer；注意 URL 参数、Context、Header 写入顺序及 Recorder 并发安全。

用 httptest.NewRecorder 捕获响应内容

测试 HTTP Handler 本质是验证它对请求的处理逻辑是否正确，而不是启动真实服务器。最轻量、最推荐的方式是把 Handler 当作普通函数调用，用 httptest.NewRecorder 构造一个假的 http.ResponseWriter，再传入伪造的 *http.Request。

关键点在于：Handler 接口只依赖 http.ResponseWriter 和 *http.Request，二者都可被模拟，无需网络或端口。

• httptest.NewRecorder() 返回的 *httptest.ResponseRecorder 实现了 http.ResponseWriter，内部缓存状态码、Header、Body
• 用 http.NewRequest 构造请求，注意设置 Method、URL、Body（如需）和 Header
• 调用 handler.ServeHTTP(recorder, req) 后，直接检查 recorder.Code、recorder.Header()、recorder.Body.Bytes()

func TestMyHandler(t *testing.T) {
	req, _ := http.NewRequest("GET", "/api/user/123", nil)
	rec := httptest.NewRecorder()
	handler := http.HandlerFunc(myHandler)
	handler.ServeHTTP(rec, req)

	if rec.Code != http.StatusOK {
		t.Errorf("expected status %d, got %d", http.StatusOK, rec.Code)
	}
	if !strings.Contains(string(rec.Body.Bytes()), "id") {
		t.Error("response body missing expected content")
	}
}

用 httptest.NewServer 测试中间件或依赖路由的行为

当 Handler 依赖 http.ServeMux 路由解析、或你正在测中间件（比如日志、鉴权），仅用 NewRecorder 不够——因为路径匹配、URL 解析、中间件链的调用顺序需要真实 HTTP 协议栈参与。这时用 httptest.NewServer 启动一个临时服务器更合适。

它会在本地随机端口起服务，返回一个带 URL 的 server 实例，你可以用标准 HTTP 客户端发请求（如 http.Get），完全模拟外部调用。

立即学习“go语言免费学习笔记（深入）”；

• NewServer 启动的是真实 goroutine，会监听端口，记得在测试末尾调用 server.Close()
• 适用于测试 http.ServeMux 注册的路由、中间件包装后的 handler、或需要重定向、Cookie、TLS 等协议级行为的场景
• 比 NewRecorder 开销大，不必要时别用；单元测试优先选 NewRecorder，集成测试再考虑 NewServer

func TestWithMiddleware(t *testing.T) {
	handler := loggingMiddleware(authMiddleware(myHandler))
	server := httptest.NewServer(handler)
	defer server.Close()

	resp, err := http.Get(server.URL + "/api/user/123")
	if err != nil {
		t.Fatal(err)
	}
	defer resp.Body.Close()

	if resp.StatusCode != http.StatusOK {
		t.Errorf("expected 200, got %d", resp.StatusCode)
	}
}

测试含 URL 参数或 Query 的 Handler

很多 Handler 依赖 r.URL.Path 或 r.URL.Query() 提取参数，比如用 chi 或 gorilla/mux 的路由变量。这时候不能只靠 http.NewRequest 的 URL 字符串——必须确保 Request.URL 正确初始化，否则 r.URL.Query().Get("id") 可能为空。

• 手动构造 url.URL 并赋给 req.URL，尤其注意 RawQuery 字段要设对（url.Values{}.Encode()）
• 若使用第三方路由器（如 chi.Context），需显式注入上下文变量，否则 chi.URLParam(r, "id") 会 panic
• 测试 POST 表单时，用 url.Values{"name": {"alice"}}.Encode() 作为 Body，并设置 Content-Type: application/x-www-form-urlencoded

func TestHandlerWithQuery(t *testing.T) {
	values := url.Values{}
	values.Set("page", "2")
	values.Set("limit", "10")

	req, _ := http.NewRequest("GET", "/api/items?"+values.Encode(), nil)
	rec := httptest.NewRecorder()
	myHandler.ServeHTTP(rec, req)

	// now r.URL.Query().Get("page") == "2"
}

避免常见陷阱：Context、ResponseWriter 写入顺序、并发安全

Handler 测试失败常不是逻辑错，而是对 Go HTTP 基础机制理解偏差。三个高频坑：

• http.Request.Context() 默认是 background，若 Handler 里用了 ctx.Value 或依赖超时，得用 req.WithContext(context.WithValue(...)) 显式替换
• 多次调用 w.WriteHeader() 会被静默忽略（只有第一次生效），但 w.Write() 后再写 Header 会 panic —— 测试时如果提前写了 Body，再断言 rec.Header().Get("X-Trace-ID") 就可能漏掉
• Handler 函数本身应是并发安全的，但测试中若复用同一个 *httptest.ResponseRecorder 实例跑多个 goroutine，会导致数据竞争（rec.Body 是 *bytes.Buffer，非线程安全）

复杂 Handler 往往混合了 Context 传递、Header 设置、Body 写入、错误提前返回等流程，建议每个测试只覆盖一条主路径，用不同 rec 实例隔离副作用。