Faraday 自定义适配器并行请求支持:从 `supports_parallel` 到 `ParallelManagerexecute` 的完整实现指南

原创2026-10-05 10:54:491,367 阅读
文章标签:后端网络通信

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。细心的读者会发现两个细节:

  1. 变量 response_1、response_2 在块外预先声明为 nil,因为并行批次尚未真正执行时,请求的响应体还是空的;
  2. 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? 有两层来源,需要区分:

  1. 适配器实例层面:#call(env) 收到的 env 是 Faraday::Env,它本身带有 parallel? 方法(见 lib/faraday/options/env.rb)。env.parallel? 反映"这个请求是否在并行上下文中";
  2. 连接层面: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 核心架构完全对齐的并行适配器。

登录后查看全文
faraday