在Ruby项目里集成外部REST API时，响应体可能是标准JSON、空字符串，甚至是只包含空白字符的无效内容。Faraday作为灵活且广泛使用的HTTP客户端，其响应中间件体系允许开发者在请求完成后自动处理body，其中Faraday::Response::ParseJson负责将JSON字符串转换为Ruby对象。但默认实现只做了基础的nil与空字符串判断，一旦遇到带空格或编码异常的响应，就会抛出JSON::ParserError，影响服务稳定性。
理解中间件的执行顺序和判定条件，能够帮助开发者在遇到线上解析错误时快速定位根因，并有针对性地设计容错策略。下面从默认行为、异常来源、自定义中间件和手动解析四个层面展开。
ParseJson中间件的工作机制与默认行为
在Faraday中启用JSON自动解析非常简单，通常只需要在连接构建代码里加入一行faraday.response :json。这个符号:json会被Faraday映射到Faraday::Response::ParseJson中间件类。它属于响应中间件，会在HTTP响应完成之后、业务代码拿到响应对象之前执行，因此从conn.get返回的response.body已经是被解析后的Ruby对象。
conn = Faraday.new(url: 'https://api.ipipp.com') do |faraday|
faraday.response :json
faraday.adapter Faraday.default_adapter
end
response = conn.get('/data')
puts response.body.class
中间件的核心逻辑可以用一个简化版本表示。它会在on_complete回调中读取env[:body]，如果body既不是nil也不是完全空字符串，就调用JSON.parse进行解析，并把解析结果写回env[:body]。这里判断空字符串时使用的是body.empty?，并不会自动去除字符串两端的空格或换行符。
def on_complete(env) body = env[:body] env[:body] = JSON.parse(body) unless body.nil? || body.empty? end
这意味着，如果服务端返回了一个只包含空格、制表符或换行符的200响应，Faraday会把这个双引号包裹的空格字符串交给JSON解析器，而JSON标准中空格本身并不是合法值，因此触发解析错误。另一个值得注意的点是，默认的ParseJson中间件并不会严格检查响应头中的Content-Type。即便服务端返回的是纯文本或HTML，只要body非空，它同样会尝试按JSON解析。这种宽松策略在单一JSON API场景下能减少配置，但在接口返回类型不可控时可能带来额外风险。
空响应的来源与异常定位
空响应并不只出现在204 No Content这一种场景。实际项目中，以下几种情况都可能让ParseJson中间件撞上空body：服务端POST成功后未返回任何内容、网关超时后返回空报文、反向代理配置错误导致200状态码但body为空、某些老版本API在错误时只返回空字符串。只要body是nil或完全空字符串，默认中间件会跳过解析，业务层拿到的是nil或空字符串；但如果是空白字符串，解析就会失败。
异常出现时，最先看到的通常是类似JSON::ParserError: unexpected token at ''的错误信息。由于Faraday中间件在请求调用栈内部，堆栈顶部可能并不直接指向你自己的业务代码，导致排查起来有些绕。可以在Faraday连接配置中加入日志中间件，或者手动输出response.body.inspect来确认原始内容。尤其是当响应体是空格时，普通puts很难看出差异，而inspect会清楚显示字符串的长度和内容。
def blank?(body) body.nil? || body.strip.empty? end
建议在定位空响应问题时，先用上面这种方式统一检查nil、空字符串和空白字符串。很多情况下，问题不是JSON解析器本身，而是上游服务返回了不可预期的空body，或者调用方错误地认为所有2xx响应都有完整JSON。此时单纯给JSON解析加更多rescue只能缓解表面问题，真正需要的是让代码对空响应有明确的业务语义。
自定义SafeParseJson中间件实现容错解析
与其在每次调用处都写重复的判断逻辑，不如在Faraday中间件层统一处理空响应。可以编写一个继承自Faraday::Response::Middleware的类，覆盖on_complete方法。在这个方法里先对body做空白检查，只有确认非空才调用解析；解析失败时也可以根据业务需要设置默认值，而不是让异常一路向上抛。
class SafeParseJson < Faraday::Response::Middleware
def on_complete(env)
body = env[:body]
return if body.nil? || body.strip.empty?
env[:body] = JSON.parse(body)
rescue JSON::ParserError
env[:body] = {}
env[:parse_error] = true
end
end
这个自定义中间件做了三件事：第一，把body.strip.empty?纳入判断，白色空格响应会被直接跳过；第二，捕获JSON::ParserError，避免因无效JSON导致整个请求失败；第三，在env中增加一个parse_error标记，方便业务层后续判断本次解析是否失败。如果不希望丢失原始响应内容，也可以在解析失败时把原始body保存到另一个env字段，以便记录错误日志或调试。
conn = Faraday.new(url: 'https://api.ipipp.com') do |faraday| faraday.use SafeParseJson faraday.adapter Faraday.default_adapter end
注册方式也很直接，faraday.use可以按实例传入中间件类。如果项目里多个地方都需要使用，也可以把SafeParseJson注册成一个符号，比如faraday.response :safe_json，这样调用方式与内置:json几乎一致。需要注意的是，中间件顺序对最终行为有影响。如果同时使用错误处理、日志、缓存等中间件，先后顺序不同可能导致空响应在到达SafeParseJson之前就被其他中间件处理或包装。
手动解析与自动解析的取舍
自动解析虽然省事，但不是所有场景都适合。当响应格式不固定、服务端可能返回JSON也可能返回纯文本时，让Faraday自动解析会掩盖真实响应类型，甚至把合法的非JSON内容变成异常。此时手动控制解析过程会更加清晰。可以先拿到原始body，根据状态码或Content-Type判断是否需要解析，再调用JSON.parse。
response = conn.get('/data')
if response.body.nil? || response.body.strip.empty?
data = {}
else
begin
data = JSON.parse(response.body)
rescue JSON::ParserError => e
puts "响应解析失败: #{e.message}"
data = { error: 'invalid json' }
end
end
这个手动解析的代码把空响应处理、解析失败处理都放在了业务可见的位置，虽然比自动解析多了几行代码，但行为更透明。对于需要区分空响应、无效JSON、合法JSON三种结果的场景来说，手动解析几乎是最好的选择。自动解析更适合那些已经稳定使用JSON格式、上游服务不会返回意外内容、并且希望减少样板代码的项目。
综合来看，Faraday::Response::ParseJson是一个高效的内置工具，但默认实现只覆盖了最基础的情况。如果你正在对接的外部API偶尔返回空白body，或者希望系统在解析失败时拥有降级逻辑，自定义一个带容错能力的响应中间件会是更稳健的方案。理解中间件的执行机制之后，就可以根据自己的业务边界决定哪些地方交给自动解析，哪些地方保留手动控制。
Ruby FaradayParseJson空响应处理修改时间：2026-08-21 05:24:10