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

Когда импорт 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 даёт практический план:
- Временно логируйте события
'pause'и'resume'на критичных потоках. Если конвейер с большим объёмом никогда не ставится на паузу, где-то данные копятся в памяти; - Наблюдайте
writable.writableLength— постоянный рост означает, что буфер не опустошается; - Сэмплируйте 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.