API 응답의 null값이 런타임 에러를 일으킨다면

프론트엔드에서 특정 필드가 항상 있다고 가정했는데, 백엔드가 가끔 null을 반환하면 앱이 먹통이 된다. 이런 미스매치를 사전에 잡는 방법을 정리했다.

실제 API 응답 확인하기

먼저 백엔드가 정말로 뭘 반환하는지 본다.

curl -i 'https://example.com/api/items?page=1'

Response body를 JSON 포맷으로 정렬해서 본다. 각 필드가 정말 있는가? null인 경우도 있는가?

TypeScript 타입 정의 점검

API 응답을 받아 정의한 타입을 본다.

interface Item {
  id: string;
  title: string;  // 이 필드가 정말 항상 존재하는가?
  description?: string;  // optional 표시를 했는가?
}

만약 백엔드가 description을 가끔 null로 준다면, 타입 정의에서 string | null이나 description?: string으로 명시해야 한다.

각 필드별로 null 가능성 확인

API 문서나 실제 응답 샘플 10-20개를 보면서, 각 필드의 null 가능성을 판단한다.

• id: 거의 항상 있음 (required)
• name: 보통 있음 (required)
• description: 가끔 없음 (optional)
• metadata: 항상 객체거나 없음 (nullable object)

클라이언트에서 방어하기

설령 백엔드 타입 정의가 잘못됐다 해도, 클라이언트에서 방어할 수 있다.

const title = item.title ?? 'Untitled';
const description = item.description || '';

Null coalescing (??)과 OR 연산자 (||)를 적절히 써서 안전하게 처리한다.

빌드할 때 타입 체크

npx tsc --noEmit

TypeScript 컴파일러가 타입 에러를 찾아낸다. CI/CD 파이프라인에 이 명령어를 포함해서, 배포 전에 타입 불일치를 막아야 한다.

실제 배포 환경과 로컬 비교

Logging이나 오류 추적 서비스로, 실제 API 응답이 로컬 개발과 다른지 확인한다.

• 개발: 완전한 응답
• 배포: 가끔 필드 누락

이런 차이가 있으면, 환경 변수나 백엔드 설정 차이를 조사해야 한다.

에러 처리 추가

런타임에 예상 밖의 null을 만났을 때를 대비하자.

if (!item.title) {
  console.error('Item title is missing:', item);
  // 에러 추적 서비스에 보고
  reportError('missing_item_title', item);
  return null;  // 또는 기본값 반환
}

상태 코드로 구분하기

HTTP 상태 코드도 중요하다.

• 200: 성공 응답 (필드 모두 있을 것 기대)
• 206: Partial content (일부 필드 누락 가능)
• 404: Not found (항상 에러 처리)
• 500: Server error (응답 신뢰 불가)

각 상태별로 다르게 처리해야 한다.