NDJSON 流式读取:分片、取消与有界消费实战

用 Node.js 与浏览器构建逐行结果流,处理 UTF-8 分片、单行与总量限制、完成标记、取消和有界界面;附可运行代码及十九项自动化测试的验证边界。

一个后台把十万条校验结果改成逐行返回,首屏确实快了,浏览器却在几分钟后卡死。问题不一定出在网络:服务端可能先把查询结果读进数组,客户端可能把每条记录都塞进 DOM,也可能把没有换行的输入不断拼成一个字符串。接口叫“流式”,不代表链路上的每一段都有内存边界。

这篇文章实现一个可以实际运行的最小链路:Node.js 生成 NDJSON,浏览器用 Fetch 逐条消费,限定单行和总输入大小,用户可以取消,只显示最后五十条。重点不是展示打字机效果,而是回答三个工程问题:收到哪些字节时才能解析一条记录;消费者变慢时谁应该暂停;连接正常结束是否足以宣布业务成功。示例只读数据,不涉及导入数据库,因此不会把网络重试伪装成业务幂等。

先把协议写清楚,别从 split 开始

本文选用 UTF-8、一行一个 JSON 值的 NDJSON。分隔符允许 LF 或 CRLF,发送端为每条记录追加换行。空行在本实现中是错误,最后一条缺少换行也是错误。这是有意选择的严格应用约定,不能声称所有逐行 JSON 工具都采取同样策略。格式定义可核对 NDJSON 项目规范。

业务消息分两种。数据行有 type、连续整数 id 和 text;完成行有 type 和 count。正常响应发送一千条数据,再发 count 为一千的完成行。客户端不仅检查 JSON 能否解析,还检查序号连续、文本类型、完成总数以及完成行之后没有额外数据。字段名来自本文示例,不是 NDJSON 自带的语义。

为什么需要完成行?假设上游查询意外只产出七百条,应用仍正常结束 HTTP 响应。传输层并不知道我们本来想读多少条。客户端如果把读到 EOF 当成业务完成,就会把半份报告显示成完整报告。本文选择“完成消息有效,且随后正常 EOF”才成功;仅看见完成消息还不够,因为后面也可能跟着异常数据。

完成行不能证明数据来自可信源,也不能证明数据库快照一致。它只是在可信服务端正确实现协议的前提下,区分业务正常收尾与没有收尾标记。完成标记不是事务提交或回滚机制,消费失败不会撤销已经写入其他系统的副作用。财务导出还需要快照标识、行数或摘要验证,以及保存成功后的交付确认。把一个布尔标记升级成完整性保证,会越过它真正能解决的问题。

字节分片不是记录分片

服务端写了一行,客户端不一定读到一行。一次读取可能含半个汉字、三条完整记录,也可能只有回车而把换行留到下一块。因此不能对每个读取结果分别调用普通 decode,再 split。中文和表情符号的多字节编码如果跨块,独立解码可能制造替换字符;如果 JSON 恰好还能解析,错误反而更隐蔽。

常见方案是在同一个解码器上使用流式解码,再积累未完成文本。本文选择另一种路线:先在字节层寻找 LF,把一整行放入固定大小缓冲区,再严格解码这一行。UTF-8 的有效多字节字符不会把 ASCII 换行字节藏在延续字节中,因此分行不需要猜字符边界。非法编码由 fatal 模式拒绝。Encoding Standard 定义了流式解码与 fatal 行为,这里使用的是每行独立解码,而非跨块流式解码。

默认缓冲区为六十四 KiB,不包含 LF,若采用 CRLF 则包含末尾的 CR。每个非 LF 字节只写入一次,避免反复拼接整段长字符串造成额外拷贝。到达上限还没有换行就报错,而不是先接受一个无限长字符串、解析后再检查长度。默认总输入上限十 MiB,统计收到的字节,包括分隔符;它属于示例的资源预算,不是 NDJSON 格式限制。

这里仍然不能宣称总内存恒定为六十四 KiB。当前 Fetch 数据块已经由运行时分配,解码会产生字符串,JSON.parse 会产生对象,底层网络也有缓冲。我们限定的是应用自己的未完成行累积空间,并且不把解析过的对象永久保存。若一个上游实现直接交给解析器一个巨大的数据块,该块早已占用内存。接入不可信源时还要限制响应体、对象复杂度、请求时长和并发数。

解析器必须拥有清理责任

