시각적 워크플로우에서 서드파티 API를 위한 서킷 브레이커 패턴

서드파티 API 장애가 하나의 기능보다 더 많은 것을 망가뜨리는 이유

하나의 서드파티 API는 결제 처리, 주소 확인, 재고 동기화, 메시지 전송, 신원 확인 등 일상 업무의 중심에 있는 경우가 많습니다. 공급업체에 문제가 생기면 보통 버튼 하나만 망가지지 않습니다. 워크플로우 전체가 응답을 기다리다 멈출 수 있습니다.

그래서 서킷 브레이커가 필요합니다. 이건 이론이 아니라 통합이 불안정할 때 핵심 운영을 계속 유지하는 현실적인 방법입니다.

느림과 다운은 영향을 다르게 줍니다.

API가 느릴 때 워크플로우는 여전히 성공하려 하지만 각 단계가 기다립니다. 사용자는 로딩 중인 화면을 보고, 지원팀에는 "멈췄다"는 티켓이 쌓이고, 백그라운드 작업도 밀립니다. 느림은 내부 시스템 자체의 문제처럼 보일 수 있어 판단이 어렵습니다.

API가 다운이면 타임아웃이나 오류가 발생합니다. 이건 더 명확하지만 더 위험할 수 있습니다. 많은 시스템이 재시도하기 때문에 한꺼번에 많은 요청이 재시도되면 트래픽 폭풍이 생겨 복구를 어렵게 하고 자체 시스템까지 끌어내릴 수 있습니다.

공통 증상은 빠르게 나타납니다: 타임아웃, 계속 증가하는 큐, 부분적 업데이트, 많은 수동 정리 작업 등입니다.

실제 피해는 연쇄 반응에서 옵니다. 배송 요금 제공자가 느려지면 견적 없이는 주문 확정을 거부하는 워크플로우 때문에 주문 생성이 느려집니다. 결제가 다운되면 지원팀이 환불을 발급하지 못해 다른 모든 것이 정상이어도 작업이 막힐 수 있습니다.

장애를 무시할 수는 없습니다. 목표는 워크플로우를 명확한 폴백 경로, 일시적 차단 규칙, 그리고 알림으로 설계해 통합이 복구되는 동안에도 비즈니스가 주문을 받고 고객을 응대하며 작업을 기록할 수 있게 하는 것입니다.

서킷 브레이커를 쉽게 설명하면

서킷 브레이커는 API 호출에 대한 안전 스위치입니다. 서드파티 서비스가 실패를 시작하면 브레이커는 워크플로우가 해당 서비스에 계속 요청을 쏟아붓지 못하게 멈춥니다. 하나의 장애가 느린 화면, 타임아웃, 작업 정체로 번지는 대신 영향을 제어할 수 있습니다.

서킷 브레이커의 세 가지 기본 결과는 다음과 같습니다:

• 호출 허용: 공급업체가 정상일 때 호출을 허용합니다.
• 호출 차단: 실패가 많을 때 호출을 차단하고 즉시 폴백 경로로 이동합니다.
• 제한된 테스트 호출 시도: 짧은 휴지 후에 소수의 테스트 호출로 복구 여부를 확인합니다.

원하면 레이블로는 “closed”, “open”, “half-open”이라 부릅니다. 이름이 중요한 건 아닙니다. 예측 가능성이 중요합니다. 공급업체가 문제가 생겼을 때 워크플로우는 매번 동일하게 동작해야 합니다.

이것이 오류를 숨기는 것은 아닙니다. 여전히 실패를 기록하고 사용자나 운영에 명확한 상태를 보여주며 관련자에게 알림을 보냅니다. 빠르게 실패하고 안전한 대안으로 작업을 라우팅하거나 잠시 멈춘 후 다시 검사하는 선택을 하는 것입니다.

어떤 API 호출이 비즈니스를 멈추면 안 되는지 선택하세요

서킷 브레이커는 선별적으로 적용할 때 가장 효과적입니다. 모든 공급업체 호출이 특별 보호를 필요로 하진 않습니다. 돈, 주문, 고객 접근을 멈추게 하거나 나중에 팀이 정리해야 하는 혼란을 만들 수 있는 단계부터 시작하세요.

