JSON Toolkit

Membaca JSON besar di Node.js: parsing streaming dengan stream-json dan backpressure dalam praktik

Intinya: Membaca array JSON 186MB dengan readFileSync dan JSON.parse mendorong memori ke puncak 612MB; beralih ke streamArray dari stream-json menjaganya tetap datar di 104MB. Artikel ini membandingkan empat strategi pembacaan dengan pengukuran, menjelaskan mengapa for await menghasilkan backpressure secara alami, bagaimana peristiwa data kehilangannya, dan cara mengatur highWaterMark serta drain di sisi tulis.

Menengah±5 menit bacaDiterbitkan 2026-11-17Diperbarui 2026-11-17
Streaming file JSON besar di Node.js: perbandingan streamArray dan backpressure

Ketika mengimpor file JSON 186MB mendorong proses ke 600MB memori, bukan ukuran file yang bersalah — JSON.parse menukar seluruh teks dengan seluruh graf objek dalam sekali tarik. Ubah strategi pembacaan dan kurva memori menjadi datar.

Satu gejala: file 186MB dengan puncak 612MB

Tugas impor sisi server adalah tempat utama masalah ini: sinkronisasi pesanan terjadwal, pembersihan log, pemuatan histori massal. Implementasi tipikal tampak seperti ini:

const fs = require('fs');
const raw = fs.readFileSync('./orders.json', 'utf8');
const orders = JSON.parse(raw);
for (const order of orders) await saveToDb(order);

Kami mengukur pola ini di Node 22.13. Sampel: array 480.000 rekaman pesanan, file 186MB dengan string, objek bersarang dan array di dalam kolom, meniru struktur bisnis nyata. Puncak Maximum resident set size diukur dengan /usr/bin/time -v: file terbaca dalam 1.3 detik, tetapi RSS mencapai 612MB — 3.3 kali ukuran file. Dengan batas bawaan old space V8 1.4–2GB, beberapa tugas seperti ini berjalan paralel cukup untuk membuat kontainer jadi korban OOM Kill.

Aritmetikanya tidak eksotis: teks mentah menempati satu salinan dalam memori (sekitar 186MB), graf objek hasil parse menempati salinan kedua (setiap kunci string, setiap kepala objek bersarang dan setiap array membawa biaya tambahan), dan proses parsing sendiri mengalokasikan sementara di atasnya. Mencapai puncak 600MB adalah hal normal.

Penyebab kedua: JSON.parse menukar seluruh teks dengan seluruh graf

Kontrak JSON.parse: «beri saya teks lengkap — dapatkan graf lengkap». Ia menuntut seluruh teks tersedia sebelum mulai dan hanya menyerahkan hasil setelah selesai. Tidak ada mekanisme «ini dulu 1.000 rekaman pertama».

Biaya graf objek telah diukur per butir dalam Kas memori JSON: setiap string menempati ruang nyata, setiap kunci objek mengambil satu slot, dan lebar array bergantung pada tipe elemen. Beberapa lusin MB JSON secara rutin menjadi tiga hingga lima kali lebih besar setelah parsing, dengan puncak ditambahkan di atasnya.

Namun sebagian besar tugas impor tidak pernah butuh seluruh graf: menyisipkan baris demi baris, memfilter baris demi baris, mentransformasi baris demi baris — setiap rekaman bisa dibebaskan segera setelah diproses. Yang tugas butuhkan adalah kemampuan «selesai parse satu rekaman — serahkan satu rekaman». Itulah tepatnya definisi parsing streaming.

Solusi: streamArray menyuplai rekaman demi rekaman, dan for await memberikan backpressure gratis

stream-json mengimplementasikan parser sebagai Transform stream yang mengonsumsi token dan tak pernah menunggu seluruh file. Ketika level teratas adalah array, streamArray() memancarkan {key, value} pada saat setiap elemen selesai di-parse:

const fs = require('fs');
const { chain } = require('stream-chain');
const { parser } = require('stream-json');
const { streamArray } = require('stream-json/streamers/StreamArray');

async function importOrders(filePath) {
  const pipeline = chain([
    fs.createReadStream(filePath, { highWaterMark: 64 * 1024 }),
    parser(),
    streamArray(),
  ]);
  for await (const { key, value } of pipeline) {
    await saveToDb(value);
  }
}

Pada file 186MB yang sama dengan 480.000 rekaman yang sama, versi ini memiliki puncak RSS 104MB, datar sepanjang waktu. Dalam memori setiap saat hanya ada «elemen saat ini + status parser»; rekaman yang selesai langsung direklaim.

