Faraday是Ruby生态中广泛使用的HTTP客户端抽象库，它通过适配器模式让开发者可以自由切换底层HTTP实现，如Net::HTTP、Typhoeus、Excon以及近年来性能出色的httpx。然而，适配器的多样性也带来了错误处理上的碎片化——不同底层库抛出的异常类型各不相同，如果直接在业务代码中分别rescue这些异常，代码会变得臃肿且脆弱。Httpx适配器同样面临这个问题，但通过利用Faraday的错误映射机制，我们可以搭建一套统一的错误处理策略，将底层异常收敛成少数几个标准错误类型，从而简化上层逻辑。
Faraday的错误体系与适配器职责
Faraday定义了一套完整的错误类层次结构，所有异常都继承自Faraday::Error。在这个基类之下，主要分为几个子类：Faraday::ConnectionFailed表示无法建立连接，Faraday::TimeoutError表示请求超时，Faraday::SSLError表示证书或SSL握手问题，Faraday::ResourceNotFound对应HTTP 404，Faraday::ClientError和Faraday::ServerError分别对应4xx和5xx响应状态码。这些标准错误类型让开发者只需关注少数几个异常即可处理绝大多数失败场景。
适配器（Adapter）在Faraday中的核心职责之一，就是将底层HTTP库抛出的原始异常转换为上述标准错误类型。例如，Net::HTTP适配器会把Errno::ECONNREFUSED转换成Faraday::ConnectionFailed，把Net::OpenTimeout转换成Faraday::TimeoutError。同样，Httpx适配器也需要完成类似的映射工作。但httpx这个库本身的异常设计较为独特，它使用HTTPX::Error作为基类，其下派生了HTTPX::ConnectionError、HTTPX::TimeoutError、HTTPX::TLSError等子类，因此映射规则需要仔细配置。
理解了这个错误体系后，统一错误处理策略的第一步就是对适配器进行配置或包装，确保所有底层异常都被转换成Faraday标准错误。Faraday适配器通常已经内置了这种转换逻辑，但有些边缘情况可能未被覆盖，我们可以通过自定义中间件来补全。
Httpx适配器的错误映射与自定义扩展
在Faraday中使用Httpx适配器非常直接，只需要在连接初始化时指定adapter :httpx即可。默认情况下，这个适配器会将HTTPX::TimeoutError转换为Faraday::TimeoutError，将HTTPX::ConnectionError转换为Faraday::ConnectionFailed，将HTTPX::TLSError转换为Faraday::SSLError。但httpx还定义了一些特定错误，例如HTTPX::HTTPError表示HTTP协议层面的异常，HTTPX::ProxyError表示代理连接问题，这些在默认映射中可能被归为通用的Faraday::Error，失去了细分处理的能力。
为了构建统一而精细的错误处理策略，我们可以通过自定义中间件来扩展映射。Faraday中间件可以拦截请求和响应，同时捕获异常并进行转换。下面这段代码定义了一个名为ErrorMapping的中间件，它在请求阶段执行，一旦捕获到底层异常，就将其转换为对应的Faraday标准错误类型：
# 自定义错误映射中间件
class ErrorMapping < Faraday::Middleware
def call(env)
@app.call(env)
rescue HTTPX::ProxyError => e
raise Faraday::ConnectionFailed, "代理连接失败: #{e.message}"
rescue HTTPX::HTTPError => e
raise Faraday::ClientError, "HTTP协议错误: #{e.message}"
rescue HTTPX::Error => e
# 未明确映射的HTTPX错误统一视为连接问题
raise Faraday::ConnectionFailed, e.message
end
end
# 使用中间件
conn = Faraday.new(url: 'https://api.ippipp.com') do |f|
f.use ErrorMapping
f.adapter :httpx
end
上面的代码中，call方法先调用@app.call(env)执行后续中间件和适配器，如果抛出了HTTPX::ProxyError或HTTPX::HTTPError，就分别转换成Faraday::ConnectionFailed和Faraday::ClientError。这个转换过程发生在中间件栈的出栈阶段，因此可以覆盖底层适配器抛出的所有异常。通过这种方式，我们可以根据业务需要精确控制错误的分类，进而统一后续的处理逻辑。
需要注意的是，中间件的加载顺序会影响异常捕获的时机。建议将错误映射中间件放在栈的首位（使用f.use在f.adapter之前），这样它就能包裹住整个请求过程，包括连接建立、请求发送和响应解析等全部阶段。
统一错误处理策略的实现与最佳实践
有了稳定的错误映射后，下一步是实现统一的错误处理策略。这个策略通常包括三个层面：错误分类、错误恢复（如重试）和错误记录。我们可以创建一个专门处理Faraday调用的模块，将常见的错误处理逻辑封装起来，供业务代码复用。
下面给出一个完整的示例，展示如何构建一个HttpClient类，它内部使用Faraday和Httpx适配器，并集中处理所有可能的异常。该类定义了get、post等常用方法，每个方法都经过统一的handle_request包装，在其中执行重试和错误分类逻辑：
require 'faraday'
require 'faraday/retry'
require 'logger'
class HttpClient
RETRYABLE_ERRORS = [
Faraday::TimeoutError,
Faraday::ConnectionFailed,
Faraday::SSLError
].freeze
def initialize(base_url:, logger: Logger.new(STDOUT))
@logger = logger
@conn = Faraday.new(url: base_url) do |f|
f.request :retry, max: 3, interval: 0.5, interval_randomness: 0.5,
exceptions: RETRYABLE_ERRORS
f.use ErrorMapping
f.adapter :httpx
f.response :logger, logger, bodies: true
end
end
def get(path, params = {})
handle_request { @conn.get(path, params) }
end
def post(path, body = {})
handle_request { @conn.post(path, body.to_json, 'Content-Type' => 'application/json') }
end
private
def handle_request
yield
rescue Faraday::TimeoutError => e
@logger.error("请求超时: #{e.message}")
raise
rescue Faraday::ConnectionFailed => e
@logger.error("连接失败: #{e.message}")
raise
rescue Faraday::ClientError => e
@logger.warn("客户端错误 (4xx): #{e.response[:status]} #{e.message}")
raise
rescue Faraday::ServerError => e
@logger.error("服务端错误 (5xx): #{e.response[:status]} #{e.message}")
raise
rescue Faraday::Error => e
@logger.error("其他HTTP错误: #{e.class} - #{e.message}")
raise
end
end
在这个实现中，我们使用了Faraday官方的retry中间件来自动重试可恢复的错误，例如网络波动导致的连接失败或超时。通过exceptions参数指定哪些异常需要重试，避免了盲目重试幂等性无保证的请求。同时，handle_request方法中对各类Faraday错误进行了统一的日志记录，并重新抛出异常，让上层调用者可以决定后续行为（例如向用户展示错误信息或触发熔断）。
还有一个关键点是错误对象中携带的上下文信息。Faraday错误通常会包含response属性，其中包含了HTTP状态码、响应头和响应体。在handle_request中，我们通过e.response[:status]获取状态码，这样日志中可以输出更精确的信息。对于4xx错误，我们记录为警告级别，因为这类错误往往由客户端请求问题引起；5xx错误则记录为错误级别，需要引起运维注意。
统一错误处理的最佳实践还包括：不要在所有地方使用宽泛的rescue => e，这会掩盖编程错误；尽量使用Faraday标准错误类型，以便于中间件和上层逻辑识别；对于重试，要明确区分幂等请求与非幂等请求，避免重复提交；日志中应包含请求方法、URL和关键参数（但需脱敏），方便追踪。通过上述策略，HTTP客户端层的错误处理变得一致且可维护，大大降低了项目长期迭代的成本。