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。第一次调用返回自定义可重试错误,第二次返回 503 Service Unavailable,第三次返回 200 OK;传输层同时断言请求方法、URL 和 Accept Header,因此一个主示例即可覆盖请求构造、错误分类和重试次数。
将以下内容保存为 client_roundtripper_test.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)
}运行测试:
go test -v预期输出
=== 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 等操作,还必须判断请求体能否重放以及业务操作是否幂等。传输错误“可以重试”并不等于业务请求“可以安全重复”;生产客户端还应限制最大尝试次数、设置明确超时,并为需要重试的非幂等操作设计幂等键。