在Ruby生态中，Faraday作为可插拔的HTTP客户端抽象层，允许开发者自由切换底层适配器。当选用httpx作为后端传输时，网络层面的超时不会以统一的Faraday::TimeoutError直接暴露，而是具体表现为Faraday::Adapter::Httpx::TimeoutError。这个异常类处在Faraday异常体系的末端，专门描述由httpx引擎触发的连接、读取或写入超时。很多人在编写服务间调用代码时，只 rescue 了 StandardError，导致无法针对适配器超时做精细化补偿，进而让整个调用链失去弹性。
异常类的继承结构与触发路径
要正确处理Faraday::Adapter::Httpx::TimeoutError，首先要弄清它在Ruby常量树中的位置。该异常定义在faraday/adapter/httpx模块内部，继承自Faraday::TimeoutError，而后者又继承自Faraday::ClientError，最终归到Faraday::Error。由于httpx自身拥有独立的HTTPX::TimeoutError体系，适配器在 rescue 底层错误时会做一层包装，把原始信息附带在cause方法中。这种设计保留了完整的异常链，使得我们可以在 Rescue 块里通过 $!.cause 拿到最初的网络层超时原因。
触发路径通常分为三段。第一段是连接建立阶段，若TCP握手超过httpx的connect_timeout，会抛出底层超时；第二段是请求发送阶段，当请求体写入慢于write_timeout时触发；第三段是响应读取阶段，服务器迟迟不返回完整body会突破read_timeout。适配器在这三个点捕获HTTPX异常并统一转为Faraday::Adapter::Httpx::TimeoutError。理解这三段有助于我们分开配置超时参数，而不是给所有阶段设置同一个模糊的阈值。
下面这段Ruby代码展示了异常类的归属判断，可以在控制台快速验证继承关系，避免线上误捕：
require 'faraday'
require 'faraday/adapter/httpx'
puts Faraday::Adapter::Httpx::TimeoutError.ancestors.inspect
# 输出中包含 Faraday::Adapter::Httpx::TimeoutError
# 以及 Faraday::TimeoutError、Faraday::ClientError、Faraday::Error
# 说明它处于 Faraday 自定义错误体系的子类位置
begin
raise Faraday::Adapter::Httpx::TimeoutError, 'simulated'
rescue Faraday::TimeoutError => e
puts "caught as timeout: #{e.class}"
end
在中间件中统一拦截与转换异常
直接在业务代码里写一大堆 rescue Faraday::Adapter::Httpx::TimeoutError 既冗余又容易遗漏。更好的方式是通过自定义Faraday中间件，在调用栈的底端做异常捕获，并将其转换为项目内部的领域错误，例如 GatewayTimeoutError。这样上层业务只依赖自己定义的异常，不会耦合具体适配器实现。如果未来从httpx切到net_http，只需改中间件映射逻辑，业务代码零改动。
中间件需要继承自Faraday::Middleware，并重写call方法。在yield让请求继续往下走时用 begin rescue 包住，捕获到适配器超时后，读取original = e.cause获取httpx原始错误，再把e的message和original的backtrace合并，抛出新的领域异常。这里要注意不能简单地 rescue StandardError，否则会把4xx、5xx响应也吞掉，那些应当走响应中间件处理，而不是当异常。
以下示例给出一个最小可用的超时转换中间件，展示了如何保留异常链并附加上下文：
class TimeoutNormalizer < Faraday::Middleware
def call(env)
@app.call(env)
rescue Faraday::Adapter::Httpx::TimeoutError => e
original = e.cause
ctx = "url=#{env.url} method=#{env.method}"
raise GatewayTimeoutError.new("httpx timeout: #{ctx} | #{e.message}"), cause: original
end
end
# 注册到 Faraday 连接
conn = Faraday.new(url: 'https://api.ippipp.com') do |f|
f.use TimeoutNormalizer
f.adapter :httpx
end
上述代码里 GatewayTimeoutError 应当是你项目里预定义的类，可以继承 StandardError 并携带 retryable: true 这样的标记。通过这种方式，重试机制只需判断错误对象的 retryable 属性，而不必关心底层是不是 httpx 适配器。
结合重试与熔断的实战策略
捕获异常只是第一步，真正让系统稳健的是后续的容错策略。对于Faraday::Adapter::Httpx::TimeoutError，多数情况属于瞬时网络抖动，适合有限次数的指数退避重试。但若是后端服务彻底雪崩，重试只会放大流量，此时应当配合熔断器，比如使用 stoplight 或 selbstlader gem，在错误率超阈值后快速失败。重试逻辑建议放在独立中间件，与前面的异常归一中间件分离，保持单一职责。
在配置httpx适配器时，应当显式传入超时选项，而不是依赖默认值。Faraday的httpx适配器接受 request: { timeout: { connect: 1, read: 2 } } 这类结构。把连接超时设短、读取超时设稍长，符合大多数内部API的特征。同时开启httpx的 persistent 连接池，能降低握手超时的发生频率。下面的代码演示了带超时与重试中间件的完整装配：
require 'faraday'
require 'faraday/adapter/httpx'
class RetryOnTimeout < Faraday::Middleware
MAX = 3
def call(env)
retries = 0
begin
@app.call(env)
rescue Faraday::Adapter::Httpx::TimeoutError
retries += 1
retry if retries < MAX
raise
end
end
end
conn = Faraday.new(url: 'https://ipipp.com') do |f|
f.use TimeoutNormalizer
f.use RetryOnTimeout
f.adapter :httpx, request: {
timeout: { connect: 1, read: 3, write: 2 }
}
end
begin
resp = conn.get('/v1/status')
puts resp.status
rescue GatewayTimeoutError => e
puts "业务层捕获: #{e.message}"
end
上面的装配顺序很关键：TimeoutNormalizer 在前，先把适配器异常转成领域错误；RetryOnTimeout 在后，只针对适配器原始超时重试，避免对已经归一化的领域错误重复重试。若顺序颠倒，RetryOnTimeout 就永远 capture 不到 Faraday::Adapter::Httpx::TimeoutError，因为已经被前面的中间件转走了。
最后强调日志记录的要点。当异常经多层包装后，务必在日志里输出 e.cause 的 class 和 message，否则运维看到的全是 GatewayTimeoutError，无法判断是连接慢还是读慢。建议在结构化日志中增加 adapter_timeout_type 字段，由中间件从 original 对象提取具体阶段填入。这样在 Grafana 里就能按阶段聚合超时，精准定位是网络问题还是后端性能问题。
Ruby FaradayHttpx适配器超时异常处理修改时间：2026-08-22 02:26:00