TypeScript에서 null 처리할 때 확인해야 할 것

TypeScript에서 null이나 undefined 처리 문제가 나면, 화면만 봐서는 원인을 찾기 어렵다. 로그, 빌드 결과, 실제 API 응답을 한꺼번에 봐야 한다.

먼저 타입 정의부터 확인하기

대부분의 경우 문제는 타입 선언에서 시작한다. null일 수 있는 필드를 optional로 명시했는지, 아니면 명확하게 nullable: boolean | null 같은 형태로 선언했는지 확인해야 한다. 특히 API 응답 타입을 정의할 때 서버에서 실제로 null을 보내는지, 아니면 필드 자체를 빼는지 파악하는 게 중요하다.

로컬과 서버 환경의 차이 확인

같은 코드라도 로컬 개발 환경과 배포된 서버에서 다르게 동작할 수 있다. 로컬에서는 mocking 데이터를 쓰고 있는데 실제 서버는 다른 형태의 응답을 보낼 수 있다. 환경 변수 설정, API 엔드포인트, 인증 토큰 등을 다시 확인해보자.

npx tsc --noEmit
npm run build

타입 가드와 optional chaining 확인

TypeScript에서 null을 안전하게 다루려면 타입 가드를 제대로 써야 한다. optional chaining(?.)을 사용하고 있는지, nullish coalescing(??)을 제대로 적용했는지 살펴보자. 특히 중첩된 객체 접근에서 한 단계라도 놓치면 런타임 에러가 난다.

빌드 타임과 런타임 에러 구분하기

빌드할 때는 에러가 없는데 런타임에서 null 에러가 난다면, 그건 타입 체크를 우회한 부분이 있다는 뜻이다. as any 같은 타입 단언이나 @ts-ignore 주석을 찾아서 왜 썼는지 다시 생각해보자. 혹은 JSON 파싱 이후 타입을 다시 검증해야 할 수도 있다.

에러 메시지와 로그 읽기

TypeScript 컴파일 에러나 브라우저 콘솔 에러는 정확히 어느 줄에서 null을 만났는지 알려준다. 에러 메시지를 꼼꼼히 읽고, 해당 라인의 변수가 정말 null일 수 있는지 추적해보자. API 응답이 기대와 다르다면 개발자 도구의 Network 탭에서 실제 JSON을 확인하자.

한 번에 여러 부분을 바꾸지 말 것

타입을 수정할 때는 한 번에 한 가지씩만 변경하고, 변경 후 빌드와 테스트를 반복하자. 여러 곳을 동시에 수정하면 어느 부분이 문제를 일으켰는지 알기 어렵다. 작은 확인을 쌓아가다 보면 자연스럽게 원인이 보인다.