下面的 ndjson.mjs 同时提供字节解析与业务消息校验。参数在取得 reader 前验证;一旦获得 reader,无论 JSON 错误、长度超限、业务消费者抛异常,还是外层提前结束迭代,都要走 finally。正常读到 EOF 只释放锁,提前退出则先取消读取再释放锁。取消清理采用尽力而为,取消自身的失败不覆盖原来的解析或业务错误;生产监控可另记清理异常。读锁的含义与取消机制可查 Streams Standard。

export async function* parseNDJSON(body, {maxLineBytes=65536,maxTotalBytes=10485760}={}) {
  if (!Number.isSafeInteger(maxLineBytes) || maxLineBytes<1 ||
      !Number.isSafeInteger(maxTotalBytes) || maxTotalBytes<1) throw Error('invalid limits');
  const reader=body.getReader(), line=new Uint8Array(maxLineBytes);
  const decoder=new TextDecoder('utf-8',{fatal:true,ignoreBOM:true});
  let used=0,total=0,complete=false;
  function parse() {
    let n=used;
    if(n && line[n-1]===13) n--;
    if(!n) throw Error('empty line');
    const value=JSON.parse(decoder.decode(line.subarray(0,n)));
    used=0;
    return value;
  }
  try {
    while(true) {
      const {done,value}=await reader.read();
      if(done) { if(used) throw Error('missing final newline'); complete=true; return; }
      total+=value.byteLength;
      if(total>maxTotalBytes) throw Error('total limit');
      for(const b of value) {
        if(b===10) yield parse();
        else {if(used===maxLineBytes) throw Error('line limit'); line[used++]=b;}
      }
    }
  } finally {
    // 清理失败不覆盖原来的解析或业务异常。
    try {if(!complete) await reader.cancel().catch(()=>{});} finally {reader.releaseLock();}
  }
}
export async function consume(body,onRow,limits) {
  let count=0,ended=false;
  for await(const item of parseNDJSON(body,limits)) {
    if(ended) throw Error('data after done');
    if(item?.type==='row' && item.id===count+1 && typeof item.text==='string') {
      await onRow(item); count++;
    } else if(item?.type==='done' && item.count===count) ended=true;
    else throw Error('invalid message');
  }
  if(!ended) throw Error('missing done');
  return count;
}

代码中的 ignoreBOM 为 true 容易读反:它不是帮我们删掉 BOM,而是让解码结果保留该字符,随后 JSON.parse 拒绝不合约的输入。本例不会自动修复编码问题,也不跳过解析失败的行。对结果报告而言,悄悄漏掉坏行会改变总数和结论,所以失败关闭比“尽可能读完”更合适。若业务是容错日志浏览器,可以另设错误行事件,但要把漏读计数展示出来,不能暗中改变协议。

consume 中对 onRow 使用 await,不是语法装饰。假如这里不等待,十万条记录就可能创建十万个尚未完成的异步任务,解析器表面上没有保存数据,内存仍被 Promise、闭包和业务队列占满。当前实现一次只交给业务一条记录,上一条处理完成才交付下一条。这保证了本函数的消费串行,不代表操作系统完全停止收包,也不代表所有代理都会立即把暂停传回数据库。

解析层允许任意 JSON 值,业务层只接受约定对象,两层分开是为了便于测试与复用。不要把 JSON.parse 成功等同于输入可信:字段长度、枚举、租户权限、链接来源等仍是业务验证。本例不会把未知字段合并进配置,也不会把 text 交给 innerHTML,避免把数据读取变成对象属性污染或 HTML 注入入口。

服务端也不能先加载全部记录

服务端只依赖 Node.js 内置模块,本地实测版本是 v24.22.1。建立一个目录,把三个代码块分别保存为 ndjson.mjs、server.mjs、index.html。没有 npm 依赖,没有环境变量和数据库凭据。服务仅监听回环地址,不应直接当作已具备鉴权的生产接口暴露。

