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

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

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

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

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

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

// 这段代码把 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，再决定是否继续。

// 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()。这样总超时到达时，不会还在退避。

POST 不是“失败就再发一次”

GET、HEAD 通常更容易重试，但 JSON API 常见的 POST 可能已经在服务端完成写入，只是响应在网络上丢失。对这类请求，建议默认关闭重试；如果服务端支持幂等键，才把同一个业务请求 ID 放进 Header，并确认服务端按该键去重。即使使用 PUT，也要先确认接口语义确实幂等。

生产参数可以先按“最多 3 次、总预算 8 秒、单次退避不超过 2 秒”起步，再结合服务端的 Retry-After 和业务延迟调整。不要把退避时间、HTTP 客户端超时、调用方 deadline 叠加成读者无法判断的多个独立预算。

延伸问答：哪些边界最容易漏掉

为什么不直接复用同一个 Request？

Body 是流，第一次发送可能已经读到末尾。重新创建 Request 能明确恢复读取位置，也能为每轮绑定仍然有效的 context。

4xx 都应该立即返回吗？

默认是这样，但 408 或接口明确约定可恢复的 409 需要单独建策略；不要把所有 4xx 一股脑加入重试。

响应体只在成功时关闭可以吗？

不可以。429、5xx 和读取失败路径同样会拿到 Body，必须在判定下一次尝试前关闭。

客户端要不要每次调用都 new？

不建议。官方文档说明 Client/Transport 含连接复用状态并可并发使用，应在服务生命周期内复用。

把重试看成一次受约束的资源操作：输入可重建、响应可回收、条件可解释、时间可截止。这样封装出来的 JSON API 客户端，出了问题能返回足够上下文，也不会因为“再试一次”把副作用扩大。