실용적인 방법은 사용자 요청을 끝까지 따라가 보는 것입니다. 어디에서 타임아웃이 발생하면 사용자가 작업을 포기하게 되는가, 혹은 팀이 나중에 정리해야 하는 난장판이 생기는가?

일반적으로 핵심 작업을 막으면 안 되는 호출에는 결제, 배송/이행, 로그인/SSO/MFA, OTP 및 확인 메시지, 승인과 연관된 규정 준수 검사가 포함됩니다.

또한 사용자 대상 단계와 백그라운드 작업을 분리하세요. 누군가가 체크아웃 화면을 기다리고 있다면 빠른 결정(성공, 폴백, 또는 명확한 메시지로 중단)이 필요합니다. 추적 번호 동기화 같은 백그라운드 작업은 메인 흐름을 차단하지 않는 한 느린 재시도가 허용됩니다.

처음에는 범위를 작게 잡아 스코프가 커지지 않게 하세요. 먼저 1–3개의 워크플로우를 보호하고 확장하세요.

무엇이 “안전한 폴백”인지 미리 정의하세요. 좋은 폴백은 구체적이고 테스트 가능해야 합니다:

• 결제: 카트를 잃지 않도록 주문을 “결제 대기”로 저장합니다.
• 배송: 캐시된 요금, 고정 요금 사용 또는 주문을 확인하고 라벨 구매를 지연합니다.
• 신원: SSO가 다운되면 비밀번호 로그인 허용 또는 이메일 인증으로 전환합니다.
• 메시징: SMS를 나중에 전송하도록 큐에 넣고 가능하면 대체 경로를 제공합니다.

AppMaster의 Business Process Editor에서는 보통 이렇게 핵심 작업은 계속 진행되고 공급업체 의존 단계는 제어된 대안으로 분기되는 깔끔한 분기가 됩니다.

설명할 수 있는 상태, 임계값, 타이머

서킷 브레이커는 안전 스위치입니다. 대부분의 시간에는 호출을 통과시킵니다. 공급업체가 실패를 시작하면 워크플로우를 쓸모없는 대기와 오류 누적으로부터 보호하기 위해 스위치를 내립니다.

세 가지 상태

Closed는 정상입니다. API를 호출하고 계속 진행합니다.

실패가 한계선을 넘으면 브레이커는 Open이 됩니다. 짧은 기간 동안 공급업체 호출을 중단하고 즉시 폴백으로 라우팅합니다(캐시값, 큐 작업, 대체 흐름 등).

쿨다운 후 브레이커는 Half-open이 됩니다. 소수의 테스트 호출을 허용합니다. 성공하면 Closed로 돌아가고, 실패하면 다시 Open으로 돌아갑니다.

무엇을 측정할지

공급업체가 어떻게 실패하는지에 맞는 신호를 사용하세요:

• 타임아웃
• HTTP 5xx 오류
• 느려지는 지연(쓸모없을 정도로 느린 경우)
• 연결/DNS 오류
• 429 레이트 리밋

시각적 워크플로우 도구에서는 보통 상태 코드, 경과 시간, 특정 오류 출력 같은 단순 체크로 매핑됩니다.

시작 임계값과 두 가지 핵심 타이머

설명하기 쉬운 수치로 시작한 뒤 실제 트래픽에 맞춰 조정하세요. 예:

• 30–60초 내에 5–10회의 호출이 실패하면 브레이커를 엽니다.
• 또는 롤링 윈도우에서 호출의 20%–40%가 실패하면 엽니다.
• 프로세스가 허용할 수 없는 경우(종종 2–5초 이상) 지연을 실패로 처리합니다.

그다음 두 가지 타이머를 설정하세요:

• 쿨다운 시간(Open 상태): 일반적으로 30초에서 5분.
• Half-open 테스트 창: 1–5회의 테스트 호출 허용 또는 10–30초 같은 짧은 시간 창.

목표는 명확합니다: 공급업체가 불안정할 때 빠르게 실패하고, 복구되면 자동으로 회복하도록 하는 것입니다.

단계별: 시각적 워크플로우에서 서킷 브레이커 구축

