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 天然背壓,適合「解析後寫庫」的批次導入,和本文「文件級串流預覽」是兩個粒度。