Roda是Ruby世界里一个以路由树著称的轻量级Web框架，它的插件机制让功能扩展变得非常灵活。当需要向客户端持续推送数据，比如导出大型CSV、生成实时日志流或者代理大文件下载时，传统的先组装完整响应体再返回的方式会带来内存暴涨和首字节延迟过高的问题。HTTP的分块传输编码正是为此而生，而Roda::Plugins::Chunked插件配合其Body类，把分块响应体的生成与流式写入封装成了几行代码就能用好的能力。本文将围绕这个插件，从协议原理、源码实现到实战用法逐层展开。
一、分块传输编码的底层格式与Content-Length的差异
要理解Roda的Chunked插件做了什么，得先回到HTTP协议本身。在HTTP/1.1中，如果服务端在发送响应时无法提前知道内容的总长度，可以不设置Content-Length头，而是声明Transfer-Encoding: chunked。此时响应体不再是一个完整的字节串，而是一系列分块，每个分块由三部分组成：十六进制表示的长度行、紧随其后的数据本体、以及一个空行（CRLF）。
举个最简单的例子，下面就是一个合法的分块响应体片段：
4\r\n Wiki\r\n 5\r\n pedia\r\n 0\r\n \r\n
客户端读到长度为0的终止块后，就知道整个响应结束。与Content-Length方式相比，分块编码有几点本质差异：第一，服务端可以边生成边发送，不必等全部内容就绪；第二，内存占用与内容总量解耦，只需为当前分块分配缓冲；第三，代理服务器和浏览器都能渐进式处理数据，前端甚至可以在JavaScript里用ReadableStream逐段消费。当然代价也有——无法支持范围请求，压缩和校验需要额外处理，不过在流式场景下这些通常不是核心诉求。
值得一提的是，在Rack的语境里，如果应用返回的body对象没有转换成数组的能力，且没有设置Content-Length，许多Rack服务器（如Puma、Unicorn）会自动启用分块编码。Roda的Chunked插件做的则是更明确、更可控的封装，让开发者主动声明分块行为，并提供了便利的流式写入接口。
二、Roda::Plugins::Chunked插件与Body类的工作机制
Roda的Chunked插件核心思路是：在请求执行结束后、响应写出之前，把原始的响应体包装成一个实现了each方法、按块产出数据的Body对象。Rack服务器调用body.each时，每拿到一段字符串，就按照chunked格式写出长度前缀和数据本体。插件的Body类职责包括：将上游body按需切分、保证每段数据以字符串形式产出、在必要时处理结束回调。
启用插件非常简单，来看一个最小的可运行示例：
require 'roda'
class App < Roda
plugin :chunked
route do |r|
r.get 'stream' do
response['Transfer-Encoding'] = 'chunked'
# 返回一个可枚举对象，插件会逐块写出
Enumerator.new do |yielder|
10.times do |i|
yielder << "line #{i}\n"
sleep 0.5
end
end
end
end
end
run App这段代码里，路由块返回的是一个Enumerator，它惰性产出数据。插件会在响应阶段检测到body没有Content-Length，将其交给分块Body处理。Rack服务器每调用一次each并拿到一个字符串，就发送一个分块。sleep调用模拟了耗时的数据生成过程，浏览器端会每半秒收到一条数据，而不是等五秒后一次性收到全部内容。
更常见也更直接的写法是使用插件提供的流式接口。插件暴露了chunked方法，传入块后可以在块内逐段写入：
class App < Roda
plugin :chunked
route do |r|
r.get 'export' do
chunked do |out|
out.write "id,name,score\n"
User.find_each(batch_size: 500) do |user|
out.write "#{user.id},#{user.name},#{user.score}\n"
end
end
end
end
end这种写法的好处是把控制流交还给了应用代码：find_each每次只加载500条记录，写出后即可被垃圾回收，导出百万行数据也不会撑爆内存。Body类在底层保证了写入的每段数据都会被正确地作为一个独立分块发出，同时在块执行完毕后自动追加终止块（长度为0的空块），客户端得以正常结束接收。
三、实战中的注意点：异常处理、心跳与连接中断
流式响应与一次性响应最大的工程差异在于：数据已经开始发给客户端后，你再也无法修改状态码和响应头了。因此所有校验逻辑、权限检查、异常兜底必须在写出第一个分块之前完成。一旦进入流式写入阶段抛出异常，客户端收到的就是一个不完整的响应，Roda无法再把500错误页发回去。
第二个需要注意的点是反向代理的缓冲。Nginx默认会缓冲上游响应，等攒够一定量才转发给浏览器，这会让流式效果完全失效。需要为对应location添加proxy_buffering off配置，或者让应用输出X-Accel-Buffering: no响应头来禁用缓冲：
r.get 'stream' do
response['X-Accel-Buffering'] = 'no'
chunked do |out|
loop do
out.write "tick: #{Time.now.to_i}\n"
sleep 1
end
end
end第三个点是连接中断的处理。客户端断开连接后，Rack服务器会在下次写数据时触发异常（比如Errno::EPIPE），插件的Body类通常会将其冒泡出来，你在写入块里捕获后应尽快结束生成逻辑，避免继续做无意义的计算：
chunked do |out|
begin
each_expensive_item do |item|
out.write render(item)
end
rescue Errno::EPIPE, IOError
# 客户端已断开，停止生成
end
end最后，如果是长时间的流，建议定期发送心跳数据保持中间设备不断开空闲连接。掌握了这些细节，Roda的Chunked插件就能在你的项目里稳定承担大流量、长耗时接口的流式输出职责。