가장 중요한 설계 선택은 “지금 공급업체를 호출해야 하나?”라는 결정을 한 곳에서 내리게 하는 것입니다. 모든 워크플로우에 흩어져 있으면 관리가 어렵습니다.

1) 공급업체 호출을 재사용 가능한 블록 뒤에 두세요

필요한 모든 워크플로우가 사용하는 하나의 서브프로세스(재사용 가능한 워크플로우 블록)를 만드세요. AppMaster에서는 이것이 엔드포인트나 자동화에서 호출할 수 있는 Business Process로 자연스럽게 매핑됩니다. 입력은 간단히, 공급업체 요청을 보내고 명확한 성공/실패 결과를 반환하도록 유지하세요.

2) 단순한 카운트뿐 아니라 시간으로 실패를 추적하세요

각 결과를 타임스탬프와 함께 기록하세요. 마지막 성공, 마지막 실패, 창(window) 내 실패 횟수, 현재 상태, 쿨다운 종료 시각 같은 필드를 저장합니다.

이 필드는 재시작을 견디고 여러 인스턴스 간 일관성을 유지하도록 테이블에 영속화하세요. Data Designer를 통한 PostgreSQL이 잘 맞습니다.

3) 매번 따를 상태 변경을 정의하세요

규칙을 단순하게 유지하세요. 예: 2분 내에 5번 실패하면 Open으로 전환합니다. Open 상태일 때는 쿨다운이 끝날 때까지 공급업체 호출을 건너뜁니다. 쿨다운 후 Half-open으로 가서 제한된 시도를 허용합니다. 성공하면 닫고 실패하면 다시 엽니다.

4) 워크플로우 분기: 공급업체 경로 vs 폴백 경로

공급업체 요청 전에 저장된 상태를 확인하세요:

• Closed: 공급업체를 호출한 뒤 성공 또는 실패를 업데이트합니다.
• Open: 호출을 건너뛰고 폴백을 실행합니다.
• Half-open: 제한된 시도를 허용한 뒤 닫을지 다시 열지를 결정합니다.

예: 배송 라벨 API가 다운된 경우 폴백은 체크아웃이나 창고 작업을 막지 않고 주문을 “라벨 대기” 상태로 생성하고 재시도를 큐에 넣을 수 있습니다.

5) 워크플로우 전반에서 공유하세요

여러 워크플로우와 서버가 있으면 동일한 브레이커 상태를 읽고 써야 합니다. 그렇지 않으면 한 인스턴스는 이미 중지 결정을 내렸어도 다른 인스턴스가 계속해서 공급업체를 때릴 수 있습니다.

작업을 계속하게 하는 폴백 경로들

서킷 브레이커는 호출이 차단될 때 무엇을 할지 결정해야만 도움이 됩니다. 좋은 폴백은 사용자를 계속 움직이게 하고, 데이터 무결성을 보호하며, 나중 정리가 예측 가능하게 만듭니다.

작업에 맞는 폴백을 선택하세요. 배송 요금 공급자가 다운되었다고 해서 정확한 가격이 필요하지 않을 수 있습니다. 시각적 워크플로우에서는 실패한 API 단계에서 여전히 사용 가능한 결과를 만들어내는 폴백 분기로 라우팅하세요.

실무에서는 폴백이 보통 다음 중 하나로 나타납니다:

• 마지막 알려진 값을 캐시에서 사용(명확한 신선도 기준 포함).
• 안전한 기본 추정값 사용(명확히 표기).
• 수동 검토로 라우팅.
• 작업을 재시도할 비동기 큐에 넣기.

사용자 경험은 논리만큼 중요합니다. 모호한 오류를 보여주지 마세요. 무슨 일이 일어났고 다음에 사용자가 무엇을 할 수 있는지 알려주세요: “지금 요금을 확인할 수 없습니다. 추정 배송비로 주문을 진행하거나 검토를 위해 저장할 수 있습니다.”

단기 장애와 장기 장애에 대비하세요. 짧은 장애(수분)는 “계속 진행하고 백그라운드에서 재시도”가 적절할 수 있습니다. 긴 장애(수시간)는 더 엄격한 동작(수동 검토나 승인 등)을 요구할 수 있습니다.

