Go / 系统课时
编写 HTTP 集成测试
编写 HTTP 集成测试
HTTP 处理器的单元测试能验证局部逻辑,却覆盖不到真实客户端的重定向、URL 编码和完整 Header 链路。本课使用 httptest.NewServer 启动临时服务,再让真实 http.Client 发起请求,一次验证路由、中间件与客户端行为。
学习目标
- 使用
httptest.NewServer启动自动分配端口的临时 HTTP 服务 - 通过真实
http.Client验证重定向、查询参数、Header 与 JSON 响应 - 判断临时服务器适合覆盖的 HTTP 链路,以及仍需其他测试解决的外部依赖
为什么使用临时测试服务器
直接调用 handler.ServeHTTP 很适合验证处理器逻辑,但请求没有经过真实客户端,因此默认重定向策略、最终请求 URL 等客户端行为不会自然发生。httptest.NewServer 会监听本机随机端口,并提供可直接请求的 URL,测试结束后还能自动释放资源。
它仍然属于隔离的测试环境:不占用预先约定的固定端口,也不要求把应用部署到外部机器。测试因此能够经过完整的 HTTP 请求与响应流程,同时保持快速、可重复。

用真实客户端走完整链路
下面的主测试定义一个响应头中间件、一个重定向入口和一个 JSON 接口。请求首先访问 /redirect,客户端自动跟随到带百分号编码查询参数的 /api/items,随后断言重定向次数、最终 URL、Header 和响应体。将内容保存为 server_integration_test.go 后运行 go test -v。
package integration_test
import (
"encoding/json"
"net/http"
testserver "net/http/httptest"
"testing"
)
type traceHeaderMiddleware struct {
downstream http.Handler
}
func (m traceHeaderMiddleware) ServeHTTP(w http.ResponseWriter, r *http.Request) {
// 让最终响应携带可观察标记,用来证明请求确实经过中间件。
w.Header().Set("X-Trace", "integration")
m.downstream.ServeHTTP(w, r)
}
func applicationHandler() http.Handler {
router := http.NewServeMux()
router.HandleFunc("/redirect", func(w http.ResponseWriter, r *http.Request) {
// Location 中保留百分号编码,客户端跟随后再通过 Query 解码。
http.Redirect(w, r, "/api/items?lang=%E4%B8%AD%E6%96%87", http.StatusFound)
})
router.HandleFunc("/api/items", func(w http.ResponseWriter, r *http.Request) {
w.Header()["Content-Type"] = []string{"application/json; charset=utf-8"}
_ = json.NewEncoder(w).Encode(map[string]string{
"message": "ok:" + r.URL.Query().Get("lang"),
})
})
return traceHeaderMiddleware{downstream: router}
}
func TestHTTPIntegration(t *testing.T) {
srv := testserver.NewServer(applicationHandler())
t.Cleanup(srv.Close)
client := srv.Client()
redirectCount := 0
client.CheckRedirect = func(req *http.Request, via []*http.Request) error {
// via 保存此前请求,可直接验证客户端确实执行了一次跳转。
redirectCount = len(via)
return nil
}
resp, err := client.Get(srv.URL + "/redirect")
if err != nil {
t.Fatal(err)
}
t.Cleanup(func() { _ = resp.Body.Close() })
if redirectCount != 1 {
t.Fatalf("redirect count = %d, want 1", redirectCount)
}
if resp.StatusCode != http.StatusOK {
t.Fatalf("status = %d, want 200", resp.StatusCode)
}
if resp.Request.URL.Path != "/api/items" {
t.Fatalf("final path = %q", resp.Request.URL.Path)
}
if got := resp.Request.URL.Query().Get("lang"); got != "中文" {
t.Fatalf("lang = %q, want 中文", got)
}
if got := resp.Header.Get("X-Trace"); got != "integration" {
t.Fatalf("X-Trace = %q", got)
}
if got := resp.Header.Get("Content-Type"); got != "application/json; charset=utf-8" {
t.Fatalf("Content-Type = %q", got)
}
payload := make(map[string]string)
if err := json.NewDecoder(resp.Body).Decode(&payload); err != nil {
t.Fatal(err)
}
if payload["message"] != "ok:中文" {
t.Fatalf("message = %q, want ok:中文", payload["message"])
}
}预期输出
=== RUN TestHTTPIntegration
--- PASS: TestHTTPIntegration (<TIME>)
PASS
ok <PATH> <TIME><PATH> 与 <TIME> 会随模块路径和测试耗时变化。测试通过说明客户端执行了一次真实重定向,最终请求到达 /api/items,查询参数被还原为 中文,响应也确实经过中间件并成功解码为 JSON。
断言链路行为而不是内部实现
集成测试应围绕外部可观察结果建立断言。这里读取 resp.Request.URL 是为了确认重定向后的最终目标;统计 CheckRedirect 接收到的历史请求能够证明跳转真实发生;检查 X-Trace 则确认中间件参与了最终响应处理。
不要在这种测试中断言某个私有函数被调用几次,也不要依赖路由器内部数据结构。只要重构后状态码、URL、Header 和响应体等 HTTP 契约保持不变,集成测试就应继续通过。
临时服务器覆盖不到什么
httptest.NewServer 验证的是当前进程可控的 HTTP 链路,并不能证明生产环境中的 DNS、反向代理、负载均衡或证书配置正确。需要测试 TLS 客户端行为时,可以改用 httptest.NewTLSServer,并使用测试服务器提供的客户端处理测试证书信任。
第三方支付、外部 API 等依赖也不宜直接接进这类测试,否则网络波动和对方服务状态会让结果失去确定性。入站 HTTP 链路交给临时服务器验证,出站依赖则使用受控替身或独立环境,才能让失败原因保持清晰。