Go httptest.Server 模拟外部 API 的测试边界

调用外部 HTTP API 的代码，最容易在测试里留下两个盲区：只断言返回值，却没有确认请求是否发对；只覆盖 200，却没有确认上游 500 时客户端怎样收口。Go 的 net/http/httptest 可以在进程内启动一个可控的测试服务，让测试真正经过 HTTP 请求，但不依赖外部网络。

把 httptest.Server 当成“请求契约替身”：handler 只负责检查方法、路径、请求头和请求体，再返回少量成功或失败响应。测试结束时关闭响应体和服务，边界就清楚了。

官方文档地址：https://pkg.go.dev/net/http/httptest

• 触发信号：客户端测试需要访问一个外部 API，但不希望依赖真实服务。
• 快速判断：要验证的是 HTTP 契约，还是第三方系统本身的行为；前者适合 httptest.Server。
• 处理目标：请求断言、成功响应、上游错误和资源关闭都要有明确结果。

先把外部 API 缩成可控的测试边界

测试替身不需要复制真实 API 的全部业务，只需覆盖被测客户端真正依赖的契约。例如客户端向 /v1/orders 发送 POST，请求体包含订单号，外部 API 返回一个 JSON 状态。handler 可以只检查这几项，任何不符合契约的请求都立即返回 400。

httptest.NewServer 会启动一个监听本机回环地址的服务，并把基础地址放到 server.URL。它不是浏览器模拟器，也不是线上服务的缩小版；它的价值是让测试拥有稳定、可编程的 HTTP 对端。

用 handler 检查方法、路径和请求体

先写一个小型客户端函数，把 API 根地址作为参数注入。这样生产代码可以传真实地址，测试代码传入 server.URL，不需要修改全局变量。

package orderapi

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
)

type CreateOrderRequest struct {
    OrderID string `json:"order_id"`
}

type CreateOrderResponse struct {
    Status string `json:"status"`
}

// createOrder 只依赖注入的 baseURL，便于测试时替换外部 API。
func createOrder(client *http.Client, baseURL string, orderID string) (string, error) {
    payload, err := json.Marshal(CreateOrderRequest{OrderID: orderID})
    if err != nil {
        return "", fmt.Errorf("编码请求体: %w", err)
    }

    // 使用 POST 明确请求意图，并把 JSON 请求体交给测试服务检查。
    req, err := http.NewRequest(http.MethodPost, baseURL+"/v1/orders", bytes.NewReader(payload))
    if err != nil {
        return "", fmt.Errorf("创建请求: %w", err)
    }
    req.Header.Set("Content-Type", "application/json")

    resp, err := client.Do(req)
    if err != nil {
        return "", fmt.Errorf("请求外部 API: %w", err)
    }
    // 无论成功还是失败，都要释放响应体，避免测试中的连接资源滞留。
    defer resp.Body.Close()

    body, err := io.ReadAll(resp.Body)
    if err != nil {
        return "", fmt.Errorf("读取响应: %w", err)
    }
    if resp.StatusCode >= http.StatusBadRequest {
        return "", fmt.Errorf("外部 API 返回 %s: %s", resp.Status, body)
    }

    var result CreateOrderResponse
    if err := json.Unmarshal(body, &result); err != nil {
        return "", fmt.Errorf("解析响应: %w", err)
    }
    return result.Status, nil
}

这个函数把“网络失败”和“HTTP 错误”分开：client.Do 返回错误通常代表请求没有得到可用响应，而 500 仍然是一个正常收到的 HTTP 响应，应该由状态码分支处理。这个区分正是外部 API 测试最值得保留的边界。

让测试服务把错误请求尽早暴露出来

测试中用 handler 记录并检查契约。断言放在服务端，失败时能直接指出客户端发来的方法、路径、请求头或 JSON 内容不对；客户端侧再断言最终业务结果。

package orderapi

import (
    "encoding/json"
    "net/http"
    "net/http/httptest"
    "testing"
)

func TestCreateOrderAgainstTestServer(t *testing.T) {
    server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        // 先检查 HTTP 契约，避免错误请求继续进入响应逻辑。
        if r.Method != http.MethodPost || r.URL.Path != "/v1/orders" {
            http.Error(w, "请求方法或路径不正确", http.StatusBadRequest)
            return
        }
        if got := r.Header.Get("Content-Type"); got != "application/json" {
            http.Error(w, "Content-Type 不正确", http.StatusUnsupportedMediaType)
            return
        }

        var request CreateOrderRequest
        // Decoder 直接读取请求体，解析失败时返回 400，模拟上游契约校验。
        if err := json.NewDecoder(r.Body).Decode(&request); err != nil || request.OrderID == "" {
            http.Error(w, "订单号不能为空", http.StatusBadRequest)
            return
        }

        w.Header().Set("Content-Type", "application/json")
        // 测试服务只返回客户端关心的最小字段。
        _, _ = w.Write([]byte(`{"status":"accepted"}`))
    }))
    // NewServer 创建的服务必须在测试结束时关闭。
    defer server.Close()

    status, err := createOrder(server.Client(), server.URL, "A-1001")
    if err != nil {
        t.Fatalf("创建订单失败: %v", err)
    }
    if status != "accepted" {
        t.Fatalf("状态 = %q，想要 accepted", status)
    }
}

