Node.js에서 큰 JSON 읽기: stream-json 스트리밍 파싱과 배압 실전
핵심 요약: 186MB JSON 배열을 readFileSync + JSON.parse로 읽으면 피크 메모리가 612MB에 달합니다. stream-json의 streamArray로 한 건씩 소비하도록 바꾸면 104MB에서 일정하게 유지됩니다. 이 글은 네 가지 읽기 방식의 실측 비교를 제시하고, for await가 왜 자연스럽게 배압을 만드는지, data 이벤트가 배압을 어떻게 잃는지, 쓰기 측의 highWaterMark와 drain 설정 방법을 설명합니다.

186MB JSON 파일 하나를 임포트했을 뿐인데 프로세스 메모리가 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(문자열, 중첩 객체, 배열을 포함하는 실무형 구조). /usr/bin/time -v로 측정한 결과 읽기는 1.3초 만에 끝나지만 Maximum resident set size는 612MB — 파일의 3.3배입니다. V8 구세대 기본 한도가 1.4~2GB이므로 이런 작업이 몇 개만 병행돼도 컨테이너는 OOM Kill을 기다리게 됩니다.
구성은 단순합니다: 원문 텍스트가 메모리에 한 부(약 186MB), parse 결과 객체 그래프가 또 한 부(문자열 키, 중첩 객체 헤더, 배열에 각각 추가 비용), 그리고 파싱 과정의 임시 할당까지 쌓여 600MB에 도달하는 것은 자연스러운 일입니다.
둘, 원인: JSON.parse는 전체 텍스트를 전체 그래프로 교환한다
JSON.parse의 계약은 "완전한 텍스트를 주면 완전한 객체 그래프를 돌려준다"입니다. 파싱 시작 전에 전체 텍스트가 준비되기를 요구하고, 파싱이 끝난 뒤에야 결과를 한꺼번에 넘겨줍니다. 중간에 "먼저 첫 1,000건만" 같은 기회는 전혀 없습니다.
객체 그래프 비용은 JSON의 메모리 계산에서 항목별로 측정했습니다: 문자열은 실제 공간을 차지하고, 객체는 키마다 슬롯을 잡으며, 배열은 요소 종류에 따라 폭이 결정됩니다. 십수 MB의 JSON이 파싱 후 3~5배가 되는 것이 상례이고 피크는 그 위에 더해집니다.
그러나 대부분의 임포트 작업에는 전체 그래프가 필요 없습니다: 한 건씩 저장하고, 한 건씩 필터링하고, 한 건씩 변환하면 처리된 레코드는 즉시 가비지 컬렉션 대상이 됩니다. 필요한 것은 "한 건 파싱하면 한 건 넘겨준다"는 능력 — 바로 스트리밍 파싱의 정의입니다.
셋, 해법: 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, 같은 48만 건에서 이 방식의 피크 RSS는 104MB로 전 구간 일정했습니다. 메모리에는 "현재 요소 + 파서 상태"만 존재하고, 처리가 끝난 요소는 즉시 회수됩니다.
놓치기 쉬운 세부 사항: for await는 saveToDb가 완료되기 전에는 파서에서 다음 레코드를 끌어오지 않으므로, 파서는 파일 읽기를 중단합니다. DB가 느릴수록 읽기도 느려집니다 — 이것이 배압이며, 추가 코드 없이 자연스럽게 형성됩니다. dev.to의 4GB 시정 교통 로그 수집 사례도 같은 체인을 쓰며, pick({filter:'data'})를 추가해도 메모리 곡선은 마찬가지로 평평했습니다.
넷, 쓰기 측 실패: 일시정지하지 않는 data 이벤트가 메모리를 되밀어 올린다
스트리밍 파싱은 읽기 측만 다스립니다. 쓰기 측이 배압을 받아주지 않으면 메모리는 다시 올라갑니다. 가장 전형적인 실패 패턴은 data 이벤트 안에서 비동기 쓰기를 하면서 쓰기 버퍼를 무시하는 것입니다:
// 잘못됨: data 이벤트 + 비동기 쓰기, 배압 완전 상실
readable.on('data', async (chunk) => {
await slowWrite(chunk); // 스트림은 기다리지 않고 버퍼는 계속 부풀어 오른다
});
data 모드에서는 스트림이 계속 흐르므로 slowWrite가 아무리 느려도 상류는 멈추지 않고, 밀린 데이터가 모두 쓰기 버퍼에 쌓입니다. 같은 186MB 샘플로 100번째 청크마다 1ms 지연되는 느린 Writable에 연결해 비교한 결과, 배압을 무시한 방식은 피크 RSS 407MB, write()가 false를 반환할 때 await once(sink, 'drain')으로 일시정지한 방식은 161MB였습니다 — 차이인 246MB는 말 그대로 쓰기 버퍼에 쌓인 데이터입니다.
// 올바름: write()가 false를 반환하면 일시정지, drain 후 재개
for await (const { value } of pipeline) {
if (!sink.write(value)) {
await once(sink, 'drain');
}
}
두 가지 추가 경험: 스트림 체인을 수동으로 조립할 때는 각 스트림에 highWaterMark를 명시적으로 설정하세요(objectMode 기본값 16은 큰 객체에는 과합니다). 그리고 pipe() 대신 pipeline()(stream/promises)을 우선 사용하면 오류 전파와 정리를 맡길 수 있습니다.
다섯, 실측 비교: 네 가지 방식의 피크 메모리
| 방식 | 샘플 | 피크 RSS | 소요 시간 | 적용 |
|---|---|---|---|---|
| readFileSync + JSON.parse | 186MB / 48만 건 | 612MB | 1.3s | 작은 파일, 랜덤 액세스 |
| streamArray + for await + 느린 DB 쓰기(건당 0.5ms) | 동일 | 104MB(일정) | DB 속도에 따름 | 건별 적재·변환 |
| streamArray + data 이벤트 쓰기, 배압 없음 | 동일 | 407MB | 약 10s | 반면교사 |
| streamArray + write()/drain 배압 | 동일 | 161MB | 약 10s | 결과 저장/전송 |
환경: Node 22.13, /usr/bin/time -v로 Maximum resident set size 측정. 샘플은 합성 데이터이며 단일 실행 값입니다. 수치는 이 샘플에서의 자릿수 결론일 뿐 보편 상수가 아닙니다.
주목할 두 가지 수치: 첫 번째와 두 번째의 차이는 6배의 메모리이고, 대가는 "1.3초"가 "DB 속도를 따름"으로 바뀌는 것입니다. 세 번째와 네 번째의 차이는 2.5배로, 읽기 측만 스트리밍하고 쓰기 측 배압을 소홀히 하면 절반만 해결된다는 뜻입니다.
여섯, 진단: 배압이 실제로 작동하는지 확인하기
운영 환경의 메모리 문제는 감으로 해결할 수 없습니다. Tencent Cloud의 배압 진단 글이 실용적인 절차를 제시합니다:
- 핵심 스트림에 임시로
'pause'와'resume'로그를 겁니다. 대용량 링크에서 pause가 한 번도 나오지 않는다면 어딘가 데이터를 메모리에 쌓고 있다고 단정할 수 있습니다; writable.writableLength(쓰기 버퍼 바이트 수)를 확인합니다. 계속 증가한다면 소화되지 않는 것입니다;process.memoryUsage()로 RSS를 주기 샘플링해 곡선을 그리고, "상승형"(축적)과 "톱니형 안정"(정상 회수)을 구분합니다.
for await에서는 pause와 resume 로그가 반드시 교차로 나타납니다. 전혀 나오지 않는다면 data 리스너 혼입이나 await 누락을 의심하세요.
일곱, 스트리밍이 필요 없는 때
스트리밍이 기본 답은 아닙니다. 수십 MB 이내에서 키 기반 랜덤 액세스가 필요하면 JSON.parse 한 번이 오히려 간편합니다. 브라우저에서 큰 파일을 여는 것은 별개의 문제 영역이며, 큰 JSON 파일 여는 법에서 뷰어 선택 사다리를 다룹니다. 스트리밍 파싱의 적용 경계는 명확합니다:
- 최상위가 배열(또는 JSONL로 행 분할 가능)이고 소비가 순차 처리이며 앞 내용을 다시 참조할 필요가 없음;
- 파일 크기가 통제 불가이거나 힙 여유를 크게 초과하여, 한 번의 임포트로 메모리를 두 배로 만들 수 없음;
- 소비자에게 자연스러운 속도 차(DB 쓰기, 하위 API 호출)가 있어 전속력 주입이 아닌 배압이 필요.
최상위 구조가 불규칙하면 먼저 JSON 파싱·포맷팅 도구에서 구조를 확인한 뒤 읽는 방식을 고르세요. 명령줄 처리 경로는 jq로 큰 JSON 다루기에서, jq --stream과 streamArray는 같은 발상의 서로 다른 런타임 구현입니다.
자주 묻는 질문
stream-json은 JSON.parse보다 얼마나 느린가요?
순수 파싱 속도는 JSON.parse가 빠릅니다: 186MB 샘플 기준 1.3초 대비, 쓰기 지연 없는 streamArray는 약 7초(토큰 파싱 + 레코드별 객체 구축 비용). 스트리밍의 이득은 전부 메모리 측에 있습니다: 피크가 612MB에서 104MB로. 임포트 작업의 병목은 어차피 DB 쓰기이므로 몇 초의 파싱 비용으로 6배의 메모리 여유를 사는 것이 보통은 합리적인 거래입니다. 밀리초급 API 응답 안에서는 부적합합니다.
for await의 배압과 수동 pause/resume은 같은 것인가요?
의미상 동등합니다: for await는 루프 본문이 미완료인 동안 읽기 스트림을 자동 일시정지하며, 이는 write()가 false를 반환할 때 pause()를, drain에서 resume()를 호출하는 것과 같습니다. 차이는 언어 메커니즘에 위임되어 누락되지 않는 점이고, 수동 구현은 한 곳만 놓쳐도 체인 전체의 배압이 끊깁니다.
최상위가 배열이 아니라 하나의 거대한 객체라면?
stream-json은 streamObject()(키별 발행)와 Pick 필터(지정된 하위 트리만 파싱)를 제공합니다. 몇 개 필드만 필요하다면 Pick과 JSONPath로 전체 객체 그래프를 필요한 하위 그래프로 줄일 수 있습니다. 다중 문서 혼합(JSON Lines, JSON Seq)은 먼저 행으로 분할해 행 단위 독립 JSON으로 처리하는 것을 권합니다.
결과를 JSONL로 기록하거나 하류로 전달하려면?
쓰기 측도 같은 배압 문제입니다: fs.createWriteStream이나 http.request는 write() 반환값을 확인하고 false이면 await once(stream, 'drain')을 기다리거나, 쓰기 스트림을 pipeline()에 연결해 Node에 관리시킵니다. 검증은 실행 후 RSS 곡선이 안정적인지, writableLength가 지속 증가하지 않는지 확인하는 것으로 충분합니다.
임포트 작업에 빠르게 메모리 모니터링을 추가하려면?
최소 구성은 100ms마다 process.memoryUsage().rss를 배열에 수집하고 종료 시 최댓값 출력입니다. 더 정확하게는 /usr/bin/time -v node task.js로 Maximum resident set size를 직접 확인하세요. 컨테이너에서는 경고선을 메모리 한도의 70%로 설정해 GC 여유를 남겨둡니다.