API JSON 응답에서 TypeScript 타입 생성하기

문제 상황

복사한 API 응답은 TypeScript 선언 초안을 빠르게 만들 수 있지만 샘플 기반 추론에는 빈틈이 있습니다. 레코드 하나만으로 선택 필드를 증명할 수 없고, 빈 배열에서는 요소 타입을 알 수 없으며, null은 다른 응답에서만 나타날 수 있습니다. 긴 숫자 식별자는 이미 JavaScript의 정확한 정수 범위를 넘었을 수도 있습니다. 따라서 생성 결과는 공식 스키마나 런타임 검증기가 아니라 검토 가능한 초안입니다.

이럴 때 사용하세요

• 새 REST 엔드포인트의 JSON 응답에 맞는 클라이언트 타입 초안이 필요할 때
• Webhook 또는 외부 SDK 예시를 연동 전에 구조화해 설명해야 할 때
• 여러 픽스처 레코드를 합쳐 누락되거나 충돌하는 필드를 찾을 때
• 버그 보고서의 낯선 페이로드를 읽기 쉬운 구조로 요약해야 할 때

단계

1. 1단계

   응답에서 민감정보를 제거하고 범위를 줄입니다

   필요한 구조를 유지하는 가장 작은 대표 페이로드만 복사하세요. 액세스 토큰, 쿠키, 이메일, 계정 식별자와 무관한 레코드는 제거합니다. 배열 항목마다 필드가 다르다면 선택 여부를 확인할 수 있도록 최소 두 항목을 남깁니다.

2. 2단계

   원본을 엄격한 JSON으로 검증합니다

   추론 전에 JSON Validator 또는 JSON Formatter로 샘플을 확인하세요. 주석, 마지막 쉼표, 잘못된 이스케이프, 여러 루트, 중복 키를 명시적으로 고칩니다. 중복 키는 파서마다 남기는 값이 달라질 수 있어 모호합니다.

3. 3단계

   안정적인 루트 이름과 선언 방식을 고릅니다

   ApiResponse, OrderList, WebhookEvent처럼 도메인을 나타내는 PascalCase 이름을 사용하세요. 객체 확장이나 선언 병합이 코드베이스와 맞으면 interface를, 별칭이 팀 규칙이면 type을 고릅니다. 배열과 스칼라 루트는 타입 별칭이 필요합니다.

4. 4단계

   여러 대표 레코드에서 타입을 생성합니다

   같은 배열의 객체들이 의도적으로 누락 필드를 보여 준다면 선택 속성 추론을 켭니다. 생성기는 객체 샘플을 병합하고, TypeScript 식별자가 아닌 키를 따옴표로 보존하며, 중첩 선언을 만들고, JSON 값 종류가 다르면 유니온을 사용합니다.

5. 5단계

   모든 추론 경고를 검토합니다

   실제 요소 타입을 확인한 뒤에만 Array<unknown>을 바꾸세요. 빈 객체 선언, 혼합 배열 유니온, null 멤버, 숫자 정밀도 경고를 확인합니다. 날짜 문자열은 string이고 모든 JSON 숫자는 number이며, 샘플에 없는 변형은 발견할 수 없습니다.

6. 6단계

   대상 프로젝트에서 컴파일하고 경계를 검증합니다

   생성 파일을 프로젝트에 추가해 TypeScript 컴파일러와 린트 규칙을 실행하세요. API 문서, OpenAPI, JSON Schema 또는 GraphQL 계약과 선언을 비교합니다. 외부 응답은 생성 타입으로 단정하기 전에 런타임에서 검증합니다.

예시

{
  "users": [
    { "id": "usr_1", "name": "Ada" },
    { "id": "usr_2", "active": true }
  ]
}

export interface ApiResponse {
  users: Array<ApiResponseUsersItem>;
}

export interface ApiResponseUsersItem {
  id: string;
  name?: string;
  active?: boolean;
}

흔한 실수

자주 묻는 질문