Faraday 内置中间件(Included Middleware)完全指南:用 Request/Response 中间件定制请求响应生命周期
Faraday 内置中间件(Included Middleware)完全指南:用 Request/Response 中间件定制请求响应生命周期
Faraday 内置了一套开箱即用的中间件,用于在请求发出前改写请求、在响应返回后解析与校验响应。本指南以 docs/middleware/included/index.md 为主线,完整梳理请求中间件与响应中间件两大分类下 7 个内置中间件的用法、配置参数与源码实现,帮助你在实际项目中按需组装中间件栈、自动完成认证、编码、日志、埋点与异常处理。
中间件机制概览:Rack 风格的请求/响应生命周期
Faraday 在底层使用一个受 Rack 启发的中间件栈(middleware stack)来处理请求。每个中间件都会接收并传递一个 Faraday::Env 对象:请求阶段由外层向内层逐层处理,直到最内层的 Adapter 真正执行 HTTP 请求;响应阶段则反过来由内向外逐层处理。最终 Faraday 把处理结果封装成 Faraday::Response 返回给调用方。
内置中间件按作用阶段分为两大宏观类别(见 docs/middleware/included/index.md):
- 请求中间件(Request Middleware):在 Adapter 执行之前修改请求细节,多数用于设置 Header 或根据 Content-Type 转换请求体,例如编码参数、注入认证头。
- 响应中间件(Response Middleware):在请求完成、收到响应后激活,例如解析响应体、记录日志、检查响应状态码。
中间件的注册顺序决定了处理顺序。与 Rack 一致,列表中第一个中间件包裹所有其他中间件,最后一个中间件处于最内层;因此 Adapter 必须始终位于中间件列表的末尾(详见 docs/middleware/index.md)。
中间件的添加有两种等价写法:按符号从 Faraday::Request、Faraday::Response、Faraday::Adapter 注册表中查找(request/response/adapter),或直接用类调用 use:
conn = Faraday.new do |f|
f.request :url_encoded
f.response :logger
f.adapter :net_http
end
# 等价写法:直接传入中间件类
conn = Faraday.new do |f|
f.use Faraday::Request::UrlEncoded
f.use Faraday::Response::Logger
f.use Faraday::Adapter::NetHttp
end
每个内置中间件源码末尾都会调用 register_middleware 完成符号注册,例如 lib/faraday/request/authorization.rb 中的 Faraday::Request.register_middleware(authorization: Faraday::Request::Authorization),因此你可以直接用 conn.request :authorization 引用它。
请求中间件:在 Adapter 执行前修改请求
Authorization:自动注入认证头
Faraday::Request::Authorization 中间件(源码见 lib/faraday/request/authorization.rb)会自动为请求添加 Authorization 头,并内置 Basic 认证的便捷支持:
Faraday.new(...) do |conn|
conn.request :authorization, 'Bearer', 'authentication-token'
end
配合 Proc 动态取值:认证令牌可以来自一个 proc,每次请求时都会重新求值;如果 proc 接收一个参数,它收到的就是被转发的 env(参见 Env 对象):
# 无参数 proc:每次请求时调用
Faraday.new(...) do |conn|
conn.request :authorization, 'Bearer', -> { MyAuthStorage.get_auth_token }
end
# 带 env 参数的 proc:可以基于请求环境动态生成令牌
Faraday.new(...) do |conn|
conn.request :authorization, 'Bearer', ->(env) { MyAuthStorage.get_auth_token(env) }
end
从源码看,proc 的调用规则由 arity 决定:当 value.is_a?(Proc) && value.arity == 1 时传入 env 调用,否则无参调用(lib/faraday/request/authorization.rb)。此外,on_request 方法首先会检查 env.request_headers<a href="https://link.gitcode.com/i/33c07afc4bb4fcbaddaef2328b2eb5b2" target="_blank">KEY],若请求头中已存在 Authorization 则不会覆盖([lib/faraday/request/authorization.rb)。
Basic 认证:传入 :basic 类型时,中间件会自动将用户名和密码 Base64 编码(源码通过 Utils.basic_header_from 实现):
Faraday.new(...) do |conn|
conn.request :authorization, :basic, 'username', 'password'
end
Faraday 1.x 兼容写法:1.x 时代 basic_auth、token_auth 是独立的方法,用法与本版本不同:
# Basic Auth 请求
# Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Faraday.new(...) do |conn|
conn.request :basic_auth, 'username', 'password'
end
# Token Auth 请求(options 自动转换为 key=value 格式)
# Authorization: Token authentication-token <options>
Faraday.new(...) do |conn|
conn.request :token_auth, 'authentication-token', **options
end
# 通用认证请求
# Authorization: Bearer authentication-token
Faraday.new(...) do |conn|
conn.request :authorization, 'Bearer', 'authentication-token'
end
详细说明见 docs/middleware/included/authentication.md。
UrlEncoded:将请求体编码为表单格式
UrlEncoded 中间件(源码见 lib/faraday/request/url_encoded.rb)把 Faraday::Request#body 中的键值对哈希转换为 url-encoded 请求体,并自动设置 Content-Type: application/x-www-form-urlencoded:
conn = Faraday.new(...) do |f|
f.request :url_encoded
...
end
conn.post('/', { a: 1, b: 2 })
# POST with
# Content-Type: application/x-www-form-urlencoded
# Body: a=1&b=2
复杂结构同样支持:数组与嵌套哈希会被递归序列化:
conn.post('/', { a: [1, 3], b: { c: 2, d: 4} })
# POST with
# Content-Type: application/x-www-form-urlencoded
# Body: a%5B%5D=1&a%5B%5D=3&b%5Bc%5D=2&b%5Bd%5D=4
从源码实现看(lib/faraday/request/url_encoded.rb),编码过程是将 body 包装为 Faraday::Utils::ParamsHash,再调用 to_query(env.params_encoder),因此参数序列化方式可以通过 Request Options 中的 params_encoder 定制。同时 process_request? 会检查:只有当请求已有 body、且 Content-Type 为空或为 application/x-www-form-urlencoded 时才处理;如果 body 已经是字符串或可读对象(to_str/read),则跳过编码(lib/faraday/request/url_encoded.rb)。
Json Request:将请求体编码为 JSON
JSON 请求中间件(源码见 lib/faraday/request/json.rb)把请求体哈希编码为 JSON 字符串,并自动设置 Content-Type: application/json。它只处理 Content-Type 匹配的请求或未设置类型的请求,且不会编码已经是字符串形式的 body:
conn = Faraday.new(...) do |f|
f.request :json
...
end
conn.post('/', { a: 1, b: 2 })
# POST with
# Content-Type: application/json
# Body: {"a":1,"b":2}
源码中类型匹配使用正则 MIME_TYPE_REGEX = %r{^application/(vnd\..+\+)?json$},即支持 application/json 以及 application/vnd...+json 等 vendor 类型(lib/faraday/request/json.rb)。当请求体是 true/false 布尔值时会照常编码,而 nil 与空字符串 body 不会被处理(lib/faraday/request/json.rb)。
自定义 JSON 编码器:默认使用 Ruby 标准库 json 的 JSON.generate。通过 encoder 选项可以指定其他编码器,既可以是实现了 dump 方法的模块/类,也可以是模块 + 方法名配对:
require 'oj'
# 方式一:提供实现了 dump 的对象
Faraday.new(...) do |f|
f.request :json, encoder: Oj
end
# 方式二:模块/类与类方法配对
Faraday.new(...) do |f|
f.request :json, encoder: [Oj, :dump]
end
Instrumentation:请求埋点
Instrumentation 中间件(源码见 lib/faraday/request/instrumentation.rb)允许使用不同的工具对请求进行埋点。核心选项只有两个:事件 name 与 instrumenter,默认值分别为 request.faraday 与 ActiveSupport::Notifications:
conn = Faraday.new(...) do |f|
f.request :instrumentation, name: 'custom_name', instrumenter: MyInstrumenter
...
end
默认用法:不传任何参数时,中间件使用 ActiveSupport::Notifications,你可以订阅默认事件名来统计每次请求:
conn = Faraday.new('http://example.com') do |f|
f.request :instrumentation
...
end
ActiveSupport::Notifications.subscribe('request.faraday') do |name, starts, ends, _, env|
url = env[:url]
http_method = env[:method].to_s.upcase
duration = ends - starts
$stdout.puts '[%s] %s %s (%.3f s)' % [url.host, http_method, url.request_uri, duration]
end
conn.get('/search', { a: 1, b: 2 })
#=> [example.com] GET /search?a=1&b=2 (0.529 s)
从源码看,中间件通过 @instrumenter.instrument(@name, env) { @app.call(env) } 包裹后续调用链,回调中可同时拿到事件开始/结束时间与完整的 env(lib/faraday/request/instrumentation.rb);源码注释也明确指出测量的是同步请求耗时。需要留意的是:默认 instrumenter 常量 ActiveSupport::Notifications 在运行时才被引用(lib/faraday/request/instrumentation.rb),因此使用默认行为时你的项目中需要提供 activesupport 依赖。
响应中间件:解析与收尾
Json Response:解析响应体
JSON 响应中间件(源码见 lib/faraday/response/json.rb)把响应体解析为 Ruby 哈希。行为可通过三个选项定制:
| 选项 | 默认值 | 说明 |
|---|---|---|
| parser_options | {} |
传递给 JSON.parse 的选项(也可用于指定自定义 decoder) |
| content_type | /\bjson$/ |
需要处理的响应 Content-Type,可为单个字符串或数组,元素可为字符串或正则 |
| preserve_raw | false |
为 true 时,原始未解析的响应体保存在 response.env[:raw_body] |
示例:
conn = Faraday.new('http://httpbingo.org') do |f|
f.response :json, **options
end
conn.get('json').body
# => {"slideshow"=>{"author"=>"Yours Truly", "date"=>"date of publication", "slides"=>[...], "title"=>"Sample Slide Show"}}
自定义 JSON 解码器:默认使用 Ruby json 的 JSON.parse。通过 parser_options 中的 decoder 选项可指定其他解码器(实现 load 的模块/类,或模块 + 类方法配对):
require 'oj'
Faraday.new(...) do |f|
f.response :json, parser_options: { decoder: Oj }
end
Faraday.new(...) do |f|
f.response :json, parser_options: { decoder: [Oj, :load] }
end
从源码看,decoder 归一化逻辑为:<a href="https://link.gitcode.com/i/47008f5bd137e90a11fcc859c8f63e47" target="_blank">Module, :method] 配对优先,其次是实现了 load 的对象,否则回退到 [::JSON, :parse]([lib/faraday/response/json.rb)。解析失败时中间件会抛出 Faraday::ParsingError 并携带原始响应(lib/faraday/response/json.rb);空白的响应体会直接返回 nil 而不解析(lib/faraday/response/json.rb)。
Logger:请求/响应日志
Logger 中间件会同时记录请求与响应的 body 和 headers,且高度可定制,支持在必要时脱敏机密信息。默认输出到 $stdout:
conn = Faraday.new(url: 'http://httpbingo.org') do |faraday|
faraday.response :logger # 记录请求和响应到 $stdout
end
conn.get
# => INFO -- request: GET http://httpbingo.org/
# => DEBUG -- request: User-Agent: "Faraday v1.0.0"
# => INFO -- response: Status 301
# => DEBUG -- response: date: "Sun, 19 May 2019 16:05:40 GMT"
定制 logger 实例:默认使用 Ruby 的 Logger.new($stdout),可以传入任意 logger 对象:
conn = Faraday.new(url: 'http://httpbingo.org') do |faraday|
faraday.response :logger, MyLogger.new($stdout)
end
包含/排除 headers 与 bodies:出于安全考虑默认只记录 headers,但可以通过配置哈希开启 bodies 与 errors 的记录,或关闭 headers:
conn = Faraday.new(url: 'http://httpbingo.org') do |faraday|
faraday.response :logger, nil, { headers: true, bodies: true, errors: true }
end
# 更细粒度:不记录请求体,但记录响应体
conn = Faraday.new(url: 'http://httpbingo.org') do |faraday|
faraday.response :logger, nil, { bodies: { request: false, response: true } }
end
注意:
bodies: { request: ..., response: ... }这种细粒度配置只在使用默认 formatter 时生效。
过滤敏感信息:通过正则匹配器可以从日志中抹掉密钥等敏感内容:
conn = Faraday.new(url: 'http://httpbingo.org') do |faraday|
faraday.response :logger do | logger |
logger.filter(/(api_key=)([^&]+)/, '\1[REMOVED]')
end
end
conn.get('/', api_key: 'secret')
# => INFO -- request: GET http://httpbingo.org/?api_key=[REMOVED]
# => DEBUG -- request: User-Agent: "Faraday v1.0.0"
# => INFO -- response: Status 301
# => DEBUG -- response: date: "Sun, 19 May 2019 16:12:36 GMT"
调整日志级别:默认在 info 级别记录,可通过 log_level 选项修改:
conn = Faraday.new(url: 'http://httpbingo.org') do |faraday|
faraday.response :logger, nil, { bodies: true, log_level: :debug }
end
自定义 formatter:可传入自定义 formatter 控制请求、响应与错误的记录格式。任何自定义 formatter 必须实现 request 与 response 方法(参数为 Faraday 环境对象),可以实现 exception 方法(参数为 StandardError)。若继承自 Faraday::Logging::Formatter(实现位于 lib/faraday/logging/formatter.rb),则 debug、info、warn、error、fatal 方法会自动委托给底层 logger:
class MyFormatter < Faraday::Logging::Formatter
def request(env)
# 基于 env 构建自定义消息
info('Request') { 'Sending Request' }
end
def response(env)
# 基于 env 构建自定义消息
info('Response') { 'Response Received' }
end
def exception(exc)
# 基于 exc 构建自定义消息
info('Error') { 'Error Raised' }
end
end
conn = Faraday.new(url: 'http://httpbingo.org/api_key=s3cr3t') do |faraday|
faraday.response :logger, nil, formatter: MyFormatter
end
RaiseError:4xx/5xx 自动抛错
RaiseError 中间件(源码见 lib/faraday/response/raise_error.rb)在响应状态码为 4xx 或 5xx 时抛出 Faraday::Error 异常,免去手动检查状态码的麻烦。这些异常建立在 Faraday 默认错误体系之上(参见 Faraday 错误处理,基础错误包括 Faraday::Error、Faraday::ConnectionFailed、Faraday::TimeoutError、Faraday::SSLError 等)。所有抛出的异常都会用一个包含响应 status、headers、body 的哈希初始化:
conn = Faraday.new(url: 'http://httpbingo.org') do |faraday|
faraday.response :raise_error # 状态码 4xx/5xx 时抛出 Faraday::Error
end
begin
conn.get('/wrong-url') # => 假设返回 404
rescue Faraday::ResourceNotFound => e
e.response_status #=> 404
e.response_headers #=> { ... }
e.response_body #=> "..."
end
具体的异常类由 HTTP 状态码决定,如下表所示:
4xx 错误(400-499 表示客户端错误,抛出的异常类继承自 Faraday::ClientError):
| 状态码 | 异常类 |
|---|---|
| 400 | Faraday::BadRequestError |
| 401 | Faraday::UnauthorizedError |
| 403 | Faraday::ForbiddenError |
| 404 | Faraday::ResourceNotFound |
| 407 | Faraday::ProxyAuthError |
| 408 | Faraday::RequestTimeoutError |
| 409 | Faraday::ConflictError |
| 422 | Faraday::UnprocessableContentError |
| 429 | Faraday::TooManyRequestsError |
| 其他 4xx | Faraday::ClientError |
5xx 错误(500-599 表示服务器错误,抛出 Faraday::ServerError):需要注意,该异常仅在真正收到响应且状态码位于 500-599 时抛出;超时、连接失败等通常与 5xx 相关的其他错误会以继承自 Faraday::Error 的独立异常抛出(见 docs/getting-started/errors.md)。
缺失 HTTP 状态:当服务器返回畸形响应或底层 HTTP 库存在 bug 导致状态码为 nil 时,视为服务器错误,抛出继承自 Faraday::ServerError 的 Faraday::NilStatusError(对应源码中的 when nil 分支,lib/faraday/response/raise_error.rb)。
中间件选项:
| 选项 | 默认值 | 说明 |
|---|---|---|
| include_request | true |
为 true 时,异常携带请求信息(method、url、url_path、params、headers、body) |
| allowed_statuses | [] |
不应抛错的状态码数组 |
综合示例:将 404 加入白名单后,404 响应不再抛错,而 401 仍会抛出 Faraday::UnauthorizedError,且异常中可以通过 response[:request][:url_path] 等键读取请求上下文:
conn = Faraday.new(url: 'http://httpbingo.org') do |faraday|
faraday.response :raise_error, include_request: true, allowed_statuses: [404]
end
begin
conn.get('/wrong-url') # => 假设返回 404,不抛错
conn.get('/protected-url') # => 假设返回 401,抛出异常
rescue Faraday::UnauthorizedError => e
e.response[:status] # => 401
e.response[:headers] # => { ... }
e.response[:body] # => "..."
e.response[:request][:url_path] # => "/protected-url"
end
从源码看,response_values 默认会把 status、headers、body 与 request(含 method/url/url_path/params/headers/body)组装进异常消息;只有显式设置 include_request: false 时才省略 request 信息(lib/faraday/response/raise_error.rb)。
组合实战:一条连接上的中间件栈
内置中间件的价值在于按需组合。一个更贴近真实项目的配置示例(取自 docs/middleware/index.md):
Faraday.new(...) do |conn|
# POST/PUT 参数编码
conn.request :url_encoded
# 请求/响应日志
conn.response :logger
# 最后一个中间件必须是 Adapter
conn.adapter :net_http
end
这个请求中间件配置对 POST/PUT 请求的影响如下:
Request::UrlEncoded在 body 尚未编码或 Content-Type 不是其他类型时,将其编码为application/x-www-form-urlencoded。Response::Logger记录请求与响应 headers,也可配置为记录 bodies。
换中间件意味着换优先级——显式指定请求的 Content-Type,就等于明确声明应该由哪个中间件来处理它。例如在 :url_encoded 之前先设置 Content-Type: application/json,UrlEncoded 就会跳过该请求,让给后续的 JSON 中间件处理。
全局默认选项(DEFAULT_OPTIONS):除了在实例上逐条传参,中间件还支持通过类级 DEFAULT_OPTIONS 在应用层统一修改默认值。以 RaiseError 为例,其类顶部定义了 DEFAULT_OPTIONS = { include_request: true, allowed_statuses: <a href="https://link.gitcode.com/i/156880aab3107b643fa311f5d35e5bf9" target="_blank">] }([lib/faraday/response/raise_error.rb),实例化时会被引用。若希望应用内所有实例都改变默认行为,可以在 config/initializers 中配置:
# config/initializers/faraday_config.rb
Faraday::Response::RaiseError.default_options = { include_request: false }
应用初始化后,所有该中间件实例都会采用新配置;实例级传入的选项(如 f.response :raise_error, include_request: true)仍然可以按需覆盖。
小结
Faraday 内置的 7 个中间件覆盖了 HTTP 客户端最常见的需求:Authorization 负责认证、UrlEncoded 与 Json Request 负责请求体编码、Instrumentation 负责埋点、Json Response 负责响应解析、Logger 负责日志与脱敏、RaiseError 负责异常化处理。理解请求/响应中间件的分工、注册顺序(Adapter 永远在最后)以及各自的配置选项,你就可以像拼装管道一样按需构建出清晰、可维护的 HTTP 客户端。各中间件的详细说明与源码实现位于:
- docs/middleware/included/authentication.md + lib/faraday/request/authorization.rb
- docs/middleware/included/url-encoding.md + lib/faraday/request/url_encoded.rb
- docs/middleware/included/json.md + lib/faraday/request/json.rb、lib/faraday/response/json.rb
- docs/middleware/included/instrumentation.md + lib/faraday/request/instrumentation.rb
- docs/middleware/included/logging.md + lib/faraday/response/logger.rb、lib/faraday/logging/formatter.rb
- docs/middleware/included/raising-errors.md + lib/faraday/response/raise_error.rb
如果内置中间件不满足需求,还可以参照 docs/middleware/index.md 与 docs/middleware/custom-middleware.md 编写自定义中间件,接入同一套请求/响应生命周期。
