JSON 工具箱

JSON 还没收完怎么解析:流式预览与增量修复

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

实战约 5 分钟发布于 2026-11-16更新于 2026-11-16
流式 JSON 逐块到达时部分解析与增量修复的管道示意

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 天然背压,适合「解析后写库」的批量导入,和本文「文档级流式预览」是两个粒度。

参考资料

同系列工具

相关文章

JSON 修复指南:LLM 坏输出的救回与信任边界

LLM 输出被 markdown 围栏包裹、带着尾逗号和 Python 字面量,手改过的配置少了引号,这些 JSON 严格解析器一概拒收。本文按修复器真实能力划清九类可修与四类不能修的边界,讲状态机与正则两派实现的差别,给出 jsonrepair 与 json-repair 双栈接入顺序,以及修复结果如何用校验器兜底。

实战约 6 分钟更新于 2026-11-08

LLM 输出的 JSON 被截断了怎么办:先看停止原因,再谈修复

模型返回的 JSON 少了结尾,解析器只给一个列号,补上括号就能跑——但缺口被藏进了数据里。本文按停止原因判定、输出额度定容、schema 字段排序与部分恢复的诚实披露,划清截断场景下能修与必须重试的边界。

实战约 5 分钟更新于 2026-11-14

JSONL 文件实操:打开、转换与坏行排错

整份 .jsonl 丢给 JSON.parse 报错,多半不是文件坏了,而是读取方式错了。这篇给出查看与逐行读取的标准写法、与 JSON 数组互转的命令、六类坏行的排查表,以及流式接口里逐行消费的正确姿势。

实战约 9 分钟更新于 2026-11-06