Detail yang mudah terlewat: for await tidak menarik rekaman berikutnya dari parser sampai saveToDb selesai, sehingga parser berhenti membaca file. Basis data lebih lambat, pembacaan lebih lambat — itulah backpressure, terbentuk alami, tanpa satu baris kode tambahan. Uraian di dev.to tentang mengambil feed transportasi kota 4GB memakai rantai yang sama dengan pick({filter:'data'}) dan melaporkan kurva memori sama datarnya.

Ketika sisi tulis gagal: peristiwa data tanpa jeda mendorong memori naik kembali

Parsing streaming hanya mendisiplinkan sisi baca. Jika tulis tidak menerima backpressure, memori naik lagi. Kegagalan klasik: menulis asinkron di dalam handler data tanpa peduli buffer writable:

// Salah: peristiwa data + tulis asinkron, backpressure hilang sepenuhnya
readable.on('data', async (chunk) => {
  await slowWrite(chunk); // stream tidak menunggu; buffer terus membengkak
});

Dalam mode data stream terus mengalir, betapapun lambat slowWrite, dan semuanya menumpuk di buffer internal writable. Pada sampel 186MB yang sama, kami mengarahkan rekaman ke Writable lambat yang menunda 1ms pada setiap chunk ke-seratus. Tanpa penanganan backpressure puncak RSS mencapai 407MB; dengan penangguhan melalui await once(sink, 'drain') saat write() mengembalikan false, 161MB. Selisih 246MB secara literal adalah data yang duduk di buffer tulis.

// Benar: jeda saat write() mengembalikan false, lanjut di drain
for await (const { value } of pipeline) {
  if (!sink.write(value)) {
    await once(sink, 'drain');
  }
}

Dua catatan lapangan lagi: saat merakit rantai stream secara manual, tetapkan highWaterMark secara eksplisit pada setiap stream — nilai bawaan 16 dalam objectMode terlalu longgar untuk objek besar; dan utamakan pipeline() dari stream/promises alih-alih pipe(), yang menangani propagasi kesalahan dan pembersihan.

Pengukuran: puncak memori empat strategi

Strategi Sampel Puncak RSS Durasi Penggunaan
readFileSync + JSON.parse 186MB / 480 ribu 612MB 1.3s file kecil, akses acak
streamArray + for await + tulis DB lambat (0.5ms masing-masing) sama 104MB (datar) mengikuti tempo DB ingest rekaman demi rekaman, transformasi
streamArray + tulis via data, tanpa backpressure sama 407MB ~10s contoh buruk
streamArray + write()/drain sama 161MB ~10s tulis ke disk atau teruskan

Lingkungan: Node 22.13, Maximum resident set size via /usr/bin/time -v, sampel sintetis dengan kolom berbentuk bisnis, run tunggal tanpa perataan, simulasi tulis lambat via setTimeout. Angka-angka ini adalah kesimpulan tingkat magnitudo untuk sampel ini, bukan konstanta universal — ukur dengan data Anda sendiri.

Dua pembacaan berhak perhatian. Strategi pertama dan kedua berbeda enam kali dalam memori, dengan harga pertukaran «1.3 detik» menjadi «kecepatan DB». Ketiga dan keempat berbeda 2.5 kali: pembacaan streaming tanpa backpressure pada tulisan hanya menyelesaikan separuh pekerjaan.

Diagnostik: memastikan backpressure benar-benar bekerja

Masalah memori di produksi tidak diselesaikan dengan intuisi. Materi Tencent Cloud tentang penelusuran backpressure memberikan rencana praktis:

  1. Log sementara peristiwa 'pause' dan 'resume' pada stream kritis. Jika pipa dengan volume besar tidak pernah berjeda, di suatu tempat data menumpuk dalam memori;
  2. Pantau writable.writableLength — pertumbuhan berkelanjutan berarti buffer tak pernah kering;
  3. Sampling RSS via process.memoryUsage() pada interval dan gambar kurvanya, bedakan «pertumbuhan tanjakan» (penumpukan) dan «stabil bergerigi» (pemulihan sehat).

Dalam semantik for await, peristiwa pause dan resume wajib bergantian; jika tidak pernah terpicu, cari listener data berlebih atau await yang tertinggal.

Kapan streaming bukan jawabannya

