Go HTTP 接口怎么写单元测试：请求参数与响应断言

测试 Go HTTP 接口时，不必先监听一个真实端口。只要目标是一个 http.Handler，就可以用 httptest.NewRequest 构造服务端请求，用 httptest.NewRecorder 接住 Handler 写入的响应，最后分别检查 URL 参数、状态码、响应头和正文。

用 httptest 构造请求和响应接收器

下面的 Handler 只接受 GET 请求，并从 name 查询参数生成问候语。输入不完整时返回 400，方法不对时返回 405。

func greetingHandler(w http.ResponseWriter, r *http.Request) {
	if r.Method != http.MethodGet {
		w.Header().Set("Allow", http.MethodGet)
		http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
		return
	}
	name := r.URL.Query().Get("name")
	if name == "" {
		http.Error(w, "name is required", http.StatusBadRequest)
		return
	}
	w.Header().Set("Content-Type", "text/plain; charset=utf-8")
	fmt.Fprintf(w, "hello, %s", name)
}

httptest.NewRequest 创建的是适合传给服务端 Handler 的请求；它不是模拟浏览器的客户端请求。NewRecorder 则实现了 http.ResponseWriter，可以接收 Handler 写入的 Header、状态码和正文，因此测试不需要启动端口。

把请求参数、状态码和响应体分开断言

最容易维护的写法是表驱动测试。每个用例先写清请求方法、URL 和期望结果，再在同一个断言块中按输入、输出顺序检查。这样失败时不会只得到一句“正文不相等”。

func TestGreetingHandler(t *testing.T) {
	tests := []struct {
		name       string
		method     string
		target     string
		wantStatus int
		wantType   string
		wantBody   string
	}{
		{"success", http.MethodGet, "/greet?name=Go", http.StatusOK, "text/plain; charset=utf-8", "hello, Go"},
		{"missing name", http.MethodGet, "/greet", http.StatusBadRequest, "", "name is required\n"},
		{"wrong method", http.MethodPost, "/greet?name=Go", http.StatusMethodNotAllowed, "", "method not allowed\n"},
	}

	for _, tt := range tests {
		t.Run(tt.name, func(t *testing.T) {
			req := httptest.NewRequest(tt.method, tt.target, nil)
			rec := httptest.NewRecorder()
			greetingHandler(rec, req)

			resp := rec.Result()
			defer resp.Body.Close()
			if resp.StatusCode != tt.wantStatus {
				t.Fatalf("status = %d, want %d", resp.StatusCode, tt.wantStatus)
			}
			if got := resp.Header.Get("Content-Type"); got != tt.wantType {
				t.Errorf("content type = %q, want %q", got, tt.wantType)
			}
			body, err := io.ReadAll(resp.Body)
			if err != nil {
				t.Fatal(err)
			}
			if string(body) != tt.wantBody {
				t.Errorf("body = %q, want %q", body, tt.wantBody)
			}
		})
	}
}

这里使用 Result() 后再读响应。官方文档特别提醒：如果 Handler 没有显式调用 WriteHeader 或 Write，Recorder 的 Code 可能还是 0；Result().StatusCode 才会体现隐含的 200。响应头也从 Result 返回的 Response 读取，不要依赖已被标记为兼容用途的内部 HeaderMap。

用失败用例检查 Handler 边界

这组测试验证的是 Handler 的行为，不是完整 Web 服务。它能发现参数读取、方法分支和响应写入的问题，但不会自动覆盖 ServeMux 路由是否匹配、认证中间件是否执行或真实网络连接是否可用。

运行 go test -run TestGreetingHandler -v 可以只执行这组用例。若后续把 Handler 接到真实路由，再增加一层测试即可；不要为了测试一个纯函数而启动服务，也不要让端口、网络和外部依赖掩盖参数断言本身的问题。

常见问题

NewRequest 和 http.NewRequest 应该选哪个？

测试服务端 Handler 时优先用 httptest.NewRequest，因为它按服务端入站请求准备字段；要测试真正的客户端发送行为，再考虑 http.NewRequest 配合测试服务器。

为什么不直接检查 rec.Code？

Recorder 的 Code 记录显式写入的状态码，Handler 什么都没写时可能是 0。通过 rec.Result().StatusCode 检查最终响应，更符合客户端视角。

什么时候需要 httptest.NewServer？

当你要验证客户端、序列化、重定向、真实路由或中间件链之间的协作时使用 NewServer。单独测试 Handler 的分支和响应，不需要启动服务器。