Faraday 的 UrlEncoded 中间件:请求体 URL 编码的完整实战指南

原创2026-10-05 11:20:531,638 阅读
文章标签:后端网络通信

Faraday 的 UrlEncoded 中间件:请求体 URL 编码的完整实战指南

本篇指南围绕 Faraday 内置的 UrlEncoded 请求中间件展开:它负责把 Faraday::Request#body 中的 key/value 哈希序列化为 application/x-www-form-urlencoded 格式的请求体,并自动设置对应的 Content-Type 请求头。读完本文,你将掌握该中间件的注册方式、简单与嵌套结构的编码结果、两种内置参数编码器(NestedParamsEncoder 与 FlatParamsEncoder)的切换方法,以及其底层实现原理与边界行为,从而在任何需要以表单方式提交数据的场景中准确控制 Faraday 的请求体。

一、UrlEncoded 中间件的作用

UrlEncoded 是 Faraday 内置的请求中间件(Request Middleware),位于 lib/faraday/request/url_encoded.rb。它的职责可以概括为两点:

  1. 转换请求体:将 Faraday::Request#body 中的 key/value 哈希转换为 url-encoded 字符串;
  2. 自动设置请求头:把 Content-Type 设置为 application/x-www-form-urlencoded。

在 docs/middleware/included/index.md 的中间件分类中,它被归入"在适配器执行之前修改请求细节"的请求中间件类别,与 Authorization、Json Request、Instrumentation 并列。请求中间件的典型行为正是"基于内容类型设置 Header 或转换请求体"——UrlEncoded 正是这一模式的代表实现。

从源码看,该中间件的核心编码逻辑集中在 call 方法中(lib/faraday/request/url_encoded.rb):

def call(env)
  match_content_type(env) do |data|
    params = Faraday::Utils::ParamsHash[data]
    env.body = params.to_query(env.params_encoder)
  end
  @app.call env
end