Streaming bukan jawaban bawaan. Untuk file beberapa lusin MB dengan akses acak per kunci, satu panggilan JSON.parse lebih sederhana dan murah. Membuka file besar di browser adalah domain masalah lain — cara membuka file JSON besar membahas tangga viewer. Batas parsing streaming jelas:

  • level teratas adalah array (atau data bisa dipecah sebagai JSONL), konsumsi berurutan, tanpa melihat ke belakang;
  • ukuran file tak terkendali atau jauh melebihi margin heap, dan satu impor tidak boleh menggandakan jejak proses;
  • konsumen memiliki selisih kecepatan alami (tulis DB, panggilan API hilir), jadi butuh backpressure, bukan selang laju penuh.

Ketika bentuk level teratas tidak teratur, periksa dulu strukturnya di alat parser dan formatter JSON; padanan baris perintah dibahas di jq untuk JSON besar — jq --stream dan streamArray adalah satu ide di dua runtime.

FAQ

Seberapa lambat stream-json dibanding JSON.parse?

Pada parsing murni, JSON.parse menang: 1.3 detik untuk sampel 186MB, dibanding sekitar 7 detik untuk streamArray tanpa latensi tulis (parsing token plus pembangunan objek rekaman demi rekaman). Manfaat streaming seluruhnya di sisi memori: puncak turun dari 612MB ke 104MB. Impor memang terbatas oleh tulis DB, jadi membayar beberapa detik parsing untuk margin memori enam kali biasanya transaksi yang bagus; di dalam respons API tingkat milidetik, tidak.

Apakah backpressure for await sama dengan pause/resume manual?

Secara semantik ya: for await menangguhkan stream yang dapat dibaca selama badan loop masih menggantung, setara memanggil pause() saat write() mengembalikan false dan resume() di drain. Bedanya: mekanika bahasa memegang pembukuan dan tidak lupa apa pun; pengkabelan manual kehilangan backpressure seluruh rantai begitu satu titik luput.

Bagaimana jika level teratas adalah satu objek raksasa?

stream-json menyediakan streamObject() (memancarkan per kunci) dan filter Pick (hanya mem-parse subtree yang dipilih). Jika beberapa kolom saja cukup, Pick dengan JSONPath mengecilkan seluruh graf ke subgraf yang dibutuhkan. Input multi-dokumen (JSON Lines, sekuens JSON) sebaiknya dipecah baris demi baris dan diperlakukan sebagai dokumen independen.

Bagaimana menulis hasil sebagai JSONL atau meneruskannya ke hilir?

Sisi tulis adalah pertanyaan backpressure yang sama: fs.createWriteStream dan http.request sama-sama menuntut pemeriksaan nilai kembalian write() dan menunggu once(stream, 'drain') saat false — atau sambungkan writable ke pipeline(). Verifikasi sederhana: kurva RSS setelah satu run harus stabil dan writableLength tidak boleh terus tumbuh.

Apa monitor memori tercepat untuk tugas impor?

Versi minimal: timer yang mensampling process.memoryUsage().rss setiap 100ms ke dalam array dan mencetak maksimum di akhir. Lebih presisi: /usr/bin/time -v node task.js memberikan langsung Maximum resident set size. Di kontainer, letakkan garis alarm di 70% batas memori untuk menyisakan ruang GC.

Referensi

Alat yang sesuai

Artikel terkait

jq dan berkas JSON besar: mengapa -s meledakkan memori dan cara memproses secara streaming

Agregasi ratusan MB log JSON dengan jq -s berakhir di OOM, sementara reduce inputs menghasilkan statistik yang sama hanya dengan beberapa MB RAM. Diukur pada sampel 220 MB dan 2 juta baris: slurp memuncak di 2,08 GB dibanding 3,5 MB untuk reducer streaming. Artikel ini menjelaskan mekanisme konsumsi memori, pemrosesan JSONL baris demi baris, peristiwa path dari --stream, dan tiga jebakan nyata, termasuk keluaran kosong senyap dari -n --stream.

Lanjutan±6 menit bacaDiperbarui 2026-11-12

File JSON besar tidak bisa dibuka? Pilih alat yang tepat sesuai ukuran

Ekspor JSON berukuran puluhan MB sering membuat editor teks dan alat daring membeku, padahal proses parsing sendiri hanya butuh beberapa ratus milidetik. Kami mengukur waktu dan memori di setiap tahap untuk sampel 45 MB berisi 500.000 rekaman, menunjukkan bahwa biaya sesungguhnya ada pada jumlah baris dan node, lalu menyusun tabel pemilihan alat berdasarkan ukuran file: tampilan daring, baris perintah, pemrosesan stream, dan aplikasi desktop.

Menengah±6 menit bacaDiperbarui 2026-11-07