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