这里优先使用 server.Client()，它是为测试服务配置好的客户端。对于普通 HTTP 服务，http.DefaultClient 也能访问 server.URL，但显式传入独立客户端更容易避免全局 Transport、代理或超时配置污染测试。

成功响应和上游 500 要分开验收

一个真实的外部 API 替身不能只返回成功。可以让 handler 根据订单号返回 500，确认客户端把上游错误保留在错误信息中，而不是把它误判为“订单创建成功”。

func TestCreateOrderPropagatesUpstreamError(t *testing.T) {
    server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        // 用固定输入触发上游失败，测试失败路径而不是随机网络异常。
        w.Header().Set("Content-Type", "application/json")
        w.WriteHeader(http.StatusBadGateway)
        _, _ = w.Write([]byte(`{"error":"upstream overloaded"}`))
    }))
    defer server.Close()

    _, err := createOrder(server.Client(), server.URL, "retry-me")
    if err == nil {
        t.Fatal("上游返回 502 时应该得到错误")
    }
    // 错误中保留状态码和响应内容，方便调用方记录和决定是否重试。
    if !strings.Contains(err.Error(), "502") || !strings.Contains(err.Error(), "upstream overloaded") {
        t.Fatalf("错误信息没有保留上游响应: %v", err)
    }
}

上面的示例需要在 import 中加入 strings。文章重点不是让每个测试都复制一份 handler，而是把成功、客户端错误、上游错误分别表达出来。项目较大时可以抽出“按订单号返回结果”的测试工厂，仍然保持每个用例只修改自己的输入和响应。

关闭顺序决定测试是否干净

客户端收到响应后要关闭 resp.Body，测试服务也要调用 server.Close。官方文档说明，Server.Close 会关闭服务并等待当前请求完成；如果测试故意保持长连接，可以额外调用 CloseClientConnections 关闭到测试服务的开放连接。

func TestServerCleanupBoundary(t *testing.T) {
    server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        // 返回一个可读取的最小响应，供客户端验证并关闭 Body。
        _, _ = w.Write([]byte("ok"))
    }))
    defer server.Close()

    resp, err := server.Client().Get(server.URL)
    if err != nil {
        t.Fatalf("请求测试服务失败: %v", err)
    }
    // 这里显式关闭响应体，和被测客户端内部的资源责任保持一致。
    defer resp.Body.Close()

    if resp.StatusCode != http.StatusOK {
        t.Fatalf("状态码 = %d，想要 200", resp.StatusCode)
    }
}

// 需要模拟连接没有及时归还时，再使用 CloseClientConnections 做额外清理。
func closeOpenTestConnections(server *httptest.Server) {
    server.CloseClientConnections()
}

若需要测试 HTTPS，可用 httptest.NewTLSServer，并使用它返回的 server.Client()，因为该客户端信任测试证书。若要先修改服务配置再启动，则选择 NewUnstartedServer，配置完成后调用 Start 或 StartTLS；配置应发生在第一次启动或创建客户端之前。

发布前的测试清单

• 请求方法、路径和关键请求头是否由 handler 明确检查？
• 请求体解析失败、字段缺失和格式错误是否有独立响应？
• 200、4xx、5xx 是否分别断言了状态码和业务结果？
• 被测客户端是否把网络错误与 HTTP 错误区分开？
• 每个响应体是否关闭，所有 NewServer 是否最终 Close？
• 需要 TLS、HTTP/2 或自定义配置时，是否选择了正确的 httptest 构造函数？

常见问题

为什么不直接 mock http.Client？

如果只想验证业务分支，mock Transport 或接口会更轻；但要验证方法、路径、请求头、编码和响应体关闭，httptest.Server 能保留真实 HTTP 层的契约，定位错误更直接。

server.URL 能不能写死？

不要写死端口。每次测试使用 server.URL，让 httptest 管理监听地址，避免并行测试抢占固定端口。

为什么收到 500 还要读取响应体？

响应体经常包含错误码或限流信息。先读取并关闭，再把有用信息放入错误返回，调用方才能决定记录、重试或降级。

什么时候用 NewTestServer？

当前 Go 官方文档把它作为测试中的推荐构造方式，并默认使用进程内网络实现；如果项目工具链尚不支持它，可以继续使用 NewServer，并用 defer 显式 Close。