ADR-003 외부 Gateway 실패 경로 정합 = graceful degradation

• 상태: 채택
• 날짜: 2026-07-03
• 근거: TDD “실패 경로·동시성·멱등” / AS-IS 실측

맥락

전환 대상 3개 GatewayImpl의 외부 오류 처리가 불일치한다(실측).

GatewayImpl	외부 오류 시	근거
KakaoGeocodingGatewayImpl	try/catch → null (graceful)	KakaoGeocodingGatewayImpl.kt:42-45
DataGoKrPublicFacilityGatewayImpl	try/catch → emptyList() (graceful)	DataGoKrPublicFacilityGatewayImpl.kt:39-42
KmaWeatherGatewayImpl	catch 없음 → 예외 전파	KmaWeatherGatewayImpl.kt:31-46

실 API 전환 시 기상청이 5xx/timeout을 내면 weather UseCase가 예외로 깨진다. 나머지 둘은 degrade하는데 weather만 전파 — 전환 후 장애 반경이 도메인마다 다르다.

결정

KmaWeatherGatewayImpl을 facility/geocoding과 동일하게 graceful degradation으로 정합한다: RestClientException/역직렬화 실패/resultCode≠00/빈 items 시 빈 Forecast 반환 + logger.warn. connect 3s / read 5s 타임아웃(ExternalRestClientFactory)은 유지. 재시도는 추가하지 않는다(개발용 저빈도 호출, 단순함 우선).

근거

• 조회성 부가정보(날씨)의 외부 장애가 상위 유즈케이스를 깨뜨리지 않아야 한다 — 부분 실패는 빈 결과로 흡수.
• 세 gateway의 실패 정책을 통일해 전환 후 운영 예측 가능성 확보.
• 실패율·레이턴시는 logger.warn → 옵저버빌리티 대시보드(별도 과제)로 관측. 앱은 계속 동작.

대안 (미채택)

• 현행 유지(예외 전파): weather만 장애 반경이 다름. 전환 후 기상청 장애가 날씨 조회 유즈케이스를 500으로 깬다. 기각.
• 재시도 추가: 저빈도 개발 호출에 불필요한 복잡도. 대량 호출은 mock 사용이라 재시도 이득 없음. 기각.

영향

• KmaWeatherGatewayImpl에 try/catch + degrade 추가(BE-03), 동일 파일의 계약/실패 테스트로 검증.
• happy-path 동작 불변 → 하위 호환, 무중단(커밋 revert로 롤백).