Menghurai JSON yang belum sampai sepenuhnya: pratonton streaming dan pembaikan tambahan
Inti pati: LLM mengeluarkan JSON token demi token dan API memulangkan respons besar cebisan demi cebisan, tetapi JSON.parse menolak bergerak sehingga dokumen penuh tiba. Artikel ini memisahkan tiga gaya pelaksanaan — pembaikan penuh, tambahan sebenar dan penghuraian separa — menerangkan bagaimana topeng Allow mengekalkan kestabilan pratonton, lengkap dengan ukuran pipeline dan kod sedia untuk produksi.

JSON.parseberjanji «saya hanya mula selepas dokumen penuh tiba», manakala streaming berjanji «saya serahkan data secebis demi secebis». Konfliknya bukan pada kelajuan tetapi pada semantik kelenjapan: dokumen yang belum siap belum mempunyai «hasil penghuraian yang betul» untuk ditimbang.
Gejala: tiga senario yang tidak mampu menunggu teks penuh
Senario pertama ialah aplikasi LLM. Model mengeluarkan JSON token demi token; output berstruktur 8KB boleh mengambil masa puluhan saat untuk sampai habis sementara pengguna menatap panel kosong — sedangkan medan-medan pertama sudah boleh dipaparkan sejak saat pertama. Senario kedua ialah gateway dan proksi: upstream menolak respons berpuluh megabait melalui cebisan HTTP, dan proksi yang mahu menapis medan sebelum memajukan pula memuncak memori jika menimbal semuanya dengan res.json(). Senario ketiga ialah baris mesej dan saluran log: rekod NDJSON tiba satu demi satu dan pengguna tidak mahu mengumpul kelompok.
Persamaannya jelas: data tiba beransur-ansur, sedangkan penghurai standard hanya menerima dokumen lengkap. JSON.parse membaling Unexpected end of JSON input pada cebisan pertama, membaling ralat yang sama pada cebisan ke-65 dan hanya memulangkan hasil pada cebisan akhir. Menunggu bukan satu-satunya pilihan — tetapi dahulu anda mesti menetapkan apa maksudnya «menghurai» dokumen yang belum siap.
Semantik penghuraian berdasarkan awalan: adakah setiap cebisan sah?
Ambil satu tatasusunan pesanan berukuran 7847 bait, potong kepada cebisan 120 aksara bagi mensimulasikan ketibaan streaming (Node v22.13.1, jsonrepair 3.15.0, partial-json 0.1.7), lalu jalankan tiga penghurai ke atas setiap awalan:
| Pendekatan | Kejayaan pada 66 awalan | Masa terkumpul | Semantik |
|---|---|---|---|
JSON.parse |
1 (cebisan akhir sahaja) | 2.1 ms | ada semua atau tiada langsung |
partial-json (Allow.ALL) |
66 (sejak cebisan pertama) | 14.3 ms | sentiasa memulangkan «yang diketahui setakat ini» |
jsonrepair dijalankan semula penuh pada setiap awalan |
66 | 23.8 ms | boleh dihurai selepas kurungan dilengkapkan, tetapi dikira semula dari awal setiap kali |
Dua kesimpulan utama. Pertama, kegagalan JSON.parse tidak membawa sebarang maklumat: kedudukan ralat yang dilaporkan sentiasa di hujung, jadi anda tidak tahu berapa lagi yang belum sampai mahupun sama ada bahagian yang diterima itu konsisten dengan dirinya sendiri. Kedua, pembaikan penuh yang dijalankan semula pada setiap awalan boleh dilakukan tetapi tidak berbaloi: purata panjang teks setiap panggilan meningkat secara linear dan kos terkumpul meningkat secara kuadratik, O(n²). 23.8 ms kelihatan tidak berbahaya; apabila teks mencapai saiz megabait, faktor yang sama bertukar menjadi detik CPU terbuang.
Dan berhati-hati: «boleh dihurai secara awalan» tidak bermaksud «data lengkap». Nombor terakhir awalan yang dilengkapkan boleh disambung oleh cebisan berikutnya, dan rentetan terakhir boleh terpotong di tengah jujukan escape — di situlah punca segala ketidakstabilan pratonton streaming.
Tiga gaya pelaksanaan dan tempat masing-masing
Perpustakaan di sisi streaming terbahagi kepada tiga sikap, dan tersalah pilih sikap lebih merugikan daripada tersalah pilih perpustakaan:
| Perpustakaan | Sikap | Sesuai | Tidak sesuai |
|---|---|---|---|
jsonrepair (3.15.0) |
pembaikan penuh + Transform stream | anda menerima «dokumen yang akan siap kelak» dan mahu hasil tanpa kehilangan | sekadar pratonton (output ialah teks penuh yang dibetulkan, bukan objek data) |
partial-json (0.1.7) |
penghuraian separa, membenarkan membuang ekoran yang belum siap | pratonton UI: setiap awalan terus mempunyai objek yang boleh digunakan | simpanan ke pangkalan data (pratonton mungkin kekurangan medan, nombor tidak stabil) |
jsonmend (0.1.3) |
tambahan sebenar, korpus konsistensi awam | saluran paip «masuk sebahagian, keluar satu versi» tanpa mengimbas semula lampau | dokumen yang sudah berakhir (penghuraian penuh lebih pantas) |
Ketiga-tiganya bukan pesaing. jsonrepair mengeksport jsonrepairTransform melalui subpath ./stream, satu Transform stream standard: cebisan dimasukkan di kiri, di kanan keluar blok teks JSON yang dibetulkan, dan dijamin gabungannya sama dengan menghurai keseluruhan teks sekali gus — persamaan decode(encode(x)) === x kekal terjaga. partial-json menjaga garisan yang lain: setiap awalan terus menghasilkan objek, dengan harga mengetepikan janji «hasil akhirnya tidak berubah». jsonmend mengekang garisan ketiga dengan korpus konsistensi awam: tambahan sebenar, semantik boleh diselaraskan, kedua-dua pelaksanaan berkongsi asas regresi yang sama.
Topeng Allow: medan mana yang berani dipaparkan dalam pratonton
Inti pati partial-json bukan «mampu menghurai input yang rosak sebarang cara», tetapi pengisytiharan pihak pemanggil sendiri tentang ketidaklengkapan yang sanggup diterima. Topeng digabung secara bit mengikut jenis JSON (STR, NUM, ARR, OBJ…); buang satu jenis, nilai yang belum siap bagi jenis itu tidak akan masuk pratonton:
import { parse, Allow } from 'partial-json';
parse('{"price": 12', Allow.ALL);
// → { price: 12 } nombor 12 ialah «terbaca setakat ini»
parse('{"price": 1234.5', Allow.ALL);
// → { price: 1234.5 } medan yang sama telah berubah: pratonton tidak stabil
parse('{"price": 12', Allow.ALL & ~Allow.NUM);
// → {} tanpa bit NUM, nombor yang belum siap tidak dipaparkan
Inilah penemuan paling bernilai secara kejuruteraan daripada ukuran: nombor seperti harga dan kaunter yang boleh disambung oleh cebisan berikutnya berubah di UI pada setiap bingkai; manakala Allow.ALL & ~Allow.NUM memerintahnya diam menunggu sehingga siap baharu muncul. Rentetan juga sama — rentetan yang terpotong di tengah jujukan escape Unicode dibuang dengan selamat oleh partial-json 0.1.7, bukan diteka. Kestabilan pratonton bukan hadiah daripada penghurai; pemanggil membelinya dengan topeng.
Kos pelaksanaan pembaikan streaming: penimbal undur dan salinan kuadratik
Saluran paip streaming bukan sekadar membungkus API penuh dalam gelung for. Pada sampel 66 cebisan yang sama, saluran paip dengan jsonrepairTransform mengambil keseluruhan 6.7ms, manakala pembaikan penuh pada setiap awalan 23.8ms — jurang 3.5 kali berpunca daripada lapisan pelaksanaan: pelaksanaan streaming hanya menoleh ke belakang dalam tetingkap yang perlu, output ditulis secara tambahan dengan penimbal, dan teks terdahulu tidak disalin berulang kali.
Port teras streaming jsonrepair ke HarmonyOS ArkTS (praktik penyesuaian perpustakaan pihak ketiga openHarmony) mendedahkan tiga kos khusus: laluan streaming di huluan perlu mengumpul «penimbal undur», jadi untuk dokumen kecil hasilnya menunggu flush — pengarang lalu menulis IncrementalRepairer berasingan untuk teks pendek; laluan regular di huluan menyalin output keseluruhan berulang kali, sifatnya kuadratik, dan semasa port OutputBuilder membuangnya; dan masih ada satu perangkap aksara sempadan — syarat text[i] === undefined sebagai ujian «telah baca hingga akhir» apabila ditukar kepada charAt akan tertipu, kerana ''.includes('') sentiasa true, jadi pelampaian sempadan mula-mula disekat dengan rentetan kosong. Butiran ini menjelaskan mengapa «pembaikan streaming» berhak mempunyai slot kategori tersendiri: kerumitan kejuruterannya dan pembaikan sekali gus berada pada aras yang berbeza.
Perlu dicatat juga sempadan yang diketahui: isu #214 dalam jsonrepair melaporkan pembaikan streaming menolak awalan sah yang kehilangan koma sebelum nilai berlambak-slash — dalam mod streaming, dari segi leksikal sukar membezakan «aksara seterusnya belum tiba» dengan «input tidak sah»; tetingkap undur itulah harga yang dibayar untuk kekaburan ini.
Cara melaksanakannya: pratonton dan simpanan berjalan berasingan
Gabungkan semantik di atas menjadi satu saluran paip; prinsipnya muat dalam satu ayat: pratonton menggunakan penghuraian separa, simpanan menggunakan penghuraian ketat.
import { jsonrepairTransform } from 'jsonrepair/stream';
import { parse as partialParse, Allow } from 'partial-json';
// Laluan 1: saluran paip tanpa kehilangan. Masuk: cebisan, keluar: teks JSON dibetulkan, akhirnya pengesahan ketat
const tr = jsonrepairTransform();
tr.pipe(finalSink); // finalSink kemudian membuat JSON.parse + pengesahan perniagaan
chunkStream.pipe(tr);
// Laluan 2: saluran paip pratonton. Setiap awalan menghasilkan satu bingkai UI; nombor dan rentetan yang belum siap disekat topeng
function onChunk(buffer) {
const preview = partialParse(buffer, Allow.ALL & ~Allow.NUM & ~Allow.STR);
render(preview); // lukis hanya medan stabil; medan yang cepat berubah biar menunggu
}
Kontrak kedua-dua laluan berbeza dan tidak saling menggantikan: bingkai pratonton boleh kekurangan medan, bingkai simpanan tidak boleh; bingkai simpanan mesti menunggu strim berakhir dan melalui JSON.parse penuh dengan pengesahan perniagaan, manakala bingkai pratonton tidak pernah disimpan. Jika huluan ialah output LLM, sebelum menyimpan anda perlu menilai berdasarkan stop_reason sama ada terpotong — aliran «lihat stop_reason dahulu, baharulah bercakap tentang pembaikan» telah dikupas dalam artikel pembaikan JSON terpotong daripada LLM, tidak diulang di sini.
Bilakah tidak perlu streaming
Tiga syarat penolakan; cukup memenuhi satu sahaja, gunakan penghuraian penuh secara jujur: fail kecil — JSON.parse biasa sehingga ~22MB membaca sekali gus lazimnya di bawah satu saat, streaming hanya menambah kod; statistik sekali gus sahaja — agregasi lebih mudah dengan jq --stream atau NDJSON baris demi baris, lihat panduan praktikal JSONL; penerima hiliran tidak menerima data separa — contohnya jumlah wang, satu nilai perantaraan yang tersalah darab daripada pratonton sudah pun kerugian sebenar; ketika itu pratonton streaming hanya berharga sebagai «palang kemajuan».
Penghuraian streaming yang diselesaikan sentiasa ialah «tidak mampu menunggu», bukan «lebih pantas». Dengan volum teks yang sama, jumlah CPU penghuraian penuh sentiasa lebih kecil daripada sebarang pilihan streaming; yang anda tukar ialah masa sehingga bait pertama boleh digunakan dan paras memori yang kekal tetap. Jika pertukaran ini difahami, pemilihan teknologi tidak akan bergoyang lagi.
Soalan lazim
Bolehkah objek pratonton terus disimpan ke pangkalan data?
Tidak boleh. Pratonton ialah petikan «yang diketahui setakat ini»: nombor boleh disambung oleh cebisan berikutnya, rentetan boleh terpotong, medan boleh sementara tiada. Sebelum menyimpan mesti menunggu strim berakhir, menjalankan JSON.parse ketat penuh ke atas keseluruhan teks, kemudian pengesahan perniagaan. Pratonton hanya milik lapisan UI.
partial-json atau jsonrepair?
Bergantung pada yang anda mahu: teks atau objek. Teks dibetulkan tanpa kehilangan (untuk dihurai semula di hiliran) — gunakan jsonrepair, output streamingnya dijamin sepadan dengan penghuraian keseluruhan; objek untuk setiap awalan terus dipaparkan pada UI — gunakan partial-json, dengan topeng Allow ditetapkan mengikut tahap ketidakstabilan yang sanggup dipikul.
Adakah penghuraian streaming mengurangkan jumlah masa?
Tidak. Jumlah CPU penghuraian penuh sentiasa paling kecil, dan pilihan streaming lagi membayar kos penyelenggaraan keadaan. Streaming menukar tiga perkara: masa sehingga cebisan pertama boleh digunakan, memori yang tidak membesar mengikut panjang keseluruhan, dan keupayaan memproses ketika masih menerima (memajukan, menapis, memaparkan).
Elemen tatasusunan tiba satu demi satu dan saya mahu memprosesnya satu demi satu — bagaimana?
Itu jalan yang lain: stream-json dengan streamArray membaling {key, value} tepat apabila elemen tertutup, dan dengan for await menghasilkan backpressure secara semula jadi — sesuai untuk import pukal gaya «hurai kemudian tulis», manakala artikel ini berbincang tentang pratonton pada skala keseluruhan dokumen.