TypeScript discriminated unions와 type guards로 동적 API 응답의 타입 안전성을 보장하는 방법

Context

API 응답은 단일 엔드포인트에서도 status 필드 값에 따라 구조가 완전히 달라질 수 있다. 이 heterogeneity를 처리하지 못하면 런타임 에러가 발생한다. 기존 방식은 typeof나 수동 타입 단언을 사용하므로 안전성이 낮았다.

Technical Solution

• UserData, SuccessApiResponse, ErrorApiResponse 인터페이스를 각각 정의한다
• 각 응답 타입에 리터럴 문자열 status 필드('success', 'error')를 discriminant으로 추가한다
• ApiResponse = SuccessApiResponse | ErrorApiResponse 형태로 union 타입을 구성한다
• if (response.status === 'success') 조건문으로 type guard를 구현한다
• switch문과 default case에 never 타입 체크를 추가하여 exhaustive validation을 수행한다

Impact

단일 응답뿐 아니라 ApiResponse[] 컬렉션에서도 각 요소별 정확한 타입 접근이 가능하다.

Key Takeaway

Discriminated union은 리터럴 속성을 discriminant으로 활용하여 TypeScript의 정적 분석을 통해 정확한 type narrowing을 가능하게 한다.