TypeScript 외부 API 데이터 unknown과 type guard 안전 검증

잘못된 신뢰

아래 개념 조각에서 참조하는 학습용 타입입니다. 프로젝트 파일을 import하지 않습니다. 같은 이름을 다시 선언하는 비교 코드는 별도 파일에서 확인하세요.

type Task = { id: string; title: string; completed: boolean };

const data =
  await response.json()
    as Task[];

이 코드는 runtime 검증을 하지 않습니다.

서버가 다음 값을 보내도 TypeScript는 실행 중에 막아주지 않습니다.

[
  {
    "id": 1,
    "title": null,
    "completed": "no"
  }
]

unknown으로 시작

const data:
  unknown =
  await response.json();

이제 사용 전에 검증해야 합니다.

isTask

export function isTask(
  value: unknown,
): value is Task {
  if (
    typeof value !==
      'object' ||
    value === null
  ) {
    return false;
  }


  if (
    !('id' in value) ||
    !('title' in value) ||
    !('completed' in value)
  ) {
    return false;
  }


  return (
    typeof value.id ===
      'string' &&
    typeof value.title ===
      'string' &&
    typeof value.completed ===
      'boolean'
  );
}

true를 반환하면 TypeScript는 value를 Task로 좁힙니다.

배열 검증

export function isTaskArray(
  value: unknown,
): value is Task[] {
  return (
    Array.isArray(value) &&
    value.every(isTask)
  );
}

fetch 함수

export async function fetchTasks():
  Promise<Task[]> {
  const response =
    await fetch('/api/tasks');


  if (!response.ok) {
    throw new Error(
      '요청 실패',
    );
  }


  const data:
    unknown =
    await response.json();


  if (!isTaskArray(data)) {
    throw new Error(
      '잘못된 작업 데이터',
    );
  }


  return data;
}

이제 API가 예상 구조를 반환하지 않으면 명시적으로 오류 처리할 수 있습니다.

URLSearchParams도 외부 입력

브라우저에서 const searchParams = new URLSearchParams(location.search);를 먼저 선언합니다. 아래 localStorage 조각은 브라우저 전용입니다. 서버 없이 실행하는 타입 가드 검증은 직접 확인 예제를 사용하세요.

URL parameter는 string 또는 null입니다.

const id =
  searchParams.get('id');

존재 여부와 형식 검증이 필요합니다.

localStorage도 마찬가지입니다.

const raw =
  localStorage.getItem(
    'tasks',
  );

저장된 문자열을 JSON.parse한 결과도 unknown으로 검증할 수 있습니다.

schema validation library는 언제?

실제 서비스에서 API 구조가 크고 중첩되면 직접 type guard를 모두 작성하기 어려울 수 있습니다.

그때 Zod 같은 schema validation 도구를 검토할 수 있습니다.

하지만 먼저 TypeScript 타입과 runtime validation이 다른 문제라는 원리를 이해해야 합니다.

이 과정에서는 외부 라이브러리를 추가하지 않습니다.

JSON.parse는 JSON 문법이 틀린 문자열에서 먼저 예외를 던집니다. 파싱에 성공한 값의 구조를 확인하는 type guard와는 다른 실패이므로, 실제 입력을 다룰 때는 파싱 오류와 데이터 형식 오류를 구분해 처리합니다.

원리 확인: TypeScript narrowing과 타입 가드 (2026-10-12). 아래 기대 결과와 기존 실행 기록은 구분해서 읽습니다.

학습 완료 체크리스트

타입 검사를 통과하는 코드와 올바른 외부 데이터는 같은 의미일까요? title이 숫자인 입력에서 guard가 false가 되는 이유를 설명하면 컴파일 타입과 실행 중 검증의 경계를 구분한 것입니다.