JSON 还没收完怎么解析:流式预览与增量修复
结论:大模型逐 token 吐 JSON、接口按块返回大响应,JSON.parse 却要等全文到齐才肯动手。本文按逐前缀解析的完整性语义讲清三类实现(全量修复、真增量、部分解析)的分工,给出 Allow 掩码控制预览稳定性、流式管线替代平方级重跑的实测数据与落地代码。

JSON.parse的契约是「全文到齐才动手」,而流式场景的契约是「来一块处理一块」——两者的矛盾不在性能,在完整性语义:一个没写完的文档,根本不存在「正确解析结果」。
现象:三个等不了全文的场景
第一个场景是 LLM 应用。模型按 token 逐个吐出 JSON,一条 8KB 的结构化输出要几十秒才能收完,用户盯着空白等待框——其实第 1 秒就有前几个字段可以显示了。第二个场景是网关与代理:上游按 HTTP chunk 推一个几十 MB 的响应,代理想在转发前做字段过滤,等 res.json() 全量缓冲等于把内存峰值翻几倍。第三个场景是消息队列与日志管道:一条 NDJSON 记录跟着前一条追加到达,消费者不想攒批。
三个场景的共同点是:数据是渐次到达的,而标准解析器的接口只接受完整文档。JSON.parse 在第 1 块就抛 Unexpected end of JSON input,在第 65 块仍然抛同一个错,直到最后一块才返回结果。等待不是唯一的选项,但你必须先想清楚「没写完的文档」解析出来算什么。
逐前缀解析的基本语义:每一块都合法吗
把一份 7847 字节的订单数组按 120 字符一块切开模拟流式到达(Node v22.13.1,jsonrepair 3.15.0,partial-json 0.1.7),逐前缀跑三个解析器:
| 解析方式 | 66 个前缀的成功次数 | 累计耗时 | 语义 |
|---|---|---|---|
JSON.parse |
1(仅最后一块) | 2.1 ms | 全有或全无 |
partial-json(Allow.ALL) |
66(第 1 块起) | 14.3 ms | 永远给出「目前已知」的值 |
jsonrepair 逐前缀全量重跑 |
66 | 23.8 ms | 补全括号后可解析,但每次从头算 |
关键结论有两个。其一,JSON.parse 的失败不携带任何信息:报错位置永远是末尾,你既不知道还差多少,也不知道已收到的部分是否自洽。其二,逐前缀全量重跑(每次把已收到的全部文本重新 repair 一遍)可行但不划算:每块平均文本长度线性增长,累计成本按 O(n²) 涨,23.8ms 看着不多,文本到 1MB 量级时这个倍数会变成秒级浪费。
另外注意:逐前缀「可解析」不等于「数据完整」。前缀补全后给出的最后一个数字可能被下一块续写,最后一个字符串可能截断在转义序列中间——这是流式预览一切稳定性的根源。
三类实现怎么分工
流式侧的库分三种姿态,选错姿态比选错库更伤:
| 库 | 姿态 | 适用 | 不适用 |
|---|---|---|---|
jsonrepair(3.15.0) |
全量修复 + Transform 流 | 拿到的是「将来会完整的文档」,要无损结果 | 只想要预览(修复输出是整段文本,不是数据对象) |
partial-json(0.1.7) |
部分解析,允许丢弃未完成尾部 | UI 预览:每个前缀都要一个可用对象 | 落库(预览可能缺字段、数字不稳定) |
jsonmend(0.1.3) |
真增量修复,开放一致性语料 | 喂一段出一版、不重扫前文的管道 | 已停止的完整文档(直接全量解析更快) |
三者不是竞争关系。jsonrepair 的 ./stream 子路径导出 jsonrepairTransform,是一个标准 Transform 流:把块从左边灌进去,右边出来的是修好的 JSON 文本块,保证拼起来与全文一次解析的结果严格相等——decode(encode(x)) === x 这条线它守得住。partial-json 守的是另一条线:每个前缀都能立刻给对象,代价是放弃「结果最终不变」的承诺。jsonmend 用公开一致性语料约束第三条线:真增量、语义可对齐,双端实现有同一套回归依据。
Allow 掩码:预览里哪些字段敢显示
partial-json 的核心不是「能解析多烂的输入」,而是调用方声明愿意承受哪种不完整。掩码按 JSON 类型逐位组合(STR、NUM、ARR、OBJ……),去掉某一类,对应类型的未完成值就不进预览:
import { parse, Allow } from 'partial-json';
parse('{"price": 12', Allow.ALL);
// → { price: 12 } 数字 12 是"目前读到的"
parse('{"price": 1234.5', Allow.ALL);
// → { price: 1234.5 } 同一个字段变了:预览不稳定
parse('{"price": 12', Allow.ALL & ~Allow.NUM);
// → {} 去掉 NUM 位,未完成的数字不显示
这是实测里最有工程价值的一条:价格、计数这类会被续写的数字,出现在 UI 上的每一帧都可能变;而 Allow.ALL & ~Allow.NUM 让它们安静地等到写完再出现。字符串同理——截断在 Unicode 转义中间的字符串,partial-json 0.1.7 的修复是把它安全丢弃而不是硬猜。预览的稳定性不是解析器送的,是调用方用掩码换的。
流式修复的实现代价:回看缓冲与平方拷贝
流式管线不是把全量 API 套个 for 循环。同一份 66 块样本,jsonrepairTransform 流式管线总耗时 6.7ms,而逐前缀全量重跑累计 23.8ms——3.5 倍的差距来自实现层:流式实现只在必要的窗口里回看,输出用增量缓冲追加,不重复拷贝前文。
把 jsonrepair 流式核心移植到鸿蒙 ArkTS 的实践披露了三个具体的实现代价:上游 streaming 路径要攒「回看缓冲」,小文档反而要等 flush 才出结果,所以作者另写了一个 IncrementalRepairer 专门给短文本做边收边看的增量预览;上游 regular 路径把输出整段反复拷贝是平方级的,移植时加 OutputBuilder 消掉;还有一个边界字符坑——text[i] === undefined 判「读到末尾」在换成 charAt 后,''.includes('') 恒为 true 会骗过字符成员判断,越界必须先挡空串。这些细节解释了为什么「流式修复」值得单独一个分类位:它的工程复杂度和一次性修复不在一个量级。
已知边界也要记一笔:jsonrepair 的 issue #214 报告了流式修复会拒绝「斜杠前缀值前缺逗号」的合法前缀——流式状态下「下一个字符还没到」和「输入非法」在词法上难以区分,回看窗口就是为这种歧义付出的代价。
怎么落地:预览与落库分开走
把前面的语义合成一条流水线,原则只有一句话:预览用部分解析,落库用严格解析。
import { jsonrepairTransform } from 'jsonrepair/stream';
import { parse as partialParse, Allow } from 'partial-json';
// 链路一:无损管线。块进来,修好的 JSON 文本出去,最后严格校验一次
const tr = jsonrepairTransform();
tr.pipe(finalSink); // finalSink 收到后 JSON.parse + 业务校验
chunkStream.pipe(tr);
// 链路二:预览管线。每个前缀给一帧 UI,未完成数字与字符串被掩码挡住
function onChunk(buffer) {
const preview = partialParse(buffer, Allow.ALL & ~Allow.NUM & ~Allow.STR);
render(preview); // 只画稳定的字段,快的字段先不上屏
}
两条链路的契约不同,不能互相替代:预览帧允许缺字段,落库帧不允许;落库帧必须等流结束并跑一次完整 JSON.parse 加业务校验,预览帧从不落库。如果上游是 LLM 输出,落库前还要按停止原因判定是否截断——那套「先看 stop_reason 再谈修复」的流程在LLM 截断修复里已经展开,这里不重复。
什么时候别做流式
三个否决条件,命中任何一条就老老实实全量解析:文件小——22MB 以内普通 JSON.parse 一次读完通常不到一秒,流式只增加代码复杂度;只做一次性统计——聚合场景直接用 jq 的 --stream 或逐行 NDJSON 更省事,见 JSONL 文件实操;下游消费方不接受部分数据——比如计算总金额,预览帧的中间值乘错一次就是资损,这类场景流式预览只剩「进度条」价值。
流式解析解决的问题始终是「等不起」,不是「更快」。同样的文本量,全量解析的总 CPU 时间永远小于任何流式方案;你换到的是首字节可用时间和恒定的内存水位。这个取舍想清楚,选型就不会摇摆。
常见问题
预览对象能直接存进数据库吗?
不能。预览是「目前已知」的快照:数字可能被下一块续写,字符串可能截断,字段可能暂时缺失。落库前必须等流结束,对完整文本跑一次严格 JSON.parse,再过业务校验。预览只进 UI 层。
partial-json 和 jsonrepair 选哪个?
看你要文本还是对象。要无损的修复文本(转给下游再解析)用 jsonrepair,它的流式输出保证与全文解析结果相等;要每个前缀立刻得到对象做 UI 预览用 partial-json,并按字段承受不稳定的程度配置 Allow 掩码。
流式解析能降低总耗时吗?
不能。总 CPU 时间上全量解析永远最快,流式方案还要多付状态维护的 overhead。流式换到的是三样东西:首块可用时间、不随全文长度增长的内存水位、以及边收边处理(转发、过滤、展示)的能力。
数组元素逐个到达想逐个处理怎么办?
那是另一条路径:stream-json 的 streamArray 在每个元素闭合时抛出 {key, value},配合 for await 天然背压,适合「解析后写库」的批量导入,和本文「文档级流式预览」是两个粒度。