JSON Toolkit

Читання великих JSON у Node.js: потоковий парсинг stream-json і бекпресур на практиці

Головне: Читання 186MB JSON-масиву через readFileSync і JSON.parse дає пік пам'яті 612MB; перехід на streamArray з stream-json утримує її рівними на 104MB. У статті — порівняння чотирьох стратегій читання за вимірами, пояснення, чому for await дає бекпресур автоматично, як data-подія його втрачає і як налаштувати highWaterMark та drain на боці запису.

Середній~5 хв читанняОпубліковано 2026-11-17Оновлено 2026-11-17
Потокове читання великого JSON у Node.js: порівняння streamArray та бекпресуру

Коли імпорт файлу JSON на 186MB піднімає процес до 600MB пам'яті, винен не розмір файлу — JSON.parse обміняв увесь текст на весь граф об'єктів за один раз. Змініть стратегію читання, і крива пам'яті стане рівною.

Один симптом: файл 186MB з піком 612MB

Серверні завдання імпорту — найпоширеніше місце цієї проблеми: регулярна синхронізація замовлень, очищення логів, масове завантаження історії. Типова реалізація виглядає так:

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

Ми протестували цей шаблон на Node 22.13. Зразок — масив із 480 000 записів замовлень, файл 186MB із рядками, вкладеними об'єктами та масивами у полях, що імітує реальну бізнес-структуру. Пік Maximum resident set size за /usr/bin/time -v: файл читається за 1.3 секунди, але RSS сягає 612MB — у 3.3 рази більше за файл. За типової межі старого простору V8 у 1.4–2GB кілька таких завдань одночасно — прямий шлях до OOM Kill у контейнері.

