JSON Toolkit

Чтение больших JSON в Node.js: потоковый парсинг с stream-json и backpressure на практике

Главное: Чтение JSON-массива на 186MB через readFileSync и JSON.parse поднимает память до пика 612MB; переход на streamArray из stream-json удерживает её плоской на 104MB. В статье — сравнение четырёх стратегий чтения по замерам, объяснение, почему for await даёт backpressure бесплатно, как событие data его теряет и как настроить highWaterMark и drain на стороне записи.

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

Когда импорт 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 раза больше файла. При дефолтном лимите old space V8 в 1.4–2GB нескольких таких задач параллельно достаточно, чтобы контейнер убило по OOM Kill.

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

Вторая причина: JSON.parse обменивает весь текст на весь граф

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

Стоимость графа объектов разобрана по пунктам в статье Память JSON: учёт по строкам, объектам и массивам: каждая строка занимает реальное место, каждый ключ объекта — отдельный слот, а ширина массива зависит от типов элементов. Пара десятков MB JSON после парсинга регулярно становится в три-пять раз больше, пик добавляется сверху.

Но большинству задач импорта весь граф не нужен: вставлять построчно, фильтровать построчно, преобразовывать построчно — каждая запись может быть освобождена сразу после обработки. Задаче нужна способность «распарсил запись — отдал запись». Это и есть определение потокового парсинга.

Решение: streamArray выдаёт запись за записью, а for await даёт backpressure бесплатно

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, поэтому парсер приостанавливает чтение файла. Медленнее база — медленнее чтение. Это и есть backpressure, образованный естественно, без единой строки дополнительного кода. Разбор на dev.to о приёме муниципального потока на 4GB использует ту же цепочку с pick({filter:'data'}) и сообщает такую же плоскую кривую памяти.

Когда сторона записи проваливается: событие data без паузы поднимает память обратно

Потоковый парсинг дисциплинирует только чтение. Если запись не принимает backpressure, память снова растёт. Классический провал: асинхронная запись внутри обработчика data без внимания к буферу writable:

// Неправильно: событие data + асинхронная запись, backpressure полностью потерян
readable.on('data', async (chunk) => {
  await slowWrite(chunk); // поток не ждёт; буфер продолжает раздуваться
});

В режиме data поток течёт дальше, как бы медленно ни работал slowWrite, и всё копится во внутреннем буфере writable. На той же пробе 186MB мы направили записи в медленный Writable, задерживающийся на 1ms каждый сотый чанк. Без обработки backpressure пик 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, без backpressure та же 407MB ~10s как делать не надо
streamArray + write()/drain та же 161MB ~10s вывод на диск или передача дальше

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

Два показателя заслуживают внимания. Первая и вторая стратегии отличаются в шесть раз по памяти ценой обмена «1.3 секунды» на «скорость БД». Третья и четвёртая отличаются в 2.5 раза: потоковое чтение без backpressure на записи решает лишь половину задачи.

Диагностика: убедиться, что backpressure действительно работает

Проблемы памяти в проде не решаются интуицией. Материал Tencent Cloud по поиску неисправностей backpressure даёт практический план:

  1. Временно логируйте события 'pause' и 'resume' на критичных потоках. Если конвейер с большим объёмом никогда не ставится на паузу, где-то данные копятся в памяти;
  2. Наблюдайте writable.writableLength — постоянный рост означает, что буфер не опустошается;
  3. Сэмплируйте RSS через process.memoryUsage() по интервалам и стройте кривую, различая «рамповый рост» (накопление) и «пилообразную стабильность» (здоровое освобождение).

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

Когда потоковость не ответ

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

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

Когда форма верхнего уровня нерегулярна, сначала посмотрите структуру в инструменте JSON-парсер и форматтер; командно-строчный эквивалент описан в статье jq для больших JSON — jq --stream и streamArray — одна идея в двух средах исполнения.

FAQ

Насколько stream-json медленнее JSON.parse?

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

Backpressure у for await — то же самое, что ручные pause/resume?

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

А если верхний уровень — один огромный объект, а не массив?

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

Как записать результат в JSONL или переслать дальше?

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

Какой самый быстрый монитор памяти для задачи импорта?

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