Ruby HTTPX Retries 插件如何配置重试条件、次数与异常捕获？

在 Ruby 生态中，HTTPX 是一个强调并发和插件化设计的 HTTP 客户端。它的插件机制允许开发者按需加载功能，而 Retries 插件专门用于处理失败请求的自动重试。对于依赖外部服务的应用来说，网络闪断、DNS 短暂解析失败、连接被重置、反向代理返回 502 这类问题并不罕见。如果每次失败都直接抛给调用方，系统稳定性会明显下降。Retries 插件能够把这些重试逻辑统一封装起来，避免在业务代码里到处写循环和 sleep。

该插件默认行为比较保守，但通过参数可以调整重试次数、等待时间、可重试的异常类型以及状态码范围。理解这些配置项的组合方式，是在不放大故障的前提下获得更好可用性的关键。

Retries 插件的加载与基础行为

HTTPX 的插件通过 plugin 方法在会话创建时加载。插件参数可以直接传入，例如下面的代码创建了一个带重试能力的会话，最大重试次数为 3 次，每次重试前等待 2 秒。

require "httpx"

http = HTTPX.plugin(:retries, max_retries: 3, retry_after: 2)

response = http.get("https://ipipp.com/api/data")
puts response.status

在这个配置下，如果请求因为网络层错误失败，插件会先捕获异常，然后根据重试次数决定是否再次发起相同请求。这里的 3 次指的是初始请求失败后额外重试的次数，因此总请求次数最多为 4 次。如果三次重试仍然失败，最后一次捕获的异常会继续抛出，调用方可以像没有插件时一样进行处理。

需要特别说明的是，插件不会无条件重试所有请求。对于默认配置，只有被判定为可重试的异常才会触发下一轮请求。这样设计是为了避免把业务错误或不可恢复错误也纳入重试范围，例如请求体已经发送但服务器返回 4xx 这类客户端错误，通常重试没有意义。

重试条件与状态码配置

Retries 插件提供两个核心条件参数：retry_on 用于指定哪些异常类可以触发重试，retry_on_status 用于声明哪些 HTTP 响应状态码需要重试。两者可以组合使用，只要满足其中一个条件，插件就会进入重试流程。

http = HTTPX.plugin(
  :retries,
  max_retries: 5,
  retry_after: 1,
  retry_on: [HTTPX::TimeoutError, HTTPX::ConnectionError],
  retry_on_status: [429, 500, 502, 503, 504]
)

上面这段配置扩展了默认行为。异常类方面，HTTPX::TimeoutError 覆盖读写超时，HTTPX::ConnectionError 覆盖连接建立失败、连接被重置等情况。状态码方面，429 表示请求过于频繁，通常服务端希望客户端稍后重试；5xx 中的 500、502、503、504 大多属于临时性服务端故障，重试有较高概率成功。像 400、401、403、404 这类状态码不应加入重试列表，因为它们不具备时间自愈性。

条件判断顺序一般先检查异常类型，再检查状态码，但开发者不需要依赖这个顺序，重要的是把可恢复条件写清楚。另外，如果只想重试特定异常而忽略所有状态码，可以省略 retry_on_status；反过来，只想对某些状态码重试，可以设置 retry_on 为一个空数组。

异常捕获范围与自定义回调

插件内部会捕获 retry_on 中声明的异常，如果异常不在列表中，会立即向调用方抛出，不会占用重试次数。例如默认条件下，HTTPX::ResponseError 是否会被捕获取决于插件版本和参数设置。如果应用希望所有 HTTPX 内部错误都触发重试，可以把 HTTPX::ResponseError 或更宽泛的 StandardError 加入列表，但更宽泛捕获可能掩盖真正的问题。

除了固定参数，插件还支持通过代码块或回调在每次重试前执行逻辑。可以使用 on_retry 参数传入一个可调用对象，它接收请求和错误信息，便于记录日志、调整等待时间或上报监控。下面是一个自定义回调的示例。

require "httpx"

retry_callback = lambda do |request, error|
  puts "请求失败: #{request.uri}，错误: #{error.class}，准备重试"
end

http = HTTPX.plugin(
  :retries,
  max_retries: 3,
  retry_after: 2,
  retry_on: [HTTPX::ConnectionError],
  on_retry: retry_callback
)

http.get("https://ipipp.com/api/data")

回调函数对于排查间歇性故障很有帮助。例如可以在日志中记录第几次重试、失败原因和当前 URI，再结合监控系统观察哪些域名或接口更容易触发重试。需要注意回调执行时需要线程安全，如果多个请求并发重试，回调内不要操作非线程安全的共享变量。

重试次数、等待时间与幂等性考量

max_retries 和 retry_after 是最直观的控制参数，但它们的取值需要结合业务场景。对于实时性要求高的接口，重试次数不宜超过 2 次，等待时间最好在几百毫秒以内；对于后台任务或消息通知，可以适当放宽到 5 次，并采用 1 秒以上的间隔。较大的 retry_after 能缓解服务端压力，但会拉长调用方阻塞时间。

HTTPX 的 Retries 插件默认使用固定等待时间，如果需要指数退避和随机抖动，可以在回调中让当前线程休眠动态时长，或者根据重试次数计算等待时间。不过要注意，插件内部已经根据 retry_after 做了基础等待，如果回调里再手动 sleep，可能造成等待时间叠加。更推荐调整 retry_after 配合 on_retry 实现记录，而不在回调里执行阻塞操作。

幂等性是启用自动重试前必须评估的问题。GET、HEAD、OPTIONS 这类请求通常可以安全重试；POST、PUT、PATCH、DELETE 在多数情况下不是幂等的，但如果服务端使用幂等键或业务本身允许重复提交，也可以开启重试。一个折中方案是仅对只读请求启用 Retries 插件，对写请求使用单独的 HTTPX 会话并且不加载该插件，避免重复创建订单或重复扣款。

完整示例与调试建议

下面给出一个相对完整的 Retries 插件配置，它结合了异常捕获、状态码重试、最大重试次数和回调日志。

require "httpx"

http = HTTPX.plugin(
  :retries,
  max_retries: 4,
  retry_after: 0.8,
  retry_on: [HTTPX::TimeoutError, HTTPX::ConnectionError, HTTPX::ResponseError],
  retry_on_status: [408, 429, 500, 502, 503, 504],
  on_retry: lambda { |request, error|
    puts "重试请求：#{request.uri}，原因：#{error.class}"
  }
)

response = http.get("https://ipipp.com/api/status")
puts response.status
puts response.body.to_s

调试重试策略时，可以先在开发环境把 retry_after 设成一个很小的值，并把回调日志打开，观察哪些请求在重试。也可以临时把 max_retries 调高以验证异常路径，但上线前要恢复为合理值。通过日志确认可重试条件没有覆盖到不可恢复错误，避免把问题隐藏起来。

最后要再次强调，自动重试不是解决服务端故障的根本手段。如果某个接口持续返回 503，重试只会增加服务端压力。此时应该配合熔断器、超时控制和监控告警一起使用，让 Retries 插件只负责处理短期抖动，而不是掩盖系统性问题。

Ruby HTTPXRetries插件重试机制修改时间：2026-08-24 14:00:49