Арифметика банальна: сирий текст займає одну копію в пам'яті (близько 186MB), граф об'єктів після parse — другу (кожен рядковий ключ, заголовок вкладеного об'єкта та масив мають накладні витрати), а сам процес парсингу тимчасово виділяє ще. Пік у 600MB — норма.

Друга причина: JSON.parse обмінює весь текст на весь граф

Контракт JSON.parse: «дай мені повний текст — отримаєш повний граф об'єктів». Він вимагає, щоб увесь текст був на місці до початку парсингу, і віддає результат лише після завершення. Механізму «спочатку перші 1000 записів» не існує.

Витрати на граф об'єктів розібрано по пунктах у статті Облік пам'яті JSON: кожен рядок займає реальний простір, кожен ключ об'єкта — окремий слот, а ширина масиву залежить від типів елементів. Півтора десятка MB JSON регулярно перетворюються у три-п'ять разів більший граф, і пік додається зверху.

Але більшості завдань імпорту весь граф не потрібен: вставляти по рядку, фільтрувати по рядку, трансформувати по рядку — кожен запис можна звільнити одразу після обробки. Потрібна лише здатність «розпарсив запис — віддав запис». Саме це є визначенням потокового парсингу.

Рішення: streamArray споживає запис за записом, а for await дає бекпресур автоматично

stream-json реалізує парсер як Transform-потік, який споживає токени й ніколи не чекає весь файл. Якщо верхній рівень — масив, streamArray() випромінює {key, value} у мить завершення парсингу кожного елемента:

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

На тому ж файлі 186MB і тих самих 480 000 записах цей варіант має пік RSS 104MB, рівний упродовж усього запуску. У пам'яті одночасно існують лише «поточний елемент + стан парсера», оброблені записи звільняються негайно.

Легко пропустити деталь: for await не витягує наступний запис із парсера, доки не завершиться saveToDb, тож парсер призупиняє читання файлу. Повільніша база — повільніше читання. Це і є бекпресур, сформований природно, без жодного рядка додаткового коду. Опис на dev.to про імпорт муніципального трафіку на 4GB використовує той самий ланцюг із pick({filter:'data'}), і крива пам'яті так само рівна.

Коли сторона запису провалюється: подія data без пауни підіймає пам'ять назад

Потоковий парсинг дисциплінує лише читання. Якщо запис не приймає бекпресур, пам'ять знову зростає. Класичний провал — асинхронний запис у обробнику data без уваги до буфера writable:

// Помилка: подія data + асинхронний запис, бекпресур повністю втрачено
readable.on('data', async (chunk) => {
  await slowWrite(chunk); // потік не чекає; буфер продовжує рости
});

У режимі data потік тече далі, як би повільно slowWrite не працював, тож усе накопичується у внутрішньому буфері writable. На тому ж зразку 186MB ми направили записи у повільний Writable, що затримується на 1ms кожен сотий чанк. Без обробки бекпресуру пік RSS сягав 407MB; з await once(sink, 'drain'), коли write() повертає false, — 161MB. Різниця у 246MB — це буквально дані, що лежать у буфері запису.

// Правильно: пауза, коли write() повертає false, продовження на drain
for await (const { value } of pipeline) {
  if (!sink.write(value)) {
    await once(sink, 'drain');
  }
}

Ще дві поради: збираючи ланцюг потоків вручну, задавайте highWaterMark явно для кожного потоку — типових 16 у objectMode замало для великих об'єктів; і надавайте перевагу pipeline() із stream/promises замість pipe(), який візьме на себе поширення помилок і прибирання.

Виміри: пік пам'яті чотирьох стратегій

Стратегія Зразок Пік RSS Тривалість Застосування
readFileSync + JSON.parse 186MB / 480 тис. 612MB 1.3s малі файли, довільний доступ
streamArray + for await + повільні записи у БД (0.5ms кожен) той самий 104MB (рівно) диктується БД посторінкове завантаження, трансформації
streamArray + запис у data, без бекпресуру той самий 407MB ~10s як не треба
streamArray + write()/drain той самий 161MB ~10s вивід на диск або далі по конвеєру

Середовище: Node 22.13, Maximum resident set size з /usr/bin/time -v, синтетичний зразок із бізнес-подібними полями, одиночні запуски без усереднення, імітація повільних записів через setTimeout. Це висновки про порядок величини для цього зразка, а не універсальні константи — міряйте на власних даних.

Два показники заслуговують уваги. Перший і другий відрізняються у шість разів пам'яттю, і ціна — обмін «1.3 секунди» на «так швидко, як БД». Третій і четвертий відрізняються у 2.5 разу: потокове читання без бекпресуру на записі розв'язує лише половину проблеми.

Діагностика: як переконатися, що бекпресур працює

Проблеми пам'яті у проді не вирішуються інтуїцією. Матеріал Tencent Cloud з діагностики бекпресуру дає практичний план:

  1. Тимчасово логуйте події 'pause' і 'resume' на критичних потоках. Якщо конвеєр із великим об'ємом ніколи не стає на паузу, десь накопичуються дані;
  2. Спостерігайте за writable.writableLength — стабільне зростання означає, що буфер не спорожніє;
  3. Семпліть RSS через process.memoryUsage() за інтервалом і малюйте криву, розрізняючи «плавне зростання» (накопичення) і «пилкоподібну стабільність» (здорове звільнення).

При for await події pause і resume мають чергуватися; якщо вони не спрацьовують, шукайте зайвий слухач data або пропущений await.

Коли потоковість не потрібна

Потоковість — не відповідь за замовчуванням. Для файлів у кілька десятків MB із довільним доступом за ключем один виклик JSON.parse простіший і дешевший. Перегляд великого файлу у браузері — інша предметна область, дивіться як відкрити великий JSON-файл. Межі застосування потокового парсингу чіткі:

  • верхній рівень — масив (або дані можна розбити як JSONL), споживання послідовне, без повернень назад;
  • розмір файлу неконтрольований або значно перевищує запас купи, і один імпорт не повинен подвоювати пам'ять;
  • споживач має природний розрив швидкості (записи у БД, виклики API вниз за течією), тож потрібен бекпресур, а не пожежний шланг на повній швидкості.

Якщо форма верхнього рівня нерегулярна, спершу подивіться структуру в інструменті JSON-парсер і форматувальник; командний рядок описано у статті jq для великих JSON — jq --stream і streamArray це сама ідея у двох виконаннях.

FAQ

Наскільки stream-json повільніший за JSON.parse?

У чистому парсингу перемагає JSON.parse: 1.3 секунди для зразка 186MB проти приблизно 7 секунд у streamArray без затримок запису (токеновий парсинг плюс побудова об'єктів по записах). Виграш потоковості повністю на боці пам'яті: пік падає з 612MB до 104MB. Імпорт все одно обмежений записом у БД, тож кілька зайвих секунд парсингу за шестикратний запас пам'яті — зазвичай вигідна угода; всередині відповідей API за мілісекунди — ні.

Чи бекпресур for await — це те саме, що ручні pause/resume?

Семантично так: for await призупиняє читаний потік, поки тіло циклу не завершено, що еквівалентно виклику pause() коли write() повертає false і resume() на drain. Різниця в тому, що мова бере бухгалтерію на себе і нічого не забуває; ручна проводка втрачає бекпресур усього ланцюга за одного пропуску.

А якщо верхній рівень — один величезний об'єкт, а не масив?

stream-json має streamObject() (випромінює по ключах) і фільтр Pick (парсить лише обране піддерево). Якщо потрібні кілька полів, Pick із JSONPath звужує повний граф до потрібного підграфа. Змішаний багатодокументний вхід (JSON Lines, JSON-послідовності) краще розбивати по рядках і обробляти як незалежні документи.

Як записати результат у JSONL або переслати далі?

Бік запису — та сама історія з бекпресуром: fs.createWriteStream і http.request вимагають перевірки значення write() і await once(stream, 'drain') на false — або підключіть writable до pipeline(). Перевірка проста: крива RSS після запуску має бути стабільною, а writableLength не рости постійно.

Який найшвидший монітор пам'яті для завдання імпорту?

Мінімальний варіант: таймер, що кожні 100ms семплить process.memoryUsage().rss у масив і друкує максимум наприкінці. Точніше — /usr/bin/time -v node task.js прямо дає Maximum resident set size. У контейнерах тримайте лінію тривоги на 70% ліміту пам'яті, залишаючи запас для GC.