Go 自定义 RoundTripper 怎么设计重试：请求体复用、幂等性与错误返回

给 Go 服务加 HTTP 重试时，最容易被忽略的是请求体：GET 重试通常只需重新发起请求，POST 如果没有可重放的 body，却可能在第一次失败后拿着空请求继续发送。一个可靠的自定义 http.RoundTripper 应先确定哪些方法允许重试，再确认 body 能否重新打开，最后把最后一次失败原样交还给调用方。

把重试写进 Transport 可以复用到多个调用方，但不要把“遇到 error 就再发一次”当成策略。请求体复用、幂等性判断和错误保留必须同时成立。

先把重试 Transport 的职责划清

RoundTripper 接收一个完整的 *http.Request，返回响应或错误。它适合做跨接口一致的传输策略，例如对临时网络错误或少量 5xx 做有限重试；它不应该猜测业务是否已经写入订单，也不应该吞掉调用方需要记录的原始错误。

这里设计Transport的时候，至少要把四个核心参数明确定义出来：最大重试次数、允许重试的HTTP方法列表、判定为临时故障的状态码列表、每次重试前的等待规则。要是把这些判断逻辑随便塞在超长循环里，后续排查问题的时候根本没法确认POST请求有没有被意外重发。

调用方真正关心的是请求能不能再发一次

GET、HEAD、OPTIONS这类请求本身就不需要提交业务侧的请求体，重试的边界很清晰。PUT和DELETE能不能重试，完全要看对应接口有没有按照幂等语义来实现；POST请求默认不要开自动重试，除非调用方明确传入了幂等键，或者业务协议本身就已经保证重复提交不会生成重复的业务数据。

请求体还有一个独立问题：http.NewRequest 接收 *bytes.Reader、*strings.Reader 或 *bytes.Buffer 时，标准库可能为请求设置 GetBody。如果 body 来自文件、流或自定义 Reader，就不能假设它一定存在。没有 GetBody 时，最安全的默认行为是放弃重试，而不是把已经读过的流强行复用。

参数设计：把可重试条件写成小函数

type RetryTransport struct {
	Base       http.RoundTripper
	MaxRetries int
	Backoff    func(attempt int) time.Duration
}

func retryableMethod(method string) bool {
	switch method {
	case http.MethodGet, http.MethodHead, http.MethodOptions:
		return true
	default:
		return false
	}
}

func retryableStatus(code int) bool {
	return code == http.StatusBadGateway ||
		code == http.StatusServiceUnavailable ||
		code == http.StatusGatewayTimeout
}

这里故意没有把所有 5xx 都纳入重试，也没有默认接纳 POST。规则越窄，调用方越容易解释一次请求为什么被再次发送。生产代码还应把退避上限和随机抖动放在 Backoff 内，避免大量客户端同时撞回服务端。

实现 RoundTrip 时先保存原始请求，再重建 body

func (t *RetryTransport) RoundTrip(req *http.Request) (*http.Response, error) {
	base := t.Base
	if base == nil {
		base = http.DefaultTransport
	}
	max := t.MaxRetries
	if max  0 {
			current = req.Clone(req.Context())
			if req.GetBody != nil {
				body, err := req.GetBody()
				if err != nil {
					return nil, err
				}
				current.Body = body
			}
		}

		resp, err := base.RoundTrip(current)
		if attempt == max || (!retryableResponse(resp, err)) {
			return resp, err
		}
		if resp != nil && resp.Body != nil {
			resp.Body.Close()
		}
		if t.Backoff != nil {
			time.Sleep(t.Backoff(attempt + 1))
		}
	}
}

func retryableResponse(resp *http.Response, err error) bool {
	if err != nil {
		return true
	}
	return resp != nil && retryableStatus(resp.StatusCode)
}

示例里把原始 req 当作模板，第二次尝试才通过 Clone 创建副本并调用 GetBody。响应体在决定重试前必须关闭，否则连接可能无法回收到连接池。网络错误是否可重试仍可继续收窄，例如只接纳暂时性错误，而不是所有 DNS、证书和上下文取消错误。

错误处理要保留最后一次失败的语义

如果最后一次返回的是响应，即使状态码是 503，也应把响应交给调用方，让上层决定是否读取响应体和记录服务端请求 ID。如果最后一次是网络错误，不要只返回一个“重试失败”的新错误；可以用 fmt.Errorf("retry %d times: %w", max, err) 增加上下文，同时保留 errors.Is 和 errors.As 的判断能力。

还有一个常见遗漏：调用方的 context.Context 在退避期间可能已经取消。等待前应该用可取消的定时器，而不是无条件 time.Sleep。这样超时链路才不会出现客户端已经放弃、Transport 仍在后台等待的错觉。

哪些请求不适合交给通用重试

• POST 创建订单、扣款或发送消息，除非业务提供幂等键并明确规定重复请求的处理方式。
• 带一次性流式 body 的上传请求，除非能重新打开数据源并确认偏移量。
• 由调用方主动取消的请求、证书校验失败和明显的参数错误，这些通常不属于临时故障。
• 已经收到业务成功响应但读取响应体失败的场景，是否重试不能由 Transport 单独决定。

用一个小测试确认重试真的发生了

测试时不要只断言最终返回 200，还要记录服务端收到的次数，并检查第二次请求的 body。可以用 httptest.NewServer 返回一次 503、第二次返回 200，再把一个 bytes.Reader 交给 http.NewRequest。如果服务端第二次读到的内容为空，说明 GetBody 没有被正确使用。

var calls atomic.Int32
server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
	if calls.Add(1) == 1 {
		w.WriteHeader(http.StatusServiceUnavailable)
		return
	}
	body, _ := io.ReadAll(r.Body)
	if string(body) != `{"name":"demo"}` {
		http.Error(w, "body mismatch", http.StatusBadRequest)
		return
	}
	w.WriteHeader(http.StatusOK)
}))
defer server.Close()

写完逻辑之后验证的时候至少要覆盖三个点：总请求调用次数符合预设的重试规则、第二次发起请求的请求体内容和第一次完全一致、达到最大重试次数之后返回的响应或错误依然能被上层调用方正常识别。把这三个场景写到回归测试用例里，比单纯在日志里打印retrying关键字有用得多。

一份可以放进代码评审的检查清单

提交前逐项确认：重试方法是否有业务依据；body 没有 GetBody 时是否安全停止；重试前是否关闭响应体；退避是否受 context 控制；最后一次响应和错误是否保留；测试是否覆盖第一次临时失败、第二次成功和连续失败。

相关问题

为什么不直接在业务函数里写 for 循环？

业务层的逻辑更清楚幂等键规则、订单当前状态和可接受的错误范围，所以涉及业务语义的重试逻辑要放在业务层实现。自定义Transport只适合承载那些明确通用、完全不依赖业务结果的传输层重试规则。

如果已经决定发起重试，之前拿到的旧响应只是中间结果，要主动把它关闭掉；如果已经达到最大重试次数结束流程，就不要关闭最终返回的响应体，把读取和关闭的权责交还给上层调用方。

不能直接默认可以重试。超时可能发生在请求还没到达服务端的阶段，也可能发生在服务端已经完成业务数据写入的阶段。对有副作用的请求做重试，必须搭配幂等键，或者先查询服务端的已处理状态做判断。

Response.Body 关闭后还能把响应交给调用方吗？

请求超时后一定可以再试吗？

自定义 RoundTripper 的价值在于统一传输层行为，但它的边界也必须统一：只重试能安全重放的请求，按证据判断临时失败，最后把可诊断的结果交给上层。