루프 처리 — SplitInBatches와 반복 실행

🎯 학습 목표

이 강을 마치면 다음을 할 수 있습니다.

• n8n이 items 배열을 자동으로 반복 처리하는 원리를 정확히 이해합니다.
• SplitInBatches 노드로 대량 데이터를 일정 크기로 나눠 안전하게 처리합니다.
• API Rate Limit에 대응해 Wait 노드로 요청 속도를 제어합니다.
• 루프 완료 조건을 설계하고 무한 루프를 방지하는 방법을 익힙니다.

💡 n8n의 자동 반복 처리 원리

이 섹션에서는 n8n이 배열 데이터를 어떻게 자동으로 반복 처리하는지 살펴보겠습니다.

7강에서 학습한 것처럼, n8n의 모든 데이터는 items 배열로 흐릅니다. 그런데 n8n의 대부분의 노드는 이 배열을 받았을 때 아이템 하나하나에 대해 자동으로 반복 실행됩니다. 이것이 n8n의 핵심 설계 원칙입니다. 개발자가 for 루프를 명시적으로 작성하지 않아도, 노드 자체가 모든 아이템을 순회합니다.

예를 들어, 100개의 이메일 주소가 담긴 배열이 있고, 이를 Slack 노드에 연결했다면 Slack 노드는 자동으로 100번 실행되어 각 이메일 주소로 메시지를 발송합니다. 코드로 따지면 배열을 forEach로 순회하며 API를 호출하는 것과 동일하지만, n8n에서는 그냥 노드를 연결하기만 하면 됩니다.

이 자동 반복 원리는 강력하지만, 아이템 수가 많을 때는 한 가지 문제가 생깁니다. 예를 들어 10,000개의 아이템이 있고 각 아이템마다 외부 API를 호출한다면, API 서버에 10,000개의 요청이 한꺼번에 쏟아져 Rate Limit 오류가 발생할 수 있습니다. 또한 처리 중간에 오류가 발생하면 완료된 일부와 미완료 나머지를 구분하기 어렵습니다. 이 문제를 해결하는 것이 SplitInBatches 노드입니다.

🔄 SplitInBatches 노드 — 대량 데이터를 안전하게

이 섹션에서는 대량 아이템을 일정 크기로 나눠 처리하는 SplitInBatches 노드를 살펴보겠습니다.

SplitInBatches 노드는 입력 아이템 배열을 설정한 크기(batch size)만큼 나눠서 순차적으로 처리합니다. 100개를 한 번에 처리하는 대신, 10개씩 10번에 나눠 처리하는 방식입니다. 이 노드는 두 개의 출력 핀을 가집니다.

• loop 핀: 아직 처리할 배치가 남아있을 때 실행됩니다. 처리할 아이템(현재 배치)이 이 핀을 통해 다음 노드로 넘어갑니다.
• done 핀: 모든 배치 처리가 완료됐을 때 실행됩니다. 후속 작업(결과 집계, 완료 알림)을 이 핀에 연결합니다.

SplitInBatches 노드를 사용하는 기본 패턴은 다음과 같습니다. SplitInBatches 노드의 loop 핀을 처리 노드(HTTP Request, Slack 등)에 연결하고, 처리 노드의 출력을 다시 SplitInBatches 노드의 입력으로 연결합니다. 이렇게 하면 루프 구조가 형성됩니다. 처리 노드 다음에는 Wait 노드를 두어 각 배치 사이에 딜레이를 줄 수도 있습니다. 마지막으로 done 핀에 완료 처리 노드를 연결합니다.

Batch Size 설정은 상황에 따라 다릅니다. API Rate Limit이 1분에 60 요청이라면, 1분에 60개씩 처리하도록 배치 크기 60 + Wait 60초로 설정합니다. 메모리 제약이 있다면 배치 크기를 줄여 각 처리의 메모리 부담을 낮춥니다. 일반적인 시작점은 배치 크기 10~50이며, 실제 환경에서 테스트하며 조정하는 것이 좋습니다.

⏱️ Wait 노드 — API Rate Limit 대응 전략

이 섹션에서는 요청 속도를 제어하는 Wait 노드의 활용법을 살펴보겠습니다.

Wait 노드는 워크플로우 실행을 지정한 시간만큼 일시 정지합니다. SplitInBatches와 함께 사용하면 배치 간 간격을 두어 API Rate Limit을 안전하게 지킬 수 있습니다. Wait 노드는 세 가지 모드를 제공합니다.

모드	동작	사용 상황
Time Amount	지정한 시간(초·분·시간)만큼 대기	Rate Limit 대응, 배치 사이 딜레이
Specific Time	특정 날짜·시각까지 대기	예약 발송, 특정 시각에 다음 단계 실행
Webhook	외부 웹훅 호출을 받을 때까지 대기	사람의 승인을 기다리는 워크플로우

