Czytanie dużych JSON w Node.js: strumieniowe parsowanie z stream-json i backpressure w praktyce
Podsumowanie: Czytanie tablicy JSON o 186MB przez readFileSync i JSON.parse wybija pamięć do szczytu 612MB; przejście na streamArray ze stream-json utrzymuje ją płasko na 104MB. Artykuł porównuje cztery strategie czytania z pomiarami, wyjaśnia, dlaczego for await daje backpressure gratis, jak zdarzenie data je traci i jak ustawić highWaterMark oraz drain po stronie zapisu.

Gdy import pliku JSON o 186MB wystrzeliwuje proces do 600MB pamięci, winna nie jest wielkość pliku — JSON.parse wymienił cały tekst na cały graf obiektów za jednym razem. Zmień strategię czytania, a krzywa pamięci stanie się płaska.
Jeden objaw: plik 186MB ze szczytem 612MB
Zadania importowe po stronie serwera to główne miejsce tego problemu: zaplanowane synchronizacje zamówień, czyszczenie logów, masowe ładowanie historii. Typowa implementacja wygląda tak:
const fs = require('fs');
const raw = fs.readFileSync('./orders.json', 'utf8');
const orders = JSON.parse(raw);
for (const order of orders) await saveToDb(order);
Zmierzyliśmy ten wzorzec na Node 22.13. Próbka: tablica 480 000 rekordów zamówień, plik 186MB z ciągami, zagnieżdżonymi obiektami i tablicami w polach — imitacja realnej struktury biznesowej. Szczyt Maximum resident set size według /usr/bin/time -v: plik czyta się w 1.3 sekundy, ale RSS sięga 612MB — 3.3 raza więcej niż plik. Przy domyślnym limicie old space V8 1.4–2GB kilka takich zadań równolegle wystarczy, żeby kontener skończył jako OOM Kill.
Arytmetyka nie jest egzotyczna: surowy tekst zajmuje jedną kopię w pamięci (około 186MB), graf obiektów po parse drugą (każdy klucz-ciąg, każda głowica zagnieżdżonego obiektu i każda tablica niesie narzut), a sam proces parsowania chwilowo alokuje na wierzchu. Szczyt 600MB to norma.
Druga przyczyna: JSON.parse wymienia cały tekst na cały graf
Umowa JSON.parse: „daj mi pełny tekst — dostaniesz pełny graf". Wymaga, żeby cały tekst był na miejscu przed startem, a wynik oddaje dopiero po zakończeniu. Żadnego mechanizmu „najpierw pierwsze 1000 rekordów" nie ma.
Koszty grafu obiektów rozbite na punkty w artykule Rachunek pamięci JSON: każdy ciąg zajmuje realne miejsce, każdy klucz obiektu jeden slot, a szerokość tablicy zależy od typów elementów. Kilka-kilkanaście MB JSON po parsowaniu regularnie robi się trzy- pięciokrotnie większe, szczyt dochodzi na wierzch.
Ale większości zadań importowych cały graf nigdy nie jest potrzebny: wstawiać wiersz po wierszu, filtrować wiersz po wierszu, transformować wiersz po wierszu — każdy rekord można zwolnić od razu po obrobieniu. Zadanie potrzebuje zdolności „sparsowałem rekord — wydałem rekord". To jest dokładnie definicja strumieniowego parsowania.
Rozwiązanie: streamArray dostarcza rekord po rekordzie, a for await daje backpressure gratis
stream-json implementuje parser jako Transform stream konsumujący tokeny i nigdy nie czeka na cały plik. Gdy poziom najwyższy jest tablicą, streamArray() emituje {key, value} w chwili, gdy każdy element kończy parsowanie:
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);
}
}
Na tym samym pliku 186MB z tymi samymi 480 000 rekordów ta wersja ma szczyt RSS 104MB, płaski przez cały czas trwania. W pamięci istnieją w danym momencie tylko „bieżący element + stan parsera"; skończone rekordy są zwalniane natychmiast.
Łatwy do przeoczenia szczegół: for await nie pociąga kolejnego rekordu z parsera, dopóki saveToDb się nie skończy, więc parser przerywa czytanie pliku. Wolniejsza baza — wolniejsze czytanie. To jest backpressure, ukształtowany naturalnie, bez ani linijki dodatkowego kodu. Rozbiór na dev.to o przyjmowaniu komunalnego feedu na 4GB używa tego samego łańcucha z pick({filter:'data'}) i zgłasza równie płaską krzywą pamięci.
Gdy strona zapisu zawodzi: zdarzenie data bez pauzy wystrzeliwuje pamięć z powrotem
Strumieniowe parsowanie karnuje tylko stronę czytania. Jeśli zapis nie przyjmie backpressure, pamięć znów rośnie. Klasyczna porażka: asynchroniczne zapisy wewnątrz handlera data bez spojrzenia na buffer writable:
// Źle: zdarzenie data + asynchroniczny zapis, backpressure całkowicie stracona
readable.on('data', async (chunk) => {
await slowWrite(chunk); // stream nie czeka; buffer dalej puchnie
});
W trybie data stream płynie dalej, choćby slowWrite był najwolniejszy, a wszystko kumuluje się w wewnętrznym bufferze writable. Na tej samej próbce 186MB skierowaliśmy rekordy do wolnego Writable opóźniającego 1ms na każdym setnym chunku. Bez obsługi backpressure szczyt RSS sięgał 407MB; z wstrzymaniem przez await once(sink, 'drain'), gdy write() zwraca false, — 161MB. Różnica 246MB to dosłownie dane siedzące w bufferze zapisu.
// Dobrze: pauza, gdy write() zwraca false, wznowienie na drain
for await (const { value } of pipeline) {
if (!sink.write(value)) {
await once(sink, 'drain');
}
}
Jeszcze dwie terenowe notatki: składając łańcuch streamów ręcznie, ustawiaj highWaterMark jawnie na każdym streamie — typowe 16 w objectMode to zbyt hojnie dla dużych obiektów; i preferuj pipeline() z stream/promises zamiast pipe(), który weźmie na siebie propagację błędów i sprzątanie.
Pomiary: szczyt pamięci czterech strategii
| Strategia | Próbka | Szczyt RSS | Czas | Zastosowanie |
|---|---|---|---|---|
| readFileSync + JSON.parse | 186MB / 480 tys. | 612MB | 1.3s | małe pliki, dostęp swobodny |
| streamArray + for await + wolne zapisy do DB (0.5ms każdy) | ta sama | 104MB (płaski) | dyktuje DB | przyjęcie rekord po rekordzie, transformacje |
| streamArray + zapisy przez data, bez backpressure | ta sama | 407MB | ~10s | jak nie robić |
| streamArray + write()/drain | ta sama | 161MB | ~10s | zapis na dysk lub przekazanie dalej |
Środowisko: Node 22.13, Maximum resident set size z /usr/bin/time -v, syntetyczna próbka z polami w biznesowym kształcie, pojedyncze przebiegi bez uśredniania, symulacja wolnego zapisu przez setTimeout. Te liczby to wnioski o rzędzie wielkości dla tej próbki, nie uniwersalne stałe — mierz na własnych danych.
Dwa odczyty zasługują na uwagę. Pierwsza i druga strategia różnią się sześciokrotnie w pamięci, w zamian za wymianę „1.3 sekundy" na „szybkość DB". Trzecia i czwarta różnią się 2.5-krotnie: strumieniowe czytanie bez backpressure na zapisie rozwiązuje tylko połowę zadania.
Diagnostyka: upewnić się, że backpressure naprawdę działa
Problemy pamięci na produkcji nie rozwiązują się intuicją. Materiał Tencent Cloud o szukaniu usterek backpressure daje praktyczny plan:
- Tymczasowo loguj zdarzenia
'pause'i'resume'na krytycznych strumieniach. Jeśli rurociąg o dużym wolumenie nigdy nie pauzuje, gdzieś dane kumulują się w pamięci; - Obserwuj
writable.writableLength— stały wzrost oznacza, że buffer nigdy nie opróżnia się; - Sampuluj RSS przez
process.memoryUsage()w odstępach i rysuj krzywą, odróżniając „wzrost rampowy" (kumulacja) od „piłokształtnej stabilności" (zdrowe zwalnianie).
Przy semantyce for await zdarzenia pause i resume muszą się przeplatać; jeśli nigdy nie odpalają, szukaj nadmiarowego listenera data albo zapomnianego await.
Kiedy strumieniowanie nie jest odpowiedzią
Strumieniowanie nie jest odpowiedzią domyślną. Dla plików o paru-kilkunastu MB ze swobodnym dostępem po kluczu jedno wywołanie JSON.parse jest prostsze i tańsze. Otwieranie dużego pliku w przeglądarce to inna domena — jak otworzyć duży plik JSON opisuje drabinę przeglądarek. Granice strumieniowego parsowania są jasne:
- najwyższy poziom to tablica (albo dane daje się rozbijać jako JSONL), konsumpcja jest sekwencyjna, bez zerkania wstecz;
- rozmiar pliku jest niekontrolowany albo daleko przekracza rezerwę heapu, a jeden import nie może podwoić śladu procesu;
- konsument ma naturalny rozjazd prędkości (zapisy do DB, wywołania API w dół), więc potrzebuje backpressure, a nie węża na pełnej mocy.
Gdy kształt najwyższego poziomu jest nieregularny, najpierw zajrzyj do struktury w narzędziu parser i format JSON; odpowiednik w linii poleceń opisuje artykuł jq dla dużych JSON — jq --stream i streamArray to ta sama idea w dwóch środowiskach wykonania.
FAQ
O ile wolniejszy jest stream-json od JSON.parse?
W czystym parsowaniu wygrywa JSON.parse: 1.3 sekundy na próbce 186MB w porównaniu z około 7 sekundami streamArray bez opóźnień zapisu (parsowanie tokenowe plus budowa obiektów rekord po rekordzie). Korzyść strumieniowania leży w całości po stronie pamięci: szczyt spada z 612MB do 104MB. Import i tak hamuje zapis do DB, więc zapłacić kilka sekund parsowania za sześciokrotną rezerwę pamięci to zwykle dobry interes; wewnątrz odpowiedzi API w milisekundach — nie.
Czy backpressure od for await to to samo co ręczne pause/resume?
Semantycznie tak: for await zawiesza czytelny strumień, dopóki trwa ciało pętli, co odpowiada wywołaniu pause(), gdy write() zwraca false, i resume() na drain. Różnica: mechanika języka prowadzi ewidencję i niczego nie zapomina; ręczne okablowanie traci backpressure całego łańcucha, gdy tylko jedno miejsce umknie.
A gdyby najwyższy poziom był jednym ogromnym obiektem?
stream-json dostarcza streamObject() (emituje po kluczach) i filtr Pick (parsuje tylko wybrane poddrzewo). Jeśli wystarcza kilka pól, Pick z JSONPath zawęża cały graf do potrzebnego podgrafu. Wejście wielodokumentowe (JSON Lines, sekwencje JSON) lepiej rozbijać po wierszach i traktować jako niezależne dokumenty.
Jak zapisać wynik jako JSONL albo przekazać dalej?
Strona zapisu to to samo pytanie o backpressure: fs.createWriteStream i http.request wymagają kontroli zwracanej wartości write() i czekania once(stream, 'drain') przy false — albo podłącz writable do pipeline(). Weryfikacja jest prosta: krzywa RSS po przebiegu musi być stabilna, a writableLength nie może rosnąć trwale.
Jaki jest najszybszy monitor pamięci dla zadania importu?
Wersja minimalna: timer, który co 100ms sampuluje process.memoryUsage().rss do tablicy i na końcu drukuje maksimum. Dokładniej: /usr/bin/time -v node task.js daje wprost Maximum resident set size. W kontenerach trzymaj linię alarmu na 70% limitu pamięci, zostawiając zapas dla GC.