Go httptest用 NewServer 隔离外部依赖的测试结构

我在给一个会调用支付、库存或通知服务的 Go 客户端补测试时，最先遇到的问题不是断言怎么写，而是测试不该真的碰上游。用 httptest.NewServer 可以在测试进程里启动一个本地 HTTP 服务，把可控的 Handler 注入客户端；测试只验证自己的请求构造和响应处理，不依赖外部网络、账号和随机数据。

核心结构是：测试服务负责模拟外部依赖，客户端只接收测试地址；Handler 固定请求合同，测试再断言路径、请求头、状态码和响应体。使用结束后必须关闭 Server。

先划清 NewServer 的测试边界

NewServer 接收一个 http.Handler，返回已经启动的本地 HTTP 服务，server.URL 是不带末尾斜杠的基地址。它更接近一次真实 HTTP 调用：客户端仍然经过 URL 解析、请求发送和响应读取，但地址被换成测试服务，不会触达真正的上游。

因此被测代码最好把上游地址作为配置，而不是写死在函数里。Handler 只模拟本次测试需要的合同，例如 GET /v1/stock/sku-7 返回一段固定 JSON；鉴权、超时和重试等行为则由单独用例覆盖，不要在一个 Handler 里堆成完整业务系统。

让 Handler 成为可读的返回合同

我通常先在 Handler 中写请求检查，再写响应内容。这样失败时能马上知道是客户端拼错路径、漏了请求头，还是解析响应出了问题。下面的辅助函数把上游地址注入客户端，测试服务只返回稳定的库存结果。

func newStockClient(baseURL string) *StockClient {
	// 把上游地址作为依赖注入，测试时可以替换成 httptest 服务地址。
	return &StockClient{BaseURL: strings.TrimRight(baseURL, "/"), HTTP: http.DefaultClient}
}

func TestStockClient(t *testing.T) {
	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		// 先检查请求合同，避免测试只验证“收到了某个响应”。
		if r.URL.Path != "/v1/stock/sku-7" || r.Header.Get("X-Trace-ID") == "" {
				http.Error(w, "bad request contract", http.StatusBadRequest)
				return
		}
		w.Header().Set("Content-Type", "application/json")
		// 固定返回值，让客户端解析测试不依赖真实库存变化。
		_, _ = io.WriteString(w, `{"sku":"sku-7","available":12}`)
	}))
	defer server.Close() // 关闭监听，避免测试留下连接和端口资源。

	client := newStockClient(server.URL)
	client.HTTP = server.Client() // 使用测试服务提供的客户端配置。
	got, err := client.GetStock(context.Background(), "sku-7", "trace-1")
	if err != nil {
		t.Fatalf("get stock: %v", err)
	}
	if got.Available != 12 {
		t.Fatalf("available = %d, want 12", got.Available)
	}
}

示例的重点不是业务结构，而是依赖方向：StockClient 不知道自己连的是生产域名还是测试服务。若客户端内部还保存了固定域名，单纯创建 NewServer 并不能隔离外部依赖。

按请求、状态和 Body 三层完成断言

一次稳定的 HTTP 测试至少有三层检查。第一层在 Handler 里验证方法、路径和关键头；第二层在调用方检查 err 与 StatusCode；第三层读取 Body 后检查业务字段。不要只断言状态码为 200，因为错误 JSON、空 Body 和错误的 Content-Type 仍可能让客户端逻辑失效。

使用 server.Client() 可以得到面向该测试服务配置的客户端；如果使用 http.Client 的默认实例，也可以直接请求 server.URL。响应体要在成功拿到响应后关闭，读取失败也要进入断言，否则连接资源会在大量测试中逐渐堆积。

资源关闭、变体和常见误区

最小写法是创建后立刻 defer server.Close()；在测试框架中也可以用 t.Cleanup(server.Close)，让清理动作和测试生命周期绑定。服务配置应在第一次启动前完成，不能在请求已经发出后再修改。

需要 HTTPS 时可改用 httptest.NewTLSServer，需要控制启动时机或配置时可从 NewUnstartedServer 开始；这些是同一套测试服务模型的变体。若测试只想直接调用一个 Handler 并检查 ResponseWriter，httptest.NewRecorder 更轻，不必为了每个单元测试都启动网络服务。

• 不要把测试服务地址写入全局变量，否则并行测试容易互相覆盖。
• 不要在 Handler 里调用真实上游，否则隔离边界已经失效。
• 不要省略响应体关闭，也不要把“说明图”当成真实测试输出。

相关问题

NewServer 和 NewRecorder 怎么选？只测 Handler 的状态码和响应内容时用 Recorder；需要让客户端真的发 HTTP 请求、覆盖 URL 和请求头行为时用 NewServer。

为什么测试仍然访问了真实服务？通常是被测客户端没有使用注入的 server.URL，或者内部重新拼接了固定域名。先把最终请求地址作为可观察配置，再检查调用路径是否真的使用它。

把 NewServer 当作“可控的外部依赖边界”后，测试结构会清楚很多：Handler 负责合同，客户端负责请求和解析，断言负责结果，Close 负责生命周期。四个职责分开，后续增加超时、错误响应或 TLS 用例时也不容易互相污染。