가장 많이 쓰는 Rate Limit 대응 패턴을 구체적으로 설명하겠습니다. OpenAI API는 분당 요청 수(RPM) 제한이 있습니다. 예를 들어 무료 플랜이면 분당 3회 제한이 있을 수 있습니다. 이때 SplitInBatches(크기 3) → HTTP Request(OpenAI 호출) → Wait(20초) 패턴을 사용하면, 3개 처리 → 20초 대기 → 3개 처리 → 20초 대기를 반복하며 Rate Limit을 안전하게 지킬 수 있습니다. 분당 약 9개(3 × 3회) 처리가 가능합니다.

🔁 Loop Over Items 패턴

이 섹션에서는 단순 반복이 아닌 복잡한 루프 패턴을 살펴보겠습니다.

SplitInBatches 외에도 n8n에서 루프를 구현하는 방법이 있습니다. Code 노드를 사용하면 JavaScript로 직접 배열을 순회할 수 있습니다. 이 방법은 n8n 노드 연결보다 빠르고, 복잡한 로직을 간결하게 표현할 수 있습니다. 단, 중간에 외부 API 호출이 필요한 경우에는 Code 노드 안에서 API를 호출하면 안 됩니다(n8n의 노드 기반 인증·오류 처리를 우회하게 됩니다). 이 경우에는 SplitInBatches 패턴이 더 적합합니다.

n8n 1.x 이상 버전에서는 Loop Over Items 노드가 추가됐습니다. 이 노드는 SplitInBatches보다 직관적인 루프 구성을 제공합니다. 배치 단위가 아닌 아이템 하나씩 처리할 때 사용합니다. 루프 노드를 중심으로 처리 → 루프 노드로 다시 입력 → 완료 시 done 핀 구조는 SplitInBatches와 동일합니다.

루프 설계 시 반드시 고려해야 할 것은 무한 루프 방지입니다. 루프 종료 조건이 없거나, 데이터가 계속 생성되는 경우 워크플로우가 영원히 실행됩니다. SplitInBatches는 입력 배열의 아이템이 소진되면 자동으로 done 핀으로 이동하므로 일반적으로 안전합니다. 그러나 루프 안에서 새 아이템을 생성해 다시 루프에 투입하는 구조는 무한 루프 위험이 있으므로 최대 반복 횟수를 코드로 제어해야 합니다.

⚠️ 루프 처리 시 주의점

이 섹션에서는 루프·배치 처리 시 실무에서 자주 겪는 주의사항을 살펴보겠습니다.

첫 번째 주의점은 메모리 사용량입니다. 배치 크기를 너무 크게 설정하면 한 번에 처리하는 아이템이 많아 메모리를 많이 사용합니다. 셀프호스팅 환경이면 서버의 메모리 한계를 고려해 배치 크기를 조정하십시오. 클라우드 n8n은 내부 메모리 제한이 있으므로, 초대용량(수만 건 이상) 처리는 별도의 청크 전략이 필요합니다.

두 번째 주의점은 중간 실패 복구입니다. 배치 처리 중 50번째 배치에서 오류가 나면, 1~49번째는 이미 처리된 상태입니다. 재실행하면 1번부터 다시 처리됩니다. 이를 방지하려면 각 아이템마다 처리 여부를 DB에 기록하고, 다음 실행 시 미처리 아이템만 가져오는 방식을 사용합니다. 이를 멱등성(Idempotency) 설계라고 합니다.

세 번째 주의점은 실행 시간 제한입니다. n8n 클라우드 플랜에는 워크플로우 실행 시간 제한이 있습니다. 배치 처리 + Wait 노드 조합이 너무 오래 걸리면 타임아웃이 발생합니다. 처리량이 많다면 배치를 더 작게 나누거나, 각 배치를 별도의 서브워크플로우로 분리해 실행하는 방법을 검토하십시오.

📝 핵심 요약

개념	핵심 내용
자동 반복	n8n 노드는 items 배열의 각 아이템에 자동으로 반복 실행됨
SplitInBatches	대량 데이터를 N개씩 나눠 순차 처리. loop/done 두 핀
Wait 노드	배치 사이 딜레이로 Rate Limit 대응. Time/날짜/Webhook 모드
Rate Limit 패턴	SplitInBatches(크기 N) + 처리 노드 + Wait(초) 조합
무한 루프 방지	SplitInBatches는 입력 소진 시 자동 종료. 동적 루프는 수동 제어 필요

다음 강에서는 에러 핸들링을 살펴봅니다. 워크플로우가 오류를 만났을 때 우아하게 복구하고 관리자에게 알리는 Try/Catch 패턴을 배우면, 신뢰할 수 있는 프로덕션 수준의 자동화를 구축할 수 있습니다.