import {createServer} from 'node:http';
import {Readable} from 'node:stream';
import {pipeline} from 'node:stream/promises';
import {readFile} from 'node:fs/promises';
import {fileURLToPath} from 'node:url';
export const server=createServer(async(req,res)=>{
  if(req.method!=='GET') {res.writeHead(405);res.end();return;}
  if(req.url==='/rows') {
    res.writeHead(200,{'Content-Type':'application/x-ndjson; charset=utf-8','Cache-Control':'no-store'});
    async function* records(){
      for(let id=1;id<=1000;id++) yield JSON.stringify({type:'row',id,text:`记录${id}🌏`})+'\n';
      yield JSON.stringify({type:'done',count:1000})+'\n';
    }
    try {await pipeline(Readable.from(records()),res);} catch(e) {
      // 中途失败不能再写一个假装成功的 JSON 响应。
      if(!res.destroyed) res.destroy(e);
    }
    return;
  }
  const paths={'/':['index.html','text/html; charset=utf-8'],'/ndjson.mjs':['ndjson.mjs','text/javascript; charset=utf-8']};
  const entry=paths[req.url];
  if(!entry){res.writeHead(404);res.end();return;}
  try {const data=await readFile(new URL(entry[0],import.meta.url));res.writeHead(200,{'Content-Type':entry[1]});res.end(data);}
  catch {res.writeHead(500);res.end();}
});
if(process.argv[1]===fileURLToPath(import.meta.url)) server.listen(3000,'127.0.0.1');

Readable.from 接受异步生成器,pipeline 负责把可读流接到 HTTP 响应,并处理流错误。关于 pipeline 的错误清理和背压语义,以 Node.js Stream 文档 为准。这里没有为了演示手写 write 与 drain 的竞态处理;生产代码如果需要逐块自定义调度,也必须同时处理关闭与错误,不能无限等待一个再也不会发生的 drain。

这个例子逐条构造数据,不先建立一千项数组。替换成数据库时,应使用有界批次或游标;生成器 finally 中释放游标,取消时终止可取消的查询。仅仅把结果数组包成 Readable,并没有改善数据库结果集的内存占用。还要避免在一个长事务里为慢客户端无限保留快照:可设置最长导出时间,或先异步生成受控文件,再提供下载。

服务端一旦发送响应头,中途错误就不能再可靠地改成一个新的 JSON 错误响应。示例让流失败,不发送假的 done。HTTP 200 只表示请求在发送响应头时被接受,客户端最终状态还取决于流是否完整。页面错误提示必须能承认“已有部分结果,但整体失败”,否则运维会看到成功请求数上升,用户却拿到残缺结果。

真实后端还应给每个请求设置并发额度、查询超时和权限约束。客户端取消不等于后端所有计算立即结束;外部数据库或远程服务是否响应取消,必须各自验证。本文生成器只有廉价内存计算,没有验证任何数据库驱动取消行为,也没有用模拟的客户端取消推出服务器资源已经瞬间归零。

页面要有结果上限,而不是不断追加

下面是完整 index.html。开始按钮在当前任务结束前禁用,避免新旧请求同时修改同一个状态。取消按钮使用同一请求的 AbortController。页面只保留最后五十条,文本用 textContent 插入;这不是通用虚拟列表,但足以明确展示数据缓存与界面节点都应有预算。

<!doctype html><meta charset="utf-8"><title>有界流读取</title>
<button id="start">开始</button><button id="stop" disabled>取消</button>
<p id="status" role="status">未开始</p><ol id="rows"></ol>
<script type="module">
import {consume} from './ndjson.mjs';
const start=document.querySelector('#start'),stop=document.querySelector('#stop');
const status=document.querySelector('#status'),rows=document.querySelector('#rows');
let controller;
stop.onclick=()=>controller?.abort();
start.onclick=async()=>{
  start.disabled=true;stop.disabled=false;rows.replaceChildren();
  controller=new AbortController();status.textContent='读取中';
  try {
    const response=await fetch('/rows',{signal:controller.signal});
    if(!response.ok || !response.body || response.headers.get('content-type')?.split(';')[0]!=='application/x-ndjson') {
      await response.body?.cancel();throw Error('response rejected');
    }
    const n=await consume(response.body,async item=>{
      const li=document.createElement('li');li.textContent=item.text;rows.append(li);
      if(rows.children.length>50) rows.firstElementChild.remove();
      // 演示慢消费者,不宣称每条都完成了一次真实绘制。
      await new Promise(resolve=>setTimeout(resolve,1));
    });
    status.textContent=`完整收到 ${n} 条,展示最后 50 条`;
  } catch(e) {status.textContent=controller.signal.aborted?'已取消,结果不完整':`读取失败:${e.message},结果不完整`;}
  finally {start.disabled=false;stop.disabled=true;controller=null;}
};
</script>

每条记录后的短定时器只是模拟慢消费者,让取消有机会被用户操作。它不等同于每条记录完成了浏览器绘制,也不应原封不动搬进高吞吐页面。实际报告通常把一小批结果汇总后再更新界面,同时保留一个有限队列;批次越大,绘制次数越少,但首批延迟和单次主线程占用越大,需要按目标设备测量。

