JSON Toolkit

Leggere JSON di grandi dimensioni in Node.js: parsing in streaming con stream-json e backpressure in pratica

In sintesi: Leggere un array JSON da 186MB con readFileSync e JSON.parse porta la memoria al picco di 612MB; passare al streamArray di stream-json la mantiene piatta a 104MB. Questo articolo confronta quattro strategie di lettura con misurazioni, spiega perché for await produce backpressure naturalmente, come l'evento data la perde e come configurare highWaterMark e drain sul lato scrittura.

Intermedio~5 min di letturaPubblicato il 2026-11-17Aggiornato il 2026-11-17
Streaming di un file JSON di grandi dimensioni in Node.js: confronto tra streamArray e backpressure

Quando l'import di un file JSON da 186MB spinge il processo a 600MB di memoria, il colpevole non è la dimensione del file — JSON.parse ha scambiato tutto il testo con l'intero grafo di oggetti in un colpo solo. Cambiate strategia di lettura e la curva di memoria diventa piatta.

Un sintomo: un file da 186MB con picco a 612MB

I job di import lato server sono il terreno dove questo problema compare più spesso: sincronizzazioni pianificate degli ordini, pulizia dei log, caricamento in blocco della cronologia. L'implementazione tipica assomiglia a questa:

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

Abbiamo misurato questo schema su Node 22.13. Il campione: un array di 480 000 record di ordini, file da 186MB con stringhe, oggetti annidati e array nei campi, a imitazione di strutture aziendali reali. Picco del Maximum resident set size misurato con /usr/bin/time -v: la lettura richiede 1.3 secondi, ma l'RSS culmina a 612MB — 3.3 volte il file. Con il limite predefinito del vecchio spazio di V8 a 1.4–2GB, pochi job di questo tipo in parallelo bastano per finire uccisi da OOM Kill nel container.

L'aritmetica non è esotica: il testo grezzo occupa una copia in memoria (circa 186MB), il grafo di oggetti prodotto dal parse ne occupa un'altra (ogni chiave stringa, ogni intestazione di oggetto annidato e ogni array ha un costo), e il processo di parsing stesso alloca transitoriamente sopra. Arrivare a 600MB di picco è normale.

Seconda causa: JSON.parse scambia tutto il testo con tutto il grafo

Il contratto di JSON.parse è «dammi il testo completo, ti restituisco il grafo completo». Esige che tutto il testo sia pronto prima di iniziare e consegna il risultato solo alla fine. Non esiste alcun meccanismo per «prima ecco i primi 1 000 record».

Il costo del grafo di oggetti è stato misurato voce per voce in Il conto memoria di JSON: ogni stringa occupa spazio reale, ogni chiave di oggetto prende uno slot, e la larghezza di un array dipende dai tipi degli elementi. Una decina di MB di JSON diventa regolarmente da tre a cinque volte più grande dopo il parsing, con il picco aggiunto sopra.

Ma la maggior parte degli import non ha mai bisogno dell'intero grafo: inserire riga per riga, filtrare riga per riga, trasformare riga per riga — ogni record può essere liberato appena elaborato. Quello che il job serve è «un record parseato, un record emesso». È precisamente la definizione di parsing in streaming.

La soluzione: streamArray consuma record per record, e for await fornisce la backpressure

stream-json implementa il parser come uno Transform stream che consuma token e non aspetta mai l'intero file. Quando il livello superiore è un array, streamArray() emette {key, value} nell'istante in cui ogni elemento termina di essere parseato:

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);
  }
}

Sullo stesso file da 186MB con gli stessi 480 000 record, questa versione culmina a 104MB di RSS, piatto per tutta la durata. In memoria esistono solo «l'elemento corrente + lo stato del parser»; i record finiti vengono recuperati immediatamente.

Un dettaglio facile da perdere: for await non tira il record successivo dal parser finché saveToDb non è completata, quindi il parser smette di leggere il file. Database più lento, lettura più lenta — questa è la backpressure, formata naturalmente, senza una riga di codice in più. Un articolo su dev.to sull'ingestion di un feed municipale da 4GB usa la stessa catena con pick({filter:'data'}) e riporta una curva di memoria altrettanto piatta.

Quando il lato scrittura fallisce: un evento data senza pausa riporta su la memoria

Il parsing in streaming disciplina solo la lettura. Se la scrittura non accetta la backpressure, la memoria risale. Il fallimento classico: scritture asincrone dentro un handler di data senza curarsi del buffer del writable:

// Sbagliato: evento data + scrittura asincrona, backpressure persa del tutto
readable.on('data', async (chunk) => {
  await slowWrite(chunk); // lo stream non aspetta; il buffer continua a gonfiarsi
});

In modalità data lo stream continua a fluire, per quanto lento sia slowWrite, e tutto si accumula nel buffer interno del writable. Sullo stesso campione da 186MB abbiamo indirizzato i record verso uno Writable lento che ritarda 1ms ogni centesimo blocco. Ignorando la backpressure l'RSS culmina a 407MB; sospendendo con await once(sink, 'drain') quando write() restituisce false, a 161MB. La differenza di 246MB sono letteralmente dati seduti nel buffer di scrittura.

// Corretto: pausa quando write() restituisce false, ripresa al drain
for await (const { value } of pipeline) {
  if (!sink.write(value)) {
    await once(sink, 'drain');
  }
}

