Go / 系统课时

测试出站 HTTP 客户端

测试出站 HTTP 客户端

出站 HTTP 客户端最难测试的不是 JSON 解析,而是请求如何构造、哪些失败应该重试,以及错误能否被稳定分类。本课通过替换 http.Client.Transport 注入自定义 RoundTripper,不访问真实网络也能精确控制每次响应并验证重试边界。

学习目标

  • 用可替换的 http.RoundTripper 截获并检查最终出站请求
  • 模拟可重试传输错误、503 与成功响应,验证重试次数和停止条件
  • 区分上下文取消、截止时间、可重试错误和 HTTP 状态码

为什么替换 RoundTripper

http.Client 会把单次 HTTP 传输委托给 Transport,其接口类型是 http.RoundTripper。测试时注入自定义实现,请求仍然经过 http.Client.Do 的正常调用路径,但不会继续访问 DNS、TCP 或真实远端服务。

这种方式比直接 mock 业务方法更接近客户端边界:测试既能检查最终的 Method、URL 和 Header,也能让第 1、2、3 次调用分别返回不同结果,从而验证真实的重试决策。

RoundTripper 重试测试流程

构造可替换的传输层

下面把函数适配成 RoundTripper。第一次调用返回自定义可重试错误,第二次返回 503 Service Unavailable,第三次返回 200 OK;传输层同时断言请求方法、URL 和 Accept Header,因此一个主示例即可覆盖请求构造、错误分类和重试次数。

将以下内容保存为 client_roundtripper_test.go:

go
package client

import (
    "context"
    "errors"
    "fmt"
    "io"
    "net/http"
    "strings"
    "testing"
)

type roundTripFunc func(*http.Request) (*http.Response, error)

func (f roundTripFunc) RoundTrip(r *http.Request) (*http.Response, error) {
    return f(r)
}

type retryableError struct {
    message string
}

func (e *retryableError) Error() string   { return e.message }
func (e *retryableError) Retryable() bool { return true }

type retryable interface {
    Retryable() bool
}

func shouldRetry(err error, status int) bool {
    if errors.Is(err, context.Canceled) || errors.Is(err, context.DeadlineExceeded) {
        return false
    }
    if err != nil {
        var r retryable
        return errors.As(err, &r) && r.Retryable()
    }
    return status == http.StatusBadGateway ||
        status == http.StatusServiceUnavailable ||
        status == http.StatusGatewayTimeout
}

type APIClient struct {
    client      *http.Client
    maxAttempts int
}

func (c *APIClient) GetItems(ctx context.Context, baseURL string) (string, error) {
    for attempt := 1; attempt <= c.maxAttempts; attempt++ {
        // 每次尝试重新构造 Request,避免复用已经参与过传输的请求状态。
        req, err := http.NewRequestWithContext(ctx, http.MethodGet, baseURL+"/v1/items", nil)
        if err != nil {
            return "", err
        }
        req.Header.Set("Accept", "application/json")

        resp, err := c.client.Do(req)
        if err != nil {
            if attempt < c.maxAttempts && shouldRetry(err, 0) {
                continue
            }
            return "", fmt.Errorf("request failed: %w", err)
        }

        if shouldRetry(nil, resp.StatusCode) && attempt < c.maxAttempts {
            // 重试前消费并关闭响应体,真实 Transport 才有机会复用连接。
            _, _ = io.Copy(io.Discard, resp.Body)
            _ = resp.Body.Close()
            continue
        }
        if resp.StatusCode != http.StatusOK {
            _ = resp.Body.Close()
            return "", fmt.Errorf("unexpected status: %d", resp.StatusCode)
        }

        data, readErr := io.ReadAll(resp.Body)
        _ = resp.Body.Close()
        if readErr != nil {
            return "", readErr
        }
        return string(data), nil
    }

    return "", errors.New("unreachable")
}

func TestOutboundClientWithRoundTripper(t *testing.T) {
    // 先验证明确的停止条件,避免取消、截止时间或普通 4xx 被误判为可重试。
    if shouldRetry(context.Canceled, 0) ||
        shouldRetry(context.DeadlineExceeded, 0) ||
        shouldRetry(nil, http.StatusBadRequest) {
        t.Fatal("non-retryable condition classified as retryable")
    }

    calls := 0
    transport := roundTripFunc(func(req *http.Request) (*http.Response, error) {
        calls++

        // 在真正的传输边界检查最终请求,而不是检查业务层的中间参数。
        if req.Method != http.MethodGet || req.URL.String() != "https://api.example.test/v1/items" {
            t.Fatalf("unexpected request: %s %s", req.Method, req.URL)
        }
        if req.Header.Get("Accept") != "application/json" {
            t.Fatalf("Accept = %q", req.Header.Get("Accept"))
        }

        switch calls {
        case 1:
            return nil, &retryableError{message: "temporary transport failure"}
        case 2:
            return &http.Response{
                StatusCode: http.StatusServiceUnavailable,
                Header:     make(http.Header),
                Body:       io.NopCloser(strings.NewReader("busy")),
                Request:    req,
            }, nil
        default:
            return &http.Response{
                StatusCode: http.StatusOK,
                Header:     http.Header{"Content-Type": []string{"application/json"}},
                Body:       io.NopCloser(strings.NewReader(`{"status":"ok"}`)),
                Request:    req,
            }, nil
        }
    })

    api := &APIClient{
        client:      &http.Client{Transport: transport},
        maxAttempts: 3,
    }

    body, err := api.GetItems(context.Background(), "https://api.example.test")
    if err != nil {
        t.Fatal(err)
    }
    if body != `{"status":"ok"}` {
        t.Fatalf("body = %s", body)
    }
    if calls != 3 {
        t.Fatalf("calls = %d, want 3", calls)
    }

    t.Logf("attempts=%d body=%s", calls, body)
}

运行测试:

bash
go test -v

预期输出

text
=== RUN   TestOutboundClientWithRoundTripper
    client_roundtripper_test.go:<LINE>: attempts=3 body={"status":"ok"}
--- PASS: TestOutboundClientWithRoundTripper (<TIME>)
PASS
ok      <PATH>  <TIME>

<LINE>、<PATH> 与 <TIME> 会随文件位置、模块路径和执行耗时变化。稳定结果是传输层总共被调用 3 次:可重试传输错误触发第一次重试,503 触发第二次重试,200 后立即返回响应体。

把重试条件写成可验证规则

重试策略应集中在独立函数中,而不是分散在请求流程各处。示例中的 shouldRetry 只接受两类重试条件:实现了业务约定 Retryable() bool 的传输错误,以及 502、503、504 这类暂时性服务端状态。

http.Client.Do 可能对底层传输错误进行包装,因此分类时使用 errors.Is 和 errors.As,不要匹配错误字符串。这样即使外层出现 url.Error 等包装,取消、截止时间和自定义错误类型仍能沿错误链被识别。

哪些失败不该自动重试

上下文已经取消或截止时间已到时,继续发送请求不会恢复成功,因此应立即停止。多数 4xx 表示请求本身需要修改,也不适合仅靠重复发送解决。

对于带请求体的 POST、PATCH 等操作,还必须判断请求体能否重放以及业务操作是否幂等。传输错误“可以重试”并不等于业务请求“可以安全重复”;生产客户端还应限制最大尝试次数、设置明确超时,并为需要重试的非幂等操作设计幂等键。

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

目录与阅读设置

阅读设置

17

记录一个想法

测试出站 HTTP 客户端

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

登录哪都通