Faraday 自定义适配器并行请求支持:从 `supports_parallel` 到 `ParallelManagerexecute` 的完整实现指南
Faraday 自定义适配器并行请求支持:从 supports_parallel 到 ParallelManager#execute 的完整实现指南
本指南围绕 Faraday 官方文档《Adding support for parallel requests》展开,讲解如何为自定义适配器(Custom Adapter)接入并行请求能力。读者将掌握三条核心链路:用
self.supports_parallel = true声明后端并行能力、用类方法setup_parallel_manager返回并行管理器,以及在新旧两代ParallelManager接口(execute与run)之间做出正确选择。全文结合本仓库 lib/faraday/adapter.rb 与 lib/faraday/connection.rb 的源码实现逐一印证。
从使用者的角度看:并行请求长什么样
在深入了解适配器内部的并行支持之前,先明确用户视角下的并行请求体验。Faraday 的 Connection 暴露了 in_parallel 方法,配合一个块即可把块内的多个请求打包成一批并发执行:
response_1 = nil
response_2 = nil
conn.in_parallel do
response_1 = conn.get('/about')
response_2 = conn.get('/products')
end
puts response_1.status
puts response_2.status
这段示例摘取自仓库的共享测试套件 spec/support/shared_examples/request_method.rb。细心的读者会发现两个细节:
- 变量
response_1、response_2在块外预先声明为nil,因为并行批次尚未真正执行时,请求的响应体还是空的; conn.get('/about')返回的是Faraday::Response对象,在块结束、并行批次真正跑完之后,response_1.status与response_1.body才填充完毕。
这正是"收集请求、统一执行、批量回填"的并行模型。如果你是从使用者角度想深入了解 in_parallel 的完整语义,可以参考仓库中的进阶文档 docs/advanced/parallel-requests.md;而本指南要解决的是另一侧的问题:如何让一个自定义适配器具备支撑这种并行模型的能力。
第一步:用 supports_parallel 声明后端并行能力
Faraday 并不知道你的底层 HTTP 后端(例如假想的 FlorpHttp 客户端)是否支持并发。因此适配器作者需要显式声明这一点。在类定义中设置类级标志即可:
class FlorpHttp < ::Faraday::Adapter
dependency do
require 'florp_http'
end
self.supports_parallel = true
end
这个标志在源码中对应 lib/faraday/adapter.rb 的 Parallelism 模块:
module Parallelism
attr_writer :supports_parallel
def supports_parallel?
@supports_parallel
end
def inherited(subclass)
super
subclass.supports_parallel = supports_parallel?
end
end
extend Parallelism
self.supports_parallel = false
值得注意的源码事实有三点:
- 默认值是
false:Faraday::Adapter基类把supports_parallel初始化为false,所以不声明并行能力的适配器,in_parallel会被降级为串行执行; - 标志会随继承链传递:
inherited钩子会把父类的并行标志复制给子类。也就是说,如果你的适配器继承了某个已声明supports_parallel = true的适配器,子类默认同样支持并行,除非显式覆盖; - 判定方式是鸭子类型:在 lib/faraday/connection.rb 中,连接层通过
support_parallel?判断:
def support_parallel?(adapter)
adapter.respond_to?(:supports_parallel?) && adapter&.supports_parallel?
end
只要适配器类响应 supports_parallel? 且返回真值,就认为具备并行能力。
第二步:实现 setup_parallel_manager 类方法
声明能力之后,还需要让 Faraday 能拿到一个"并行管理器"对象。这个职责由类方法 setup_parallel_manager 承担,它由连接层在 lib/faraday/connection.rb 的 default_parallel_manager 中调用:
def default_parallel_manager
@default_parallel_manager ||= begin
adapter = @builder.adapter.klass if @builder.adapter
if support_parallel?(adapter)
adapter.setup_parallel_manager
elsif block_given?
yield
end
end
end
从源码可以看到两个关键点:
setup_parallel_manager是在适配器类上调用(adapter.setup_parallel_manager),而非实例;- 当适配器不具备并行能力时,
default_parallel_manager返回nil,此时in_parallel会打印警告Warning: 'in_parallel' called but no parallel-capable adapter on Faraday stack(见 lib/faraday/connection.rb),并退化为普通串行执行。
在自定义适配器中实现它:
class FlorpHttp < ::Faraday::Adapter
dependency do
require 'florp_http'
end
self.supports_parallel = true
def self.setup_parallel_manager(_options = nil)
FlorpParallelManager.new # NB: we will need to define this
end
def call(env)
# NB: you can call `in_parallel?` here to check if the current request
# is part of a parallel batch. Useful if you need to collect all requests
# into the ParallelManager before running them.
end
end
注意 setup_parallel_manager 接受一个可选的 _options 参数,签名是 (_options = nil)。如果未来需要根据连接配置构建不同行为的管理器,可以在该参数中传递定制选项。
在 #call 中检测并行上下文:in_parallel?
上面代码中 #call 内的注释揭示了并行适配器的一个关键技巧:在请求方法内部用 in_parallel? 判断当前请求是否处于并行批次中。
in_parallel? 有两层来源,需要区分:
- 适配器实例层面:
#call(env)收到的env是Faraday::Env,它本身带有parallel?方法(见 lib/faraday/options/env.rb)。env.parallel?反映"这个请求是否在并行上下文中"; - 连接层面:
conn.in_parallel?(见 lib/faraday/connection.rb)返回!!@parallel_manager,反映连接当前是否挂着并行管理器。
对适配器作者而言,更常用的是 env.parallel?。典型场景是:如果后端需要把所有请求先收集进一个批次再统一执行(例如基于 EventMachine 或线程池的库),你可以在 #call 中判断 env.parallel?,为真时把请求压入 ParallelManager 的队列,为假时直接同步执行。
save_response 与并行执行的协作
为什么在并行批次内响应体是空的?答案藏在 save_response 的实现中,见 lib/faraday/adapter.rb:
def save_response(env, status, body, headers = nil, reason_phrase = nil, finished: true)
env.status = status
env.body = body
env.reason_phrase = reason_phrase&.to_s&.strip
env.response_headers = Utils::Headers.new.tap do |response_headers|
response_headers.update headers unless headers.nil?
yield(response_headers) if block_given?
end
env.response.finish(env) unless env.parallel? || !finished
env.response
end
核心逻辑:env.response.finish(env) 负责触发响应完成(#on_complete 回调、填充 body 等),但当 env.parallel? 为真时会被跳过。也就是说,并行批次内的请求只把状态码、响应头等元数据保存进 env,真正的"完成"动作推迟到批次统一执行之后。这也解释了为什么测试套件断言并行块内 @resp1.body 为 nil、块结束后才等于真实响应体(见 spec/support/shared_examples/request_method.rb)。
第三步:实现 ParallelManager#execute
现在到了并行支持的"心脏"——ParallelManager 类。原文档明确指出:execute 方法会被传入与 in_parallel 完全相同的块,因此你可以根据后端的工作方式,选择"收集请求后统一执行"或"把请求包进包装器"两种策略:
class FlorpParallelManager
# The execute method will be passed the same block as `in_parallel`,
# so you can either collect the requests or just wrap them into a wrapper,
# depending on how your adapter works.
def execute(&block)
run_async(&block)
end
end
连接层是如何调度 execute 的?看 lib/faraday/connection.rb 的 in_parallel 实现:
def in_parallel(manager = nil, &block)
@parallel_manager = manager || default_parallel_manager do
warn 'Warning: `in_parallel` called but no parallel-capable adapter ' \
'on Faraday stack'
warn caller[2, 10].join("\n")
nil
end
return yield unless @parallel_manager
if @parallel_manager.respond_to?(:execute)
# Execute is the new method that is responsible for executing the block.
@parallel_manager.execute(&block)
else
# TODO: Old behaviour, deprecate and remove in 3.0
yield
@parallel_manager.run
end
ensure
@parallel_manager = nil
end
这段代码是理解新旧接口差异的最佳证据,它揭示了三件事:
execute是新接口的优先选择:只要管理器响应execute,连接层就把in_parallel的块原样交给它执行;manager参数可覆盖默认管理器:in_parallel(manager)允许使用方传入自定义管理器,绕过default_parallel_manager;ensure块保证状态复位:无论执行成功还是抛异常,@parallel_manager都会被清空,避免污染后续请求。
一个容易忽略的坑:return yield unless @parallel_manager。当适配器不支持并行(管理器为 nil)时,块被直接以串行方式 yield,conn.in_parallel 之后的响应立即可用,但没有任何并发收益——这正是"静默降级"行为。适配器作者应当通过正确实现 supports_parallel? 来避免使用者踩到这个坑。
典型实现策略:收集与分发
execute 拿到块之后,常见做法是分两阶段执行:
class FlorpParallelManager
def execute(&block)
# 阶段一:在连接线程中执行块,让每个请求进入 #call,
# 并通过 env.parallel? 判断将其注册到本管理器。
instance_eval(&block)
# 阶段二:统一向底层后端分发所有收集到的请求(并发执行)。
dispatch_all_requests
end
end
这个模式与文档所述"收集所有请求到 ParallelManager 后再运行"完全吻合:#call 中检测到 env.parallel? 时把请求挂起(save_response 会因 env.parallel? 跳过 finish),块执行完后由 execute 的后续逻辑统一触发真实请求并回填响应。
关于旧接口 run:一个正在退场的兼容层
原文档特别用一节篇幅说明旧接口的演进,这是并行支持设计中最容易混淆的部分,值得完整展开:
- 旧模型(
run):在execute引入之前,ParallelManager需要实现一个run方法,而 Faraday 连接会在调用run之前先执行传入的块。也就是说,"块的执行"与"并行分发"是分离的,管理器被迫在两次调用之间保存内部状态; - 新模型(
execute):execute直接接收同一个块并全权负责执行,收集请求与统一分发都可以在execute内部完成,不再需要跨调用保存状态,也让不同的后端流程(同步收集、异步投递、批处理)有了更大的实现自由度; - 兼容策略:自 Faraday 2.0 起,
run依然可用——只要管理器没有实现execute,连接层就会走yield+@parallel_manager.run的旧路径。但源码注释TODO: Old behaviour, deprecate and remove in 3.0(lib/faraday/connection.rb)明确指出该路径计划在 3.0 移除,因此新写的适配器应一律实现execute,而不是run。
原文档提到的 faraday-em_synchrony 适配器及其 ParallelManager 实现即 run 旧接口的参考案例。对自定义适配器作者来说,可以借鉴其思路,但请务必以 execute 为当前目标接口。
完整示例与测试验证
将三块拼起来,一个支持并行请求的完整自定义适配器如下:
require 'faraday'
class FlorpHttp < ::Faraday::Adapter
dependency do
require 'florp_http'
end
self.supports_parallel = true
def self.setup_parallel_manager(_options = nil)
FlorpParallelManager.new
end
def call(env)
super
if env.parallel?
# 并行批次内:登记请求,等待批次统一执行
::Faraday.parallel_manager.register(self, env)
else
# 串行路径:直接执行并保存响应
response = FlorpHttp.perform_request(env)
save_response(env, response.status, response.body, response.headers)
end
end
end
class FlorpParallelManager
def execute(&block)
instance_eval(&block)
run_all_registered_requests # 并发分发所有登记请求
end
end
# 注册适配器昵称,便于用户通过 f.adapter :florp_http 使用
Faraday::Adapter.register_middleware(florp_http: FlorpHttp)
关于适配器的完整编写规范(save_response、request_timeout、连接配置、close 方法等),请参阅 docs/adapters/custom/index.md;register_middleware 的用法细节也可在该文档中找到。
仓库的测试套件为并行行为提供了可复现的验证基准。在 spec/support/shared_examples/request_method.rb 的 on_feature :parallel 共享用例中,测试断言了并行语义的关键不变量:
- 并行块内:
conn.in_parallel?为真,@resp1.body与@resp2.body均为nil(响应未完成); - 并行块外:
conn.in_parallel?为假; - 批次完成后:两个响应的
status均为 200,body与各自 payload 的 JSON 序列化结果一致。
这套共享用例以 on_feature :parallel 门控,意味着适配器只需声明该 feature 即可复用全部并行断言,是验证自定义适配器并行实现的捷径。
小结
为 Faraday 自定义适配器接入并行请求支持,本质上是三件事:声明(self.supports_parallel = true)、构造(setup_parallel_manager 返回管理器)、执行(ParallelManager#execute 接收并调度 in_parallel 的块)。在此基础上,env.parallel? 与 save_response 的联动决定了"收集—统一执行—批量回填"的并行时序,而 execute/run 的新旧接口选择则决定了实现的健壮性与未来兼容性。牢记源码中的两个锚点:lib/faraday/adapter.rb 的 Parallelism 模块与 lib/faraday/connection.rb 的 in_parallel 调度逻辑,你就能写出与 Faraday 核心架构完全对齐的并行适配器。