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 请求与响应流程,同时保持快速、可重复。

HTTP 集成测试完整链路

用真实客户端走完整链路

下面的主测试定义一个响应头中间件、一个重定向入口和一个 JSON 接口。请求首先访问 /redirect,客户端自动跟随到带百分号编码查询参数的 /api/items,随后断言重定向次数、最终 URL、Header 和响应体。将内容保存为 server_integration_test.go 后运行 go test -v。

go
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"])
    }
}

预期输出

text
=== 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 链路交给临时服务器验证,出站依赖则使用受控替身或独立环境,才能让失败原因保持清晰。

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

目录与阅读设置

阅读设置

17

记录一个想法

编写 HTTP 集成测试

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

登录哪都通