TypeScript null 처리: 런타임 데이터가 타입과 다를 때

TypeScript로 타입을 엄격하게 잡아뒀는데도 런타임에서 null이나 undefined가 나오는 경우가 있다. 보통은 로컬에서는 잘 통과하는데 배포 후 에러가 생긴다.

먼저 빌드할 때의 타입 체크 결과를 본다. tsc --noEmit으로 실제 타입 문제가 있는지 확인한다.

npm run build
npx tsc --noEmit

타입 에러가 없다면 문제는 다른 곳에 있다. 실제 API 응답을 봐야 한다.

응답 구조 확인

API가 반환하는 실제 데이터 구조를 확인한다. 타입 정의와 달라질 가능성이 높다.

curl -s https://api.example.com/data | jq .

응답에 예상하지 못한 필드가 있거나, optional 필드가 누락되어 있을 수 있다.

타입 가드 추가

실제 사용하는 곳에서 타입 가드를 명시적으로 추가한다.

if (data && data.property) {
  // 안전한 접근
}

원인 체크리스트

1. 빌드 타입 체크에 에러가 있는지 확인한다.
2. 실제 API 응답과 타입 정의가 일치하는지 비교한다.
3. optional/nullable 필드 처리가 모든 곳에 일관되게 적용되는지 본다.

이 순서대로 확인하면 대부분의 null 문제는 타입 정의의 부정확함에서 나온다는 걸 알게 된다.