当前位置：首页 > 文章列表 > Golang > Go教程 > 封装可重试的 JSON API 客户端并限制重试边界

封装可重试的 JSON API 客户端并限制重试边界

来源：17golang原创 2026-10-07 02:34:07 0浏览收藏

Go 的 JSON API 客户端要做重试，关键不是把 client.Do(req) 放进循环，而是先划清“什么能重试、最多重试几次、什么时候必须停”。下面这个封装只对网络错误和 429/5xx 做有限重试；4xx、JSON 解码失败、调用方取消和总超时直接返回。请求体每轮重新创建，响应体每轮关闭，避免重试后得到空 Body 或连接复用异常。

要点速览

把最大尝试次数、总超时和退避上限放进一个策略对象。
先保存 JSON 字节，再用 bytes.NewReader 为每次尝试创建新的 Request。
副作用请求默认不重试；只有幂等方法或服务端提供幂等键时才放宽。

先把可重试条件和停止条件写清楚

http.Client.Do 返回网络层错误时，通常还没有拿到可用响应；拿到 HTTP 响应后，非 2xx 本身不会变成 Go error。因此策略函数要同时看 err 和状态码。429 表示需要尊重服务端限流，5xx 多数是临时服务端故障；认证失败、参数错误和资源不存在则不应靠重试解决。

结果	默认动作	原因
网络错误	有限重试	连接、解析或暂时不可达可能恢复
429、502、503、504	退避后重试	让服务端和代理有恢复窗口
400、401、403、404	立即返回	通常需要修正输入或凭据
JSON 解码错误	立即返回	重试不会修复契约不一致

为每次尝试重建 JSON 请求，避免 Body 被读空

请求体是流，第一次发送后不能假设它还能从头读取。做法是先把结构编码成稳定的字节切片，随后每轮使用 bytes.NewReader(payload) 和 http.NewRequestWithContext 创建新请求。http.Client 可以长期复用，但 Request 应按尝试重新生成。

Go JSON API 客户端中 JSON payload、bytes.Reader、http.Request、http.Client 与 Response Body 的请求重建关系说明图 — 图1：请求重建与响应资源边界说明图，不是运行截图或执行证据。

// 这段代码把 JSON 字节作为可重放输入，每次尝试都创建新的请求。
func newJSONRequest(ctx context.Context, method, endpoint string, payload []byte) (*http.Request, error) {
    req, err := http.NewRequestWithContext(ctx, method, endpoint, bytes.NewReader(payload))
    if err != nil {
        return nil, fmt.Errorf("创建请求: %w", err)
    }
    req.Header.Set("Content-Type", "application/json") // 明确请求体格式，避免服务端按表单解析。
    return req, nil
}

把重试条件、退避上限和取消信号放在同一层

重试封装要有一个总生命周期，而不是每次失败都重新获得一段新时间。用父级 context.Context 控制调用方取消，用总超时限制请求与退避的合计时长；每次 Do 返回后先关闭 Body，再决定是否继续。

Go retryPolicy 连接网络错误、429/5xx、4xx、context.Context、退避 timer 与最终 error 的边界结构图 — 图2：重试策略与生命周期边界结构图，不是运行截图或执行证据。

// DoJSON 只重试可恢复结果，并用次数、总超时和退避上限共同收口。
func DoJSON(ctx context.Context, client *http.Client, method, endpoint string, in, out any) error {
    payload, err := json.Marshal(in) // 先固定字节，避免重试时请求体已经被消费。
    if err != nil {
        return fmt.Errorf("编码请求: %w", err)
    }
    ctx, cancel := context.WithTimeout(ctx, 8*time.Second) // 总预算覆盖请求和等待。
    defer cancel() // 释放计时器，避免派生 context 留到父级结束。

    const maxAttempts = 3
    for attempt := 1; attempt = 200 && resp.StatusCode

示例中的三个辅助函数只负责判定和等待：网络错误要排除调用方已经取消的情况；状态码函数只放行 429 与明确的临时 5xx；等待函数必须用 select 同时监听计时器和 ctx.Done()。这样总超时到达时，不会还在退避。