Faraday 的 UrlEncoded 中间件:请求体 URL 编码的完整实战指南
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。它的职责可以概括为两点:
- 转换请求体:将
Faraday::Request#body中的 key/value 哈希转换为 url-encoded 字符串; - 自动设置请求头:把
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 行)定义了三条核心规则:
- 哈希值:递归调用
encode_hash,生成parent%5Bkey%5D=value形式(第 53-62 行),且嵌套哈希的键会先被转义再排序; - 数组值:递归调用
encode_array,默认(array_indices = false)生成parent%5B%5D=value形式(第 64-77 行);若设置@array_indices = true则生成parent%5B0%5D=...、parent%5B1%5D=...带索引形式; - 标量/ 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 编码请求体,只需记住四件事:
- 注册:在
Faraday.new的块中调用f.request :url_encoded(等价于f.use Faraday::Request::UrlEncoded,见 lib/faraday/request/url_encoded.rb); - 传哈希:POST/PUT 时直接传 Ruby Hash,嵌套数组与哈希会被自动展开;
- 控制 Content-Type:默认自动设置
application/x-www-form-urlencoded;显式指定其他类型则跳过编码;字符串/IO 作为 body 时只设头不编码; - 切换编码器:需要扁平形式时,通过 Request Options 的
params_encoder: Faraday::FlatParamsEncoder(连接级或请求级)覆盖默认的NestedParamsEncoder。