본문으로 건너뛰기

ADR-004: 비동기 콜백

상황 (Context)​

Ablecity API(사주 계산)와 OpenAI API(LLM 운세) 호출은 시간이 걸린다 (각각 0.5-2초). 사용자가 "사주 등록" 버튼을 누르면 응답을 기다려야 하는 문제가 발생한다. 이 둘을 순차적으로 호출하면 더 시간이 걸린다.

의사결정 (Decision)​

Ablecity 비동기 콜백 패턴 도입

  1. 사용자가 생년월일 제출 → BFF가 즉시 응답 (사주 객체 with 로딩 상태)
  2. Ablecity에 비동기 요청 (웹훅 콜백 URL 지정)
  3. Ablecity 계산 완료 후 BFF 콜백 엔드포인트로 POST
  4. 콜백 수신 후 DB 업데이트 + LLM 호출 (비동기)
  5. 클라이언트는 폴링 또는 WebSocket으로 상태 갱신

근거 (Rationale)​

  1. 즉시 응답: 사용자는 로딩 상태를 보면서 대기 (온보딩 이탈 방지)
  2. 병렬 처리: Ablecity 계산과 LLM 호출을 분리
  3. 신뢰성: 재시도 로직으로 API 장애 대응
  4. 비용 절감: 불필요한 폴링 제거

결과 (Consequences)​

✅ 긍정​

  • 사용자 경험 향상 (빠른 응답)
  • 서버 부하 분산
  • 재시도 로직으로 안정성 향상

⚠️ 위험​

  • 콜백 URL이 외부 인터넷에 노출되어야 함 (보안 고려 필요)
  • 콜백 타이밍 제어 어려움
  • 상태 관리 복잡도 증가

구현 디테일​

1. POST /api/saju (클라이언트 요청)
   ↓ (즉시 응답: { sajuId, status: "pending" })
2. BFF → Ablecity API 비동기 호출 (webhook_url 포함)
3. BFF 환기 콜백: POST /api/internal/saju/callback?token=xxx
4. 콜백 수신 후: DB 업데이트 + LLM 호출 (비동기)
5. 클라이언트: GET /api/saju/{sajuId} 폴링 또는 WebSocket 구독

출시 전 확인사항​

  • Ablecity 콜백 웹훅 신뢰성 확인
  • 콜백 토큰 검증 로직 구현
  • 콜백 재시도 정책 (최대 3회, 지수 백오프)
  • DB 동시성 제어 (중복 업데이트 방지)
  • 콜백 타임아웃 설정 (기본 30분)

상태: ✅ 승인됨 | 최종 수정: 2026-06-25