또한 모든 폴백을 추적해 조정이 쉽도록 하세요. 최소한 폴백 유형, 원래 요청 세부사항, 사용자에게 반환한 내용(추정인지 여부 포함), 후속 처리를 위한 상태를 기록하세요.

일시적 차단 규칙과 더 똑똑한 재시도

제어되지 않은 재시도는 작은 공급업체 헛짐을 실제 장애로 바꿉니다. 많은 워크플로우가 동시에 재시도하면 스파이크(“우르르 몰림” 문제)가 발생합니다. 공급업체가 느려지고 큐가 쌓이며 레이트 리밋을 소모합니다.

재시도는 예측 가능하고 제한적이어야 하며 브레이커 상태를 존중해야 합니다. 실용적 정책 예:

• 최대 재시도를 낮게 유지(보통 2–3회).
• 지수 백오프 사용(예: 2초, 8초, 30초).
• 재시도에 지터 추가.
• 총 재시도 시간 상한(예: 60–90초) 설정.
• 브레이커가 Open이면 재시도하지 말고 바로 폴백으로 이동.

일시적 차단은 관련되지만 별개입니다. 응답에서 “지금은 이 작업을 할 수 없다”는 신호를 받을 때 사용합니다. 일반 규칙:

• 429 레이트 리밋: Retry-After 기간(또는 안전한 고정 시간) 동안 차단.
• 401/403 인증 실패: 자격 증명이 갱신될 때까지 차단하고 한 번 테스트.
• 지속적인 5xx: 잠시 차단한 뒤 소규모 테스트 허용.

차단 중에는 이미 진행 중인 작업을 어떻게 처리할지 결정하세요: 큐에 넣을지, 재라우팅할지, 우아하게 저하할지(예: 주문은 수락하되 “SMS 전송 지연”) 등.

조치 가능한 알림

서킷 브레이커는 사람들이 빠르게 알고 무엇을 해야 할지 알 때만 도움이 됩니다. 목표는 소음이 아니라 동작을 취할 수 있는 하나의 명확한 메시지입니다: 호출이 차단되고 있는지, 폴백이 활성화되었는지, 브레이커가 예상보다 오래 열려 있는지.

좋은 기본 트리거:

• 브레이커가 열릴 때 알림.
• 일정 시간 이상 열려 있을 때 알림.
• 열리기 전이라도 오류가 급증하면 알림.

알림은 실행 가능해야 합니다. 영향을 받은 공급업체와 엔드포인트, 현재 상태와 변경 시각, 사용자가 느낄 영향, 워크플로우가 지금 무엇을 하고 있는지(차단, 재시도, 폴백), 권장 다음 단계를 포함하세요.

심각도에 따라 알림을 분류하세요. 비핵심 보강 API는 이메일로, 결제나 로그인, 주문 제출은 페이징으로 보내는 식입니다. AppMaster에서는 심각도 플래그에 따라 이메일, Telegram, SMS를 보내는 분기로 쉽게 매핑할 수 있습니다.

복구를 볼 수 있도록 작은 지표 집합을 추적하세요: 공급업체별 차단 호출 수와 폴백 사용량이 종종 충분합니다.

예시 시나리오: 주문을 멈추지 않는 공급업체 장애

흔한 실패 사례: 고객이 체크아웃하는 시점에 배송 요금 제공자가 다운됩니다. 워크플로우가 주문 생성 시 실시간 요금을 반드시 요청하도록 되어 있으면 하나의 장애로 전체 주문이 중단될 수 있습니다.

정상적인 날에는 주문이 생성되고 워크플로우가 라이브 요금을 요청한 뒤 선택된 운송사와 가격으로 주문을 저장합니다.

공급업체가 실패를 시작하면 호출이 타임아웃되거나 5xx 오류를 반환합니다. 예를 들어 2분에 5회 실패하면 브레이커가 열립니다.

Open 상태에서는 워크플로우가 짧은 창(예: 10분) 동안 배송 공급업체를 호출하는 것을 중지합니다. 이는 실패하는 공급업체가 전체 체크아웃을 끌어내리는 것을 방지합니다.