启动命令是 node server.mjs,浏览器打开 http://127.0.0.1:3000/。正常情况下状态显示完整收到一千条,列表只保留最后五十条。开始后点击取消,应显示已取消、结果不完整;已显示的行可以保留用于查看,但不能被误认为完整报告。如果需要取消后清空界面,应把这个产品决定明确写进交互逻辑,而不是由网络错误偶然决定。

跨域部署时不能把本例的相对路径机械替换成任意 URL。应重新验证认证、CORS、可读响应头以及用户是否有权读取整个数据集合。反向代理、压缩、中间缓存还可能把小块数据聚合,导致服务端在流式发送,浏览器却迟迟收不到首条。应分别测量查询首行、服务端首写、浏览器首条解析、页面首批可见时间,避免用一个总耗时掩盖具体阻塞位置。

怎样证明边界真的生效

本次实际执行了十九项 Node.js 自动化测试,全部通过,没有跳过或失败。测试直接导入上面两个模块,用人工构造的 ReadableStream 控制分片,还启动回环 HTTP 服务验证一千条消息和取消。中文及表情符号被故意按单字节切开,CRLF 也被拆开;这比在本机随便 fetch 一次更容易稳定触发边界问题。

失败用例包括空行、末尾没有换行、坏 JSON、超过单行上限、超过总量上限、非法 UTF-8、BOM、错误序号、缺少 done,以及 done 后仍有数据。上限测试同时覆盖“刚好等于上限”与“超出”,避免实现比文案多拒绝一个字节。提前 break 和解析错误的测试还检查 cancel 被调用、读锁被释放。

慢消费者测试把两次回调之间的处理刻意延迟,并记录同时活跃的回调数,最大值为一。这个断言证明 consume 没有无界并发派发业务任务,不是网络吞吐测试。HTTP 取消测试证明 Node.js Fetch 的消费路径在 abort 后拒绝继续完成,也不是浏览器端到端测试。本文没有实测 Safari、Chrome 的按钮与绘制行为,没有反向代理压缩测试,没有长期内存曲线,也没有声称能处理某个每秒记录数。

如果要独立验证最关键的分片性质,可以在同目录增加以下最小测试文件。这是完整测试集中的一个可直接运行用例,不把一条测试冒充十九条。保存为 smoke.mjs,运行 node --test smoke.mjs,预期通过;把解析器改成按数据块独立解码后,这种输入很容易暴露乱码问题。

import {test} from 'node:test';
import assert from 'node:assert/strict';
import {parseNDJSON} from './ndjson.mjs';
test('逐字节传输中文与表情',async()=>{
  const bytes=new TextEncoder().encode('{"text":"中文🌏"}\n');
  let offset=0;
  const body=new ReadableStream({pull(c){
    if(offset===bytes.length) c.close();
    else c.enqueue(bytes.slice(offset,++offset));
  }});
  const result=[];
  for await(const item of parseNDJSON(body)) result.push(item);
  assert.deepEqual(result,[{text:'中文🌏'}]);
});

上线前还应增加长时间慢消费者、服务端中途异常、客户端断网、后台标签页、低内存设备和代理缓冲场景。最有价值的指标不是“收到了多少块”,而是单行拒绝次数、未完整结束次数、取消后后台任务存活时间、每请求峰值内存,以及首条可用结果的延迟分布。这些指标对应具体故障,不需要为了证明流式优越而编造一组漂亮性能数字。

什么时候不应该用这套方案

如果响应只有几十条小数据,普通 JSON 数组配合分页更简单:一次验证、一处错误处理、成熟的缓存语义,未必值得换成流协议。如果用户需要任意回看、排序和定位历史记录,只有最后五十条的页面明显不满足需求,应保留分页查询能力,而不是把所有历史留在浏览器里冒充实时系统。

NDJSON 更适合有限但较长的结果流,业务能够逐条处理,并且愿意明确“不完整”的状态。需要可靠断线续传时,还要设计稳定游标、快照版本和重放规则;仅用递增 id 再自动重连,会把排序变化、重复记录和遗漏混在一起。本文刻意不自动重试,因为错误后盲目拼接两个响应,比直接失败更容易制造难以察觉的数据错误。

最终的设计判断不是“流比数组先进”,而是每一段是否承担了清晰责任:生产端按需生成,解析端限制未完成输入,业务端串行或有界消费,界面限制保留量,完成语义由协议定义,取消负责释放资源。任何一段继续无限积累,流式接口都可能只是把内存问题换了位置。

相关文章

评论

登录后即可参与讨论

暂无评论。