Due note pratiche: assemblando catene di stream a mano, impostate highWaterMark esplicitamente su ogni stream — il valore predefinito di 16 in objectMode è troppo generoso per oggetti grandi; e preferite pipeline() da stream/promises a pipe(), che si occupa di propagazione degli errori e pulizia.

Le misurazioni: picco di memoria di quattro strategie

Strategia Campione Picco RSS Durata Uso
readFileSync + JSON.parse 186MB / 480k 612MB 1.3s file piccoli, accesso casuale
streamArray + for await + scritture lente su DB (0.5ms ciascuna) lo stesso 104MB (piatto) dettato dal DB ingestion record per record, trasformazioni
streamArray + scritture via data, senza backpressure lo stesso 407MB ~10s l'esempio da non seguire
streamArray + write()/drain lo stesso 161MB ~10s scrivere su disco o inoltrare

Ambiente: Node 22.13, Maximum resident set size via /usr/bin/time -v, campione sintetico con campi di forma aziendale, esecuzioni singole senza media, scritture lente simulate con setTimeout. Questi numeri sono conclusioni di ordine di grandezza per questo campione, non costanti universali — misurate sui vostri dati.

Due letture meritano attenzione. La prima e la seconda strategia differiscono di un fattore sei in memoria, al prezzo di scambiare «1.3 secondi» con «la velocità del DB». La terza e la quarta differiscono di un fattore 2.5: leggere in streaming senza backpressure in scrittura risolve solo metà del problema.

Diagnosi: confermare che la backpressure funziona davvero

I problemi di memoria in produzione non si risolvono a intuizione. Un articolo di Tencent Cloud sul troubleshooting della backpressure offre un metodo pratico:

  1. Loggate temporaneamente gli eventi 'pause' e 'resume' sugli stream critici. Se una pipeline ad alto throughput non pausa mai, da qualche parte i dati si stanno accumulando in memoria;
  2. Osservate writable.writableLength — crescita continua significa che il buffer non si svuota mai;
  3. Campionate l'RSS con process.memoryUsage() a intervalli e tracciate la curva, distinguendo «crescita a rampa» (accumulo) e «plateau a denti di sega» (liberazione sana).

Sotto la semantica di for await, gli eventi pause e resume devono alternarsi; se non scattano mai, cercate un listener data di troppo o un await dimenticato.

Quando lo streaming non è la risposta

Lo streaming non è la soluzione predefinita. Per file di poche decine di MB con accesso casuale per chiave, una singola chiamata a JSON.parse è più semplice ed economica. Aprire un file grande nel browser è un altro dominio di problemi — come aprire un file JSON grande copre la scala dei visualizzatori. I confini del parsing in streaming sono chiari:

  • il livello superiore è un array (o i dati si dividono come JSONL), il consumo è sequenziale, senza sguardi indietro;
  • la dimensione del file è incontrollata o supera ampiamente la riserva dell'heap, e un import non deve raddoppiare l'ingombro del processo;
  • il consumatore ha un divario di velocità naturale (scritture su DB, chiamate API a valle), quindi serve backpressure anziché un tubo a piena portata.

Quando la forma di livello superiore è irregolare, ispezionate prima la struttura nello strumento parser e formattatore JSON; l'equivalente da riga di comando è coperto in jq per JSON grandi — jq --stream e streamArray sono la stessa idea in due runtime.

FAQ

Quanto è più lento stream-json rispetto a JSON.parse?

Nel parsing puro vince JSON.parse: 1.3 secondi per il campione da 186MB, contro circa 7 secondi per streamArray senza latenza di scrittura (parsing a token più costruzione di oggetti record per record). Il beneficio dello streaming vive interamente sul lato memoria: il picco scende da 612MB a 104MB. Un import è comunque limitato dal DB, quindi pagare qualche secondo di parsing per un margine di memoria di sei volte è di solito un buon affare; dentro risposte API al millisecondo, no.

La backpressure di for await è la stessa di pause/resume manuali?

Semanticamente sì: for await sospende lo stream leggibile mentre il corpo del ciclo è in attesa, equivalendo a chiamare pause() quando write() restituisce false e resume() al drain. La differenza: la meccanica del linguaggio tiene la contabilità e non dimentica nulla; il cablaggio manuale perde la backpressure dell'intera catena appena un punto manca.

E se il livello superiore è un unico oggetto enorme?

stream-json fornisce streamObject() (emette per chiave) e il filtro Pick (parsea solo il sottoalbero scelto). Se bastano alcuni campi, Pick con un JSONPath riduce l'intero grafo al sotto-grafo richiesto. L'input multi-documento (JSON Lines, sequenze JSON) conviene dividerlo riga per riga e trattarlo come documenti indipendenti.

Come scrivere il risultato come JSONL o inoltrarlo a valle?

Il lato scrittura pone la stessa domanda di backpressure: fs.createWriteStream e http.request richiedono di controllare il valore di ritorno di write() e attendere once(stream, 'drain') su false — oppure collegare il writable a pipeline(). La verifica è semplice: la curva di RSS dopo una passata deve essere stabile e writableLength non deve crescere persistentemente.

Qual è il monitor di memoria più rapido per un job di import?

Versione minima: un timer che campiona process.memoryUsage().rss ogni 100ms in un array e stampa il massimo alla fine. Più preciso: /usr/bin/time -v node task.js dà direttamente il Maximum resident set size. Nei container, mettete la linea di allarme al 70% del limite di memoria lasciando margine al GC.