这里有两个关键细节:

  • Faraday::Utils::ParamsHash<a href="https://link.gitcode.com/i/5176832d3f985a6205e4ec7fc1d4840d" target="_blank">data] 会把传入哈希包装为"键统一字符串化"的 ParamsHash(见 [lib/faraday/utils/params_hash.rb),因此无论是 a: 1 还是 'a' => 1 都能被正确处理;
  • params.to_query(env.params_encoder) 使用请求的 params_encoder 完成最终序列化——这正是本文后面"自定义编码器"一节的入口。

二、基本用法:注册与发送表单请求

在构造 Faraday::Connection 时,通过 request :url_encoded 注册该中间件即可。由于它注册在 Faraday::Request 命名空间(源码末尾的 Faraday::Request.register_middleware(url_encoded: Faraday::Request::UrlEncoded)),所以可以用符号方式添加,等价于直接 use Faraday::Request::UrlEncoded。

基本示例(取自 docs/middleware/included/url-encoding.md):

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

对照源码,这个输出结果的产生路径是:match_content_type 检测到请求带 body 且 Content-Type 为空或已是表单类型,于是先补上 Content-Type: application/x-www-form-urlencoded(第 33 行),随后 ParamsHash 的 to_query 将 { a: 1, b: 2 } 编码为 a=1&b=2。

与中间件栈的关系

根据 docs/middleware/index.md 的说明,Faraday 采用 Rack 风格的中间件栈:第一个注册的中间件包裹其余所有中间件,适配器必须放在最后。因此一个典型的完整配置是:

Faraday.new(...) do |conn|
  # POST/PUT 参数编码器
  conn.request :url_encoded

  # 请求/响应日志
  conn.response :logger

  # 最后一个必须是适配器
  conn.adapter :net_http
end

UrlEncoded 处理的是 POST/PUT 请求体,所以在实际项目中它通常与其他请求中间件(如 :authorization)及响应中间件(如 :json、:logger)组合使用。中间件栈的顺序会影响处理顺序,这一点在需要多个中间件协作时非常重要。

三、嵌套与复杂结构的序列化

UrlEncoded 中间件的默认编码器是 NestedParamsEncoder,它"尊重参数的原始结构",因此数组、哈希等复杂对象都能被序列化。这也是该中间件相比手写 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

解码后对应:

  • a%5B%5D=1&a%5B%5D=3 → a[]=1&a[]=3,即数组元素重复键名;
  • b%5Bc%5D=2&b%5Bd%5D=4 → b[c]=2&b[d]=4,即哈希嵌套展开。

编码规则的源码级解释

NestedParamsEncoder 的实现位于 lib/faraday/encoders/nested_params_encoder.rb,其 encode_pair 方法(第 40-51 行)定义了三条核心规则:

  1. 哈希值:递归调用 encode_hash,生成 parent%5Bkey%5D=value 形式(第 53-62 行),且嵌套哈希的键会先被转义再排序;
  2. 数组值:递归调用 encode_array,默认(array_indices = false)生成 parent%5B%5D=value 形式(第 64-77 行);若设置 @array_indices = true 则生成 parent%5B0%5D=...、parent%5B1%5D=... 带索引形式;
  3. 标量/ nil:标量直接 key=escaped_value,nil 值只输出键名本身(第 45-49 行)。

更复杂的嵌套同样支持。测试用例 spec/faraday/request/url_encoded_spec.rb 验证了三层结构:

conn.post('/echo', 'a' => { 'b' => { 'c' => ['d'] } })
# body == 'a%5Bb%5D%5Bc%5D%5B%5D=d'

排序与键名转义

NestedParamsEncoder 类级变量(第 177-188 行)还提供了两个值得注意的默认行为:

  • @sort_params = true:参数默认按键排序,这对 OAuth 签名、缓存键一致性等场景很有用;
  • @array_indices = false:数组不带索引编码;
  • @param_depth_limit = 100:解码时嵌套深度上限,超过会抛出 Faraday::Error。

四、自定义序列化方式:params_encoder 与 FlatParamsEncoder

UrlEncoded 的序列化方式可以通过 Request Options 中的 :params_encoder 选项定制。这在 docs/customization/request-options.md 中有完整说明:该选项类型为 Class,默认值是 Faraday::Utils.nested_params_encoder(即 NestedParamsEncoder),它既可以在连接构造时全局设置,也可以在每个请求上单独覆盖。

全局设置(连接级别)

request_options = {
  params_encoder: Faraday::FlatParamsEncoder,
  timeout: 5
}

conn = Faraday.new(request: request_options) do |faraday|
  # ...
end

按请求覆盖

conn.get('/foo') do |req|
  req.options.timeout = 10
  req.options.params_encoder = Faraday::FlatParamsEncoder
end

params_encoder 选项在 lib/faraday/options/request_options.rb 中作为 RequestOptions 的可配置属性之一被定义。

FlatParamsEncoder 的行为差异

FlatParamsEncoder(见 lib/faraday/encoders/flat_params_encoder.rb)把参数当作扁平哈希处理:数组值会重复键名多次,而不是生成带 [] 后缀的嵌套形式。源码中的文档示例:

encode({a: %w[one two three], b: true, c: "C"})
# => 'a=one&a=two&a=three&b=true&c=C'

测试 spec/faraday/request/url_encoded_spec.rb 验证了两种编码器在同一中间件下的差异:

# 默认 NestedParamsEncoder:body == 'dimensions%5B%5D=date&dimensions%5B%5D=location'
# FlatParamsEncoder(按请求覆盖):
conn.post('/echo', dimensions: %w[date location]) do |req|
  req.options.params_encoder = Faraday::FlatParamsEncoder
end
# body == 'dimensions=date&dimensions=location'

选择依据:如果服务端期望 a=one&a=two 这种重复键形式,用 FlatParamsEncoder;如果期望 PHP/Rails 风格的 a<a href="https://link.gitcode.com/i/d424f2851635e8af7dfe9b4305d4d138" target="_blank">]=one 嵌套形式,用默认的 NestedParamsEncoder。此外,[lib/faraday/utils.rb 还提供了 build_query(扁平)与 build_nested_query(嵌套)两个工具方法,供不经过中间件直接序列化参数时使用。

五、源码实现原理:何时编码、何时跳过

理解 UrlEncoded 的三个关键判断,有助于避免踩坑。中间件的 match_content_type(lib/faraday/request/url_encoded.rb)与 process_request?(第 43-46 行)共同决定了编码的触发条件:

1. 有 body 且 Content-Type 允许,才编码

process_request? 的判定逻辑是:

def process_request?(env)
  type = request_type(env)
  env.body && (type.empty? || (type == self.class.mime_type))
end

即:请求必须携带 body,且 Content-Type 要么为空、要么恰好是 application/x-www-form-urlencoded。request_type 会把 Content-Type 按 ; 切分取主类型(第 51-55 行),因此 application/x-www-form-urlencoded; charset=UTF-8 这类带参数的写法也能被识别。

2. 自定义 Content-Type 会被尊重(跳过编码)

如果请求已显式设置了其他 Content-Type,中间件不会强行覆盖。测试用例验证了这一行为(spec/faraday/request/url_encoded_spec.rb):

conn.post('/echo', { some: 'data' }, 'content-type' => 'application/x-foo')
# Content-Type 保持 'application/x-foo',body 不做编码转换

这正是 docs/middleware/index.md 中提到的"显式指定 Content-Type 即表明应由哪个中间件处理"的设计。

3. 字符串与 IO 体不转换

match_content_type 中有一条重要保护(第 34 行):

return if env.body.respond_to?(:to_str) || env.body.respond_to?(:read)

如果 body 已经是字符串(to_str)或 IO 流(read,如 StringIO),中间件只会设置 Content-Type 而不会再编码。测试中的文件场景(第 76-79 行)传入 StringIO.new('str=apple'),请求体原样透传。这意味着你完全可以把"已经编码好的字符串"或"文件流"直接作为 body 提交。

4. 无 body 时完全无操作

测试用例第一项(第 22-26 行)验证:不带 payload 的 POST 不会设置 Content-Type,body 为空。

六、Unicode、空格与特殊字符的转义规则

URL 编码离不开字符转义。Faraday::Utils.escape(lib/faraday/utils.rb)实现如下:

ESCAPE_RE = /[^a-zA-Z0-9 .~_-]/

def escape(str)
  str.to_s.gsub(ESCAPE_RE) do |match|
    "%#{match.unpack('H2' * match.bytesize).join('%').upcase}"
  end.gsub(' ', default_space_encoding)
end

要点:

  • 只有不在 a-zA-Z0-9 .~_- 范围内的字符才会被 %XX 百分号编码;
  • 空格默认编码为 +(default_space_encoding 默认值 '+',第 20-22 行);
  • 可通过 Faraday::Utils.default_space_encoding = '%20' 全局改空格编码为 %20。

测试验证(spec/faraday/request/url_encoded_spec.rb):

conn.post('/echo', str: 'eé cç aã aâ')
# body == 'str=e%C3%A9+c%C3%A7+a%C3%A3+a%C3%A2'

Unicode 字符被 UTF-8 百分号编码,空格变成 +。而自定义空格编码的用例(第 81-92 行)则证明:

Faraday::Utils.default_space_encoding = '%20'
conn.post('/echo', str: 'apple banana')
# body == 'str=apple%20banana'

对于带 &、= 等保留字符的值,escape 同样会将其编码,避免破坏键值对分隔符语义。解码侧则由 Utils.unescape(基于 CGI.unescape)配合 NestedParamsEncoder::DecodeMethods 的 decode 完成,其中会把 + 还原为空格(第 96 行)。

七、回归验证:借助测试理解完整行为矩阵

spec/faraday/request/url_encoded_spec.rb 是理解该中间件行为的最快途径,它覆盖了以下完整场景矩阵:

场景 输入 结果
无 body conn.post('/echo') 不设置 Content-Type,body 为空
自定义 Content-Type body + content-type: application/x-foo 保持原类型,body 不编码
无额外 header { fruit: %w[apples oranges] } application/x-www-form-urlencoded + fruit%5B%5D=apples&fruit%5B%5D=oranges
显式表单 Content-Type { 'a' => 123 } 保持类型 + a=123
嵌套哈希 user: { name: 'Mislav', web: 'mislav.net' } 解码后还原为嵌套哈希
Flat 编码器 dimensions: %w[date location] dimensions=date&dimensions=location
Unicode str: 'eé cç aã aâ' str=e%C3%A9+c%C3%A7+a%C3%A3+a%C3%A2
深层嵌套 'a' => { 'b' => { 'c' => ['d'] } } a%5Bb%5D%5Bc%5D%5B%5D=d
文件/IO StringIO.new('str=apple') 原样透传

其中"嵌套哈希"用例(第 46-51 行)还演示了对称性验证:用 Faraday::Utils.parse_nested_query(response.body) 能把编码结果还原为原始嵌套哈希,说明 NestedParamsEncoder 的编解码是自洽的。

八、快速上手小结

在 Faraday 中使用 URL 编码请求体,只需记住四件事:

  1. 注册:在 Faraday.new 的块中调用 f.request :url_encoded(等价于 f.use Faraday::Request::UrlEncoded,见 lib/faraday/request/url_encoded.rb);
  2. 传哈希:POST/PUT 时直接传 Ruby Hash,嵌套数组与哈希会被自动展开;
  3. 控制 Content-Type:默认自动设置 application/x-www-form-urlencoded;显式指定其他类型则跳过编码;字符串/IO 作为 body 时只设头不编码;
  4. 切换编码器:需要扁平形式时,通过 Request Options 的 params_encoder: Faraday::FlatParamsEncoder(连接级或请求级)覆盖默认的 NestedParamsEncoder。

相关阅读

登录后查看全文
faraday