체크아웃을 막는 대신 폴백은 다음을 할 수 있습니다:

• 정액 요금(또는 안전한 추정값)을 적용.
• 주문을 그대로 생성.
• 주문을 “배송 요금 대기”로 표시해 나중에 재계산.
• 공급업체 오류 세부사항을 저장해 후속 조치.

AppMaster에서는 Business Process Editor의 명확한 분기로 구현되며 Data Designer의 shipping_rate_status 및 shipping_rate_source 같은 필드로 뒷받침됩니다.

출시 전 빠른 점검

서킷 브레이커는 스트레스 상황에서도 데모에서와 같은 방식으로 동작해야 합니다. 출시 전에 기본을 확인하세요:

• 임계값과 쿨다운이 문서화되어 있고 변경하기 쉬운가?
• Open 상태가 즉시 호출을 차단하는가(공급업체 타임아웃을 기다리지 않는가)?
• 폴백 동작이 금전 및 고객 약속에 안전한가?
• Half-open 프로빙은 소수의 테스트 호출로 제한되는가?
• 로그로 타이밍과 영향을 쉽게 답할 수 있는가?

폴백 안전성에 시간을 더 쓰세요. “작업을 계속하게 하는” 폴백은 재무적 리스크를 만들 수 있습니다. 결제 제공자가 다운되었을 때 주문을 결제 완료로 표시하는 것은 위험합니다. 더 안전한 접근은 “결제 대기”로 표시하고 고객에게 명확히 알리는 것입니다.

복구를 의도적으로 테스트하세요. 실패를 강제로 발생시켜 브레이커가 열리는 것을 보고 쿨다운을 기다린 뒤 Half-open이 소수의 프로브만 보내는지 확인하세요. 성공하면 빠르게 닫혀야 하고, 실패하면 공급업체에 플러딩 없이 다시 열려야 합니다.

로그는 1분 이내에 다음에 답할 수 있어야 합니다: 누가 영향을 받았는가, 언제 시작되었는가, 어떤 워크플로우 단계가 브레이커를 트리거했는가, 어떤 폴백이 사용되었는가.

다음 단계: AppMaster에서 패턴 구현하기

일상 운영에 피해를 줄 수 있는 통합(결제, 배송 라벨, SMS, CRM 동기화 등) 하나를 선택하세요. 먼저 그 단일 호출에 대해 브레이커를 처음부터 끝까지 구축하세요. 팀이 동작을 신뢰하면 같은 템플릿을 다음 공급업체로 반복하세요.

AppMaster에서는 Data Designer로 PostgreSQL에 브레이커 상태를 모델링하세요. 단순하게 유지하세요: 공급업체(또는 엔드포인트)별 레코드 하나에 state, failure_count, last_failure_at, open_until, 그리고 짧은 last_error 같은 필드를 두세요.

그다음 Business Process Editor에서 가독성 높은 분기로 로직을 구현하세요. 명료함이 기교보다 낫습니다.

실용적인 빌드 순서:

1. 브레이커 상태를 확인하고 open_until이 미래이면 호출을 차단.
2. 공급업체 API를 호출하고 성공 및 오류 출력을 캡처.
3. 성공 시 카운터를 리셋하고 브레이커를 닫음.
4. 실패 시 카운터를 증가시키고 임계값 도달 시 브레이커를 엶.
5. 사용자 대상 흐름은 폴백(작업 큐, 캐시 데이터 사용, 수동 처리 허용)으로 라우팅.

지원 및 운영이 무엇을 사용자에게 보여줄지 알 수 있도록 폴백 결정을 평이한 언어로 문서화하세요.

브레이커가 열리면 AppMaster 메시징 모듈(이메일, SMS, Telegram)을 사용해 소유자에게 알리세요. 중요한 내용: 공급업체, 엔드포인트, 상태, 그리고 권장 첫 조치를 포함하세요.

이 워크플로우를 AppMaster에서 빌드하는 경우, 동일한 시각적 Business Process가 엔드포인트, 백그라운드 작업, 알림을 하나의 공유 브레이커 상태로 구동할 수 있으므로 appmaster.io에서 시작하는 것이 실용적입니다.