air-intl-adapter는 11개 공급사의 제각각인 오류(SOAP Fault, REST 에러 JSON, 결제 거절 코드, 타임아웃…)를 단 하나의 예외 계층으로 정규화해 Triple 예약 시스템에 일관된 응답을 돌려준다. 이 노트는 그 정규화 파이프라인 전체 — 예외 클래스 계층, ErrorMessage 코드 체계, 공급사 오류 → 공통 비즈니스 오류 매핑, REST 응답 변환(RestExceptionView), 코루틴 예외 전파, Sentry 캡처/Slack 경보 트리거 — 를 코드 라인 단위로 해부한다.
Exceptions.kt:21 의 ApiException 이 모든 비즈니스 예외의 추상 부모다. 이 시스템에는 “표준 자바 예외를 쓰지 말고 무조건 ApiException 하위로 던진다”는 암묵적 규칙이 있다.
abstract class ApiException : RuntimeException, SentryAlertHandler { val errorMessage: ErrorMessage // 비즈니스 오류 코드 (필수) val objs: Array<*> // 부가 정보(메시지/PNR/코드 등) override var capturable: Boolean = false // Sentry 전송 여부 (기본 false!) override var notifiable: Boolean = true // Sentry "notifiable" 태그 var retryable: Boolean? = null // 재시도 가능 여부 (기본 null = 미지정)}
flowchart TD
RTE["RuntimeException"]
SAH["SentryAlertHandler (interface)"]
API["ApiException (abstract)"]
RTE --> SAH
SAH --> API
API --> IAE["InternationalAdapterException<br/>범용, 가장 다용도"]
API --> MAIE["MethodArgumentInvalidException<br/>요청 파라미터 검증 실패"]
API --> CKIE["CacheKeyInvalidException<br/>캐시키 만료/무효"]
API --> SIE["StatusInvalidException<br/>상태 검증 실패, 대부분 비재시도"]
Exceptions.kt:82~115 의 4개 구현체는 사실상 코드가 동일하고 생성자 2개(vararg objs / cause + vararg objs)만 위임한다. 차이는 오직 RestExceptionHandler에서 매핑되는 HTTP status 와 의미론적 용도에 있다.
예외 클래스
HTTP Status
의미/용도
정의 위치
InternationalAdapterException
500 INTERNAL_SERVER_ERROR
범용. 공급사 오류 대부분, of(soapFault) 팩토리 보유
Exceptions.kt:82
MethodArgumentInvalidException
400 BAD_REQUEST
요청 파라미터/페이로드 검증 실패
Exceptions.kt:102
CacheKeyInvalidException
410 GONE
검색 캐시키 만료·무효 (재검색 유도)
Exceptions.kt:107
StatusInvalidException
500 INTERNAL_SERVER_ERROR
PNR/스케줄/티켓 상태가 작업 불가 상태
Exceptions.kt:112
왜 클래스 4개를 굳이 나눴나?
본문 메시지(ErrorMessage)만으로는 HTTP status를 결정할 수 없기 때문이다. 같은 TICKETING_FAILED라도 “파라미터가 틀려서(400)“인지 “공급사 장애(500)“인지 구분이 필요하다. @ControllerAdvice가 예외의 타입으로 status를 분기하므로(RestExceptionHandler.kt:17~63), 의미별로 클래스를 쪼개 둔 것이다. 신입은 새 예외를 던질 때 “이게 호출자 잘못이면 MethodArgumentInvalidException, 캐시 만료면 CacheKeyInvalidException, 상태 문제면 StatusInvalidException, 나머지는 InternationalAdapterException” 으로 고르면 된다.
1.1 생성자가 자동으로 끼워 넣는 컨텍스트 (buildObjs)
ApiException의 모든 생성자는 buildObjs(objs)(Exceptions.kt:26~39)를 거친다. 이게 중요한 디테일이다.
private fun buildObjs(objs: Array<out Any>): Set<Any> { val orderNumber = MDCHolder.OrderNumber.getOrNull()?.takeIf { it.isNotBlank() } val pnr = MDCHolder.Pnr.getOrNull()?.takeIf { it.isNotBlank() } return buildSet { if (orderNumber != null) add(orderNumber) if (pnr != null) add(pnr) addAll(objs) }}
즉 예외를 생성하는 순간 현재 요청의 주문번호(OrderNumber)와 PNR이 MDC에서 자동으로 뽑혀 예외 메시지에 합쳐진다. 그래서 ApiException의 message는 "BOOKING_FAILED:ORD-123, ABC123, code, msg" 처럼 컨텍스트가 박혀 나온다. 이 MDC 채우기는 MDCFilter(support/filter/MDCFilter.kt)가 요청 진입 시 헤더에서 putAll로 채운다 → request-flow, support-common.
함정: objs 가 Set 이라 중복/순서가 사라진다
buildObjs는 buildSet { ... }으로 모으므로 중복 문자열이 1개로 합쳐지고 순서가 비결정적이다. 같은 값(예: 두 번 넘긴 PNR)을 부가정보로 던지면 하나만 남는다. 또 RestExceptionView가 응답 message로 쓰는 건 objs 중 ResponseMessage 타입뿐(아래 4절)이라, 단순 String으로 던진 부가정보는 응답 본문에 나가지 않고 로그/Sentry에만 남는다.
2. ErrorMessage — 비즈니스 오류 코드의 단일 진실 원천
ErrorMessage.kt는 약 100개의 enum 상수로 이뤄진 단순 enum(파라미터 없음, 메서드 없음)이다. 코드(=enum.name)가 곧 응답의 code 필드가 된다.
ErrorMessage는 코드(식별자)만 담는다. 사람이 읽을 메시지는 호출자(Triple)가 코드를 보고 i18n 처리할 책임이고, HTTP status는 예외 클래스가 결정한다. 그래서 adapter는 “무엇이 실패했는가(code)“만 정확히 분류하면 되고, “어떻게 보여줄까”는 관여하지 않는다. 이 분리가 11개 공급사 응답을 통일하는 비결이다.
함정: 코드가 곧 외부 계약(contract)이다
RestExceptionView.code = exception.errorMessage.name 이므로 enum 상수 이름을 바꾸면 응답 JSON의 code가 바뀌어 Triple 쪽이 깨진다. 리네임/삭제는 절대 가벼운 작업이 아니다(사실상 API 브레이킹 체인지). 새 코드는 추가만 안전하다.
3. 공급사 오류 → 공통 비즈니스 오류 매핑 (정규화 계층)
이 시스템의 가장 중요한 책임이다. 공급사마다 오류 표현이 다르므로 정규화 전략도 3가지로 나뉜다.
3.1 전략 A — SOAP Fault → ApiException (GDS 공급사)
GDS(Amadeus/Sabre/Galileo)는 SOAP이라 응답 본문이 <soap:Fault>다. ClientSupport.handleSoapFaultException(support/web/ClientSupport.kt:62)이 이를 파싱해 예외로 변환한다.
사용 예 — AmadeusClient.kt:185throw it.handleSoapFaultException(ErrorMessage.SEARCH_FAILED). 같은 패턴이 amadeus/amadeusndc/galileo 등 10개 클라이언트에서 반복된다.
함정: SOAP fault 파싱이 실패하면 원본 예외가 그대로 새 나간다
catch (_: Exception) { this.exception } 와 마지막 ?: this.exception 때문에, errorData가 null이거나 SOAP 형식이 아니면 ErrorMessage가 안 붙은 raw 예외(예: IOException) 가 전파된다. 그러면 @ControllerAdvice의 마지막 fallback 핸들러(RestExceptionHandler.kt:65)로 떨어져 응답 code가 INTERNAL_SERVER_ERROR로만 나가고(아래 4절) 분류 정보를 잃는다. 타임아웃(OkHttpError.isTimeout, ClientSupport.kt:206)도 errorData가 없으니 이 경로로 빠진다.
3.2 전략 B — 코드 lookup 테이블 → ErrorMessage (결제 거절)
결제 거절은 공급사/PG별 코드가 수백 개라 enum 매핑 테이블로 관리한다. 대표 예 supplier/jinair/support/enums/PaymentError.kt:
enum class PaymentError(val errorMessage: ErrorMessage) { PAYMENT_084(ErrorMessage.PAYMENT_CREDIT_CARD_DENIAL), PAYMENT_097(ErrorMessage.PAYMENT_PROVIDER_REJECT), PAYMENT_AKBANK_51(ErrorMessage.PAYMENT_INSUFFICIENT_FUNDS), // ... 60여 개 ; companion object { private val lookup = entries.associateBy({ it.name }, { it.errorMessage }) fun getMessage(errorCode: String): ErrorMessage = lookup[errorCode] ?: ErrorMessage.PAYMENT_ETC // ← 미등록 코드는 PAYMENT_ETC로 흡수 }}
모든 매핑 테이블은 매칭 실패 시 PAYMENT_ETC 같은 catch-all 코드로 폴백한다. 덕분에 새 거절 코드가 와도 NPE 없이 흘러가지만, 반대로 새 코드가 조용히 *_ETC로 묻혀 분류 통계가 부정확해질 수 있다. 결제 실패 분석 시 PAYMENT_ETC 비율이 높으면 매핑 테이블 보강이 필요하다는 신호다.
3.3 전략 C — 비즈니스 검증 → 직접 throw (application 레이어)
공급사 응답은 정상이지만 우리 비즈니스 규칙상 진행 불가인 경우, 서비스가 직접 던진다.
// AmadeusCancelService.kt:108throw StatusInvalidException(ErrorMessage.CANCEL_UNABLE_BY_ALREADY_CHECK_IN).capture()// AmadeusTicketingService.kt:61throw StatusInvalidException(ErrorMessage.TICKETING_FAILED, pnr, "carrier pnr is null").capture()
.capture()가 무려 103곳에서 호출된다(grep 확인). 즉 “비즈니스 검증 실패도 Sentry로 본다”는 운영 정책이다.
4. REST 응답 변환 — RestExceptionView
interfaces/response/RestExceptionView.kt 가 예외를 외부 응답 DTO로 바꾼다. 이게 Triple이 실제로 받는 JSON이다.
data class RestExceptionView(val code: String, val message: String? = null) { companion object { fun of(exception: Exception): RestExceptionView = when (exception) { is ApiException -> { val responseMessage = exception.objs.firstNotNullOfOrNull { it as? ResponseMessage } RestExceptionView( code = exception.errorMessage.name, // ← enum 이름이 code message = responseMessage?.message.orEmpty() // ← ResponseMessage만 노출 ) } else -> RestExceptionView(code = HttpStatus.INTERNAL_SERVER_ERROR.name) // 비-ApiException } }}
입력 예외
응답 code
응답 message
ApiException 하위
errorMessage.name (예: BOOKING_FAILED)
objs 중 ResponseMessage의 message, 없으면 ""
그 외 모든 예외
"INTERNAL_SERVER_ERROR"
(필드 없음/기본)
message에 내용을 담으려면 반드시 ResponseMessage로 감싸 던져라
RestExceptionView는 objs 배열에서 ResponseMessage 타입만 message로 꺼낸다(firstNotNullOfOrNull { it as? ResponseMessage }). 그냥 String으로 던진 부가정보("carrier pnr is null" 등)는 응답에 안 나가고 로그/Sentry에만 남는다. 외부에 메시지를 보여주려면:
throw InternationalAdapterException(ErrorMessage.PNR_CHECK_FAILED, ResponseMessage(it))// SabreClient.kt:743 실제 사용 예
5. 전역 예외 핸들러 — RestExceptionHandler (@ControllerAdvice)
중앙 디스패처가 없는 이 시스템에서, 모든 컨트롤러의 예외는 단 하나의 @ControllerAdvice로 수렴한다(RestExceptionHandler.kt:14, ResponseEntityExceptionHandler 상속). 5개의 @ExceptionHandler가 예외 타입별로 HTTP status를 분기한다.
fun Throwable.findRootCause(): Throwable { var rootCause = this while (rootCause.cause != null && rootCause.cause != rootCause) rootCause = rootCause.cause!! return rootCause}
래핑된 예외 체인을 끝까지 따라가 가장 안쪽 원인을 로그/Sentry 대상으로 삼는다. rootCause.cause != rootCause 가드로 자기참조(무한루프)도 방어한다.
함정: findRootCause() 가 ApiException 분류를 통째로 버릴 수 있다
로그·Sentry에 보내는 건 root cause다. 만약 InternationalAdapterException(ErrorMessage.BOOKING_FAILED, cause = ioException) 처럼 cause를 끼워 던지면, findRootCause()는 안쪽 ioException을 꺼낸다. 그런데 ioException은 SentryAlertHandler가 아니므로(sentryLog()의 if (this is SentryAlertHandler && capturable.not()) 체크에 안 걸림) 무조건 Sentry로 전송된다. 즉 cause를 단 예외는 .capture()를 안 해도 Sentry로 새 나갈 수 있고, 반대로 BOOKING_FAILED라는 분류 정보는 Sentry 이벤트에서 사라진다. cause 래핑 시 의도와 다르게 동작할 수 있으니 주의.
또한 응답 변환(RestExceptionView.of)에는 root cause가 아니라 원본 e 를 넘기므로(같은 라인 exception = e), 응답 code는 정상적으로 BOOKING_FAILED로 나간다 — 로그/Sentry와 응답이 서로 다른 예외를 본다는 점이 헷갈리는 지점이다.
5.2 sentryLog() — 조건부 Sentry 캡처가 진짜 경보 트리거
fun <T : Throwable> T.sentryLog(): T { if (this is SentryAlertHandler && this.capturable.not()) return this // ★ capturable=false면 스킵 Sentry.configureScope { scope -> MDCHolder.contextMap().forEach { (key, value) -> ... scope.setContexts/setTag ... } // MDC 전체 첨부 if (this is SentryAlertHandler) scope.setTag("notifiable", this.notifiable.toString()) } Sentry.captureException(this) return this}
이 메서드가 이 시스템의 “치명 오류 경보” 1차 트리거다(메시지큐가 아니라 Sentry). 동작 규칙:
예외 종류
capturable
Sentry 전송?
ApiException + .capture() 호출함
true
전송 ✅
ApiException (.capture() 안 함)
false(기본)
스킵 ⛔
SentryAlertHandler가 아닌 일반 예외 (IOException 등)
(해당 없음)
무조건 전송 ✅
.capture() 를 호출해야 비로소 Sentry에 잡힌다
ApiException의 capturable 기본값은 false(Exceptions.kt:67). 따라서 ApiException을 던지되 .capture()를 빼먹으면 Sentry에 안 잡힌다(의도적 “예상된 비즈니스 실패”는 이렇게 조용히 처리). 반대로 raw 예외는 위 표대로 무조건 잡히므로, 정규화를 못 하면(3.1 함정) Sentry 노이즈가 증가한다.
notifiable 태그는 .capture(silence = true)(Exceptions.kt:11~15)로 끌 수 있고, jejuair/jinair에서 “Sentry에는 남기되 알림은 끄는” 용도로 쓴다(JejuairClient.kt:389,395, JinairClient.kt:494 등). Sentry 측 알림 규칙이 이 태그를 보고 PagerDuty/Slack 발송 여부를 가린다.
5.3 Slack 경보는 별개 — 자동이 아니라 서비스가 수동 호출
흔한 오해: "치명 오류면 자동으로 Slack이 간다" — 아니다
RestExceptionHandler/AdapterCoroutineExceptionHandler는 Slack을 전혀 호출하지 않는다. 자동 경보 채널은 Sentry뿐이다. Slack 경보(application/SlackService.kt)는 운영상 수동 개입이 필요한 특정 비즈니스 실패 지점에서 서비스 코드가 직접 호출한다. 예: AmadeusCancelService.pnrCancelRepeat(AmadeusCancelService.kt:237~260)는 취소를 2회 재시도하고 마지막에 실패하면 slackService.sendCancelFail(...)을 부른 뒤 예외를 다시 throw한다. 즉 Slack은 “사람이 수동 취소/환불/발권해야 함”을 알리는 운영 알림이고, Sentry는 “개발자가 봐야 할 에러”다. 두 채널은 독립적이며 한 실패가 양쪽 모두에 갈 수도, 한쪽만 갈 수도 있다.
Slack 메시지에는 항상 MDCHolder.DatadogTraceId, 채널/경로, 공급사, PNR이 박힌다(SlackService.kt 전반) → 운영자가 Datadog 추적으로 바로 연결 가능. getSlackEmergencyChannelProperties()(긴급) vs getSlackOperationChannelProperties()(운영) 두 채널로 심각도를 가른다. 설정은 application.yml:73 slack.channels.{emergency|operation}. 자세한 인프라 연결은 configuration-and-infra.
6. 재시도 표시와 예외 — retryable / .retry() / .noRetry()
예외 객체가 “이건 재시도해도 된다/안 된다”는 메타데이터를 들고 다니는 점이 독특하다.
var retryable: Boolean? = null // Exceptions.kt:69, 기본 null = "미지정"fun <T : ApiException> T.retry(): T { this.retryable = true; return this } // Exceptions.kt:72fun <T : ApiException> T.noRetry(): T { this.retryable = false; return this } // Exceptions.kt:77
이 플래그는 Spring Retry(@EnableRetry — AirIntlAdapterApplication.kt:9)의 @Retryable(exceptionExpression = "...") SpEL이 소비한다. 각 클라이언트/서비스가 shouldXxxRetryable(#root) 술어를 갖는다:
즉 .retry()/.noRetry()를 명시하지 않은 예외가 amadeusndc/sabre의 retrieve에 닿으면 재시도되고, amadeus/jeju/jin/tway에서는 재시도 안 된다. 새 예외를 던질 때 의도하지 않은 재시도(부작용: 중복 예약/세션 꼬임)를 피하려면 명시적으로 .noRetry()를 붙이는 습관이 안전하다. 특히 비-ApiException(raw IOException 등)은 as? 캐스팅이 null이 되어 위 기본값을 따른다 → 타임아웃이 sabre/amadeusndc에서 자동 재시도된다는 뜻.
추가 패턴: @Recover 없음 + 수동 retry 루프
코드 전체에 Spring Retry @Recover 메서드가 하나도 없다(grep 확인). 따라서 @Retryable 재시도가 소진되면 마지막 예외가 그대로 위로 전파돼 @ControllerAdvice까지 간다. 한편 일부 서비스는 @Retryable 대신 for (count in 1..N)수동 루프로 재시도하며 마지막에 Slack 경보 후 rethrow한다(AmadeusCancelService.pnrCancelRepeat:237, voidRepeat:262). 이 루프 안에서 ALREADY_CANCELED_PNR/NOT_FOUND_TICKET 같은 “이미 목적 달성된” 코드는 break로 성공 취급한다(멱등성 처리). 재시도 메커니즘 전반은 resilience-and-events 참조.
7. 코루틴 예외 전파 — AdapterCoroutineExceptionHandler
코루틴(검색 fan-out 등)은 일반 try/catch 스택을 안 타므로 별도 처리가 필요하다. AdapterCoroutineExceptionHandler(AdapterCoroutineExceptionHandler.kt:10)가 코루틴의 미처리(uncaught) 예외를 받아 RestExceptionHandler의 로그/Sentry 로직으로 위임한다.
MDCContext()가 함께 붙어 부모 스레드의 MDC(주문번호/PNR/TraceId)가 코루틴으로 전파되므로, 코루틴 안에서 던진 예외도 1.1절의 컨텍스트 첨부와 5.2절의 Sentry MDC 태깅이 정상 동작한다.
함정: withAsync 에는 ExceptionHandler가 없다 (의도된 설계)
withBlocking/withLaunch에는 AdapterCoroutineExceptionHandler가 붙지만 withAsync(CoroutineExtensions.kt:28)에는 안 붙는다.CoroutineExceptionHandler는 “최상위에서 잡히지 않은” 예외에만 동작하는데, async의 예외는 Deferred.await() 호출 시점에 던져지는(rethrow되는) 모델이라 핸들러가 작동하지 않기 때문이다. 그래서 async로 흩뿌린 작업의 예외는 호출부에서 직접 모아야 한다 — 이게 pmap(CoroutineExtensions.kt:36~50)의 존재 이유다.
각 코루틴이 try/catch로 예외를 AsyncFail에 담아 삼키고(throw 대신 값으로 반환), 호출부가 AsyncResults.getOrThrow()(첫 예외 throw) 또는 getOrEmpty()(성공만)/ onFailure(예외 콜백)로 정책을 고른다. SupervisorJob()을 쓰는 이유도 한 자식 실패가 형제 코루틴을 취소하지 않게 하기 위함이다(병렬 검색에서 한 공급사 실패가 다른 공급사를 죽이면 안 됨). 코루틴 전반은 async-coroutines.
8. 신입 체크리스트 — 새 예외를 던질 때
올바른 throw 레시피
타입 선택: 호출자 잘못이면 MethodArgumentInvalidException(400), 캐시 만료면 CacheKeyInvalidException(410), 상태 문제면 StatusInvalidException, 나머지는 InternationalAdapterException(500).
코드 선택: 의미에 맞는 기존 ErrorMessage를 재사용. 없으면 enum 추가만(기존 리네임 금지 — 4.2 함정).
외부 메시지가 필요하면ResponseMessage("...")로 감싸 objs에 넣는다(5절). 단순 String은 응답에 안 나간다.