TypeScript 빌드는 성공인데 런타임 타입이 다를 때

TypeScript로 개발할 때 가장 답답한 상황은 빌드는 성공하는데 런타임에서 타입이 맞지 않아 에러가 날 때다. 이는 보통 외부 API 응답, 데이터베이스 쿼리 결과, 혹은 환경에 따라 달라지는 데이터에서 비롯된다.

타입 정의와 실제 데이터 비교하기

먼저 타입 정의가 정확한지 실제 데이터로 검증해야 한다.

npm run build
npx tsc --noEmit

타입 체크 결과를 보고, 실제 런타임에 받는 데이터를 로깅해서 타입 정의와 비교하자. optional(?) 표시가 빠졌거나, null 체크가 부족한 부분을 찾을 수 있다.

타입 가드 추가하기

외부 데이터를 받을 때는 타입 가드 함수를 작성해서 유효성을 먼저 검사하자.

function isValidUser(data: unknown): data is User {
  return (
    typeof data === 'object' &&
    data !== null &&
    'id' in data &&
    typeof (data as any).id === 'string'
  );
}

이렇게 검증하면 타입스크립트도 안심하고, 런타임에서도 예기치 않은 데이터를 미리 걸러낼 수 있다.

환경별 타입 차이 추적하기

로컬과 배포 환경에서 같은 API를 호출할 때 응답 구조가 다를 수 있다. 환경 변수에 따라 달라지는 데이터 필드가 있는지 확인해보자.

검증 체크리스트

1. 타입 정의 재검토 — optional과 null 처리가 정확한가
2. 실제 응답 데이터 로깅 — 예상과 다른 필드나 값이 있는가
3. 타입 가드 함수 추가 — 외부 데이터 입력점마다 검증하는가
4. 환경별 데이터 확인 — 로컬, 스테이징, 프로덕션에서 데이터가 같은가
5. 빌드 후 재검증 — 타입 에러 없이 빌드되고, 런타임도 정상인가

TypeScript는 컴파일 타임에만 타입을 보장하므로, 런타임 데이터는 개발자가 검증해야 한다.