외부 API 지연이 전체 파이프라인을 차단할 때: 격리와 병렬 처리의 판단

서론

대용량 데이터를 외부 API와 연동해 적재할 때, 흔히 마주하는 딜레마가 있다. 외부 서비스의 응답 지연이나 쿼트 한도 초과가 전체 데이터 파이프라인의 실패로 직결되는 구조다. 특히 주소 정제(Geocoding)처럼 외부 의존성이 크고 호출 비용이 높은 작업은, 배치 처리와 실시간 조회가 공유 리소스를 쓰면 한쪽의 실패가 다른 쪽의 지연을 유발한다. 우리 솔루션의 업체 온보딩 파이프라인에서도 이 문제가 명확히 드러났다. 외부 주소 보정 API의 불안정성이 신규 업체 등록 지연과 대량 데이터 이관 실패의 공통 원인이 되었다.

한 줄 요약: 외부 API 의존성을 가진 대용량 데이터 이관 시, 배치 적재와 실시간 지오코딩을 물리적으로 분리하고 병렬 처리를 도입해 장애 반경을 격리했다.

제약

결정을 내리기 전, 시스템이 반드시 지켜야 할 경계 조건은 다음과 같다.

• 외부 API 한도 관리: 무료 플랜의 일일 호출 한도(200건/키)를 여러 키로 확장하더라도, 키 관리의 복잡도를 최소화해야 한다.
• 배치 가용성: 개발·테스트 환경에서 대량 배치가 자동으로 실행되어 리소스를 낭비하거나, 프로덕션에 영향을 주지 않도록 해야 한다.
• 데이터 일관성: 외부 API 호출 실패 시, 원본 데이터의 적재 자체가 중단되지 않아야 한다. 실패는 격리되어야 한다.
• 멱등성: 재실행 가능한 배치 작업이므로, 동일한 데이터가 중복 적재되거나 상태가 깨지지 않아야 한다.

선택지

외부 API 지연과 실패를 다루기 위해 고려한 주요 대안들은 다음과 같다.

1. 단일 배치 내 병렬 호출 배치 처리 단계에서 외부 API를 병렬로 호출한다.

• 장점: 구현이 비교적 단순하고, 데이터 적재와 정제가 동시에 완료된다.
• 단점: 외부 API의 응답 지연이 배치 전체의 실행 시간을 결정한다. 한도 초과 시 전체 배치가 실패할 위험이 크다.

2. 배치 적재와 지오코딩의 완전한 분리 배치 단계에서는 원본 데이터만 적재하고, 지오코딩은 별도 트리거(실시간 또는 별도 배치)로 처리한다.

• 장점: 외부 API 장애가 배치 적재에 영향을 주지 않는다. 장애 반경이 명확히 분리된다.
• 단점: 데이터 정제 상태가 불일치할 수 있는 시간이 발생한다. 구현 구조가 복잡해진다.

3. 키 풀링과 폴백 메커니즘 여러 API 키를 관리하고, 한도 초과 시 다음 키로 자동으로 전환한다.

• 장점: 단일 키의 한도 문제를 우회할 수 있다.
• 단점: 키 관리 인프라가 필요하다. 단순한 환경에서는 오히려 운영 부담만 증가한다.

기준	단일 배치 내 병렬	배치/지오코딩 분리	키 풀링
장애 격리	낮음	높음	중간
구현 복잡도	낮음	높음	중간
운영 부담	낮음	낮음	높음

결정

우리는 배치 적재와 지오코딩을 분리하는 방향을 선택했다. 구체적으로 다음과 같은 판단을 내렸다.

첫째, 배치 적재 단계에서는 외부 API 호출을 완전히 제거한다. 원본 데이터(업체 정보)를 우선적으로 적재하고, 지오코딩은 온보딩 트리거나 별도 수동 실행 경로로 맡겼다. 이는 대량 데이터 이관 시 외부 API의 응답 시간이 전체 파이프라인의 병목이 되는 것을 방지하기 위한 의도적 결정이다. 대량 이관 파이프라인에서는 INSERT IGNORE를 통한 중복 제거와 청크 기반 병렬 처리를 채택해, 단일 레코드 실패가 전체 배치의 롤백을 유발하지 않도록 했다.

둘째, 키 관리는 하드코딩 대신 데이터베이스 테이블로 분리했다. 키 추가 시 재배포 없이 설정만으로 확장할 수 있게 함으로써, 배포 리스크를 최소화했다. 이는 작은 팀이 외부 의존성을 관리할 때 필요한 최소한의 유연성이다.

셋째, 개발 환경에서의 자동 실행을 차단했다. 배치 활성화 스위치를 기본 false로 설정해, 실수로 대량 배치가 실행되는 것을 방지했다. 지오코딩 트리거의 프로파일 제한도 제거했지만, 이는 수동 엔드포인트를 통해서만 실행되도록 설계되어 있어 자동 실행의 위험은 없었다.

핵심 판단은 **"외부 API의 불안정성을 배치의 신뢰성보다 낮게 평가했다"**는 점이다. 만약 외부 API가 항상 안정적이었다면 단일 배치 내 병렬 호출이 더 나았을 것이다. 하지만 실제 운영 신호는 그렇지 않았다.

결과와 한계

얻은 것

• 외부 API 지연이 신규 업체 등록 흐름을 차단하지 않게 되었다.
• 대량 데이터 이관 시, 지오코딩 실패가 원본 데이터 적재를 중단시키지 않게 되었다.
• 키 관리의 유연성이 확보되어, 한도 문제 대응이 배포 없이 가능해졌다.

잃은 것

• 데이터 정제 상태의 실시간 일관성을 포기했다. 적재 직후 조회 시 주소 정보가 비어 있을 수 있다.
• 구현 구조가 복잡해졌다. 배치와 실시간 경로가 각각 지오코딩을 처리하므로, 로직 중복 관리가 필요해졌다.

되돌릴 조건

• 외부 API의 안정성이 지속적으로 99.9% 이상 유지되고, 한도 문제가 완전히 해소될 경우, 분리를 다시 통합할 수 있다.

다른 시스템에 적용할 때

외부 의존성이 높은 파이프라인을 설계할 때는, '완전한 일관성'보다 '격리된 실패'를 우선 고려하라. 특히 배치 처리에서는 원본 데이터 적재를 최우선으로 두고, 정제 작업은 비동기적으로 처리하는 패턴이 장애 반경을 줄이는 데 효과적이다. 또한, 외부 키나 설정은 코드에 하드코딩하지 말고 데이터 또는 설정 서버로 분리해, 배포 없이 대응할 수 있는 유연성을 확보하라.

이 결정은 외부 API의 품질이 현재 수준으로 유지되는 한 유효하다. API 안정성이 크게 향상되면, 분리를 통합해 복잡도를 낮출 수 있다.