JSON to TypeScript — 온라인으로 인터페이스 생성

한국의 TypeScript 팀은 이 문제를 일찍 접합니다. 카카오페이, 토스, 네이버 파이낸셜 같은 대형 SDK는 타입이 지정된 클라이언트를 제공하지만, 내부 서비스와 서드파티 웹훅 페이로드는 거의 그렇지 않습니다. 일반적인 워크플로는: 네트워크 패널에서 실제 응답을 캡처하고, 여기에 붙여넣고, 엔드포인트 이름으로 루트 이름을 지정하고, 출력을 프로젝트의 types 디렉토리에 복사합니다. 그 다음 strict 모드가 문서가 언급하지 않은 불일치를 잡아냅니다. 추론기는 완전히 브라우저에서 실행되므로 스테이징 API, 서명된 웹훅 본문, 미출시 엔드포인트의 페이로드가 호스팅된 서비스에 도달하지 않습니다.

JSON to TypeScript 추론 작동 방식

추론은 파싱된 JSON 트리에 대한 단일 패스입니다. 도구는 각 값을 읽고 TypeScript 타입을 선택한 다음 찾은 각 객체에 대해 하나의 인터페이스를 작성합니다.

브라우저의 네이티브 파서로 JSON 샘플을 파싱하고 잘못된 입력을 줄/열 힌트와 함께 거부합니다.
각 값에 대한 TypeScript 타입 스니핑 — string, number, boolean, null, 배열, 또는 중첩 객체.
모든 중첩 객체에 상위 속성 키에서 파생된 인터페이스 이름 부여 (user.address는 Address 인터페이스가 됨).
각 배열의 항목 타입을 병합하여 {id: 1}과 {id: 2, label: "x"}의 목록이 올바른 옵션 필드가 있는 유니온을 생성합니다.
옵션 적용 (interface 대 type, readonly, 옵션-nullable) 및 파일이 전방 참조 없이 컴파일되도록 의존성 순서로 선언 출력.

JSON에서 TypeScript 타입을 생성하는 이유

응답 타입이 기록되어 있으면 대부분의 형태 버그를 컴파일 시점에 잡을 수 있습니다. 실제 페이로드에서 인터페이스를 추론하면 대부분을 대신 작성해주고, `strict` 모드가 문서가 언급하지 않은 필드를 잡아냅니다.
추론된 인터페이스를 Zod나 io-ts 같은 런타임 유효성 검사기와 결합하면 동일한 형태에 두 가지 역할을 부여합니다: 개발 시 편집기 자동완성과 프로덕션에서 예상치 못한 것이 전달될 때 엣지에서 400 응답.
TypeScript의 언어 서버는 알고 있는 필드만 표시합니다. 추론된 인터페이스를 가져오면 점을 입력하는 즉시 자동완성이 작동합니다 — 응답에 `as any` 캐스트하고 저장소 전체를 좌절스럽게 grep하는 일이 없어집니다.
OpenAPI 명세를 작성하려는 경우, 추론된 인터페이스는 응답 스키마의 빠른 첫 번째 초안입니다. 여전히 직접 작성한 예시와 제약 조건이 필요하지만 속성 이름과 타입은 이미 올바릅니다.

주요 활용 사례

추론은 실제 페이로드는 있지만 스키마가 없을 때 가장 유용합니다.

핸들러를 작성하기 전에 Stripe, GitHub, 또는 Twilio의 서드파티 웹훅 페이로드 타이핑.
백엔드가 착륙하는 날 프론트엔드 팀이 코딩을 시작할 수 있도록 내부 REST API에 대한 타입 부트스트래핑.
관찰된 API 응답에서 Zod, io-ts, 또는 Valibot 스키마의 시작점 생성.

출력은 어떻게 생겼나요?

샘플 JSON 문서와 루트 이름이 주어지면 생성기는 중첩 객체당 하나씩 인터페이스 트리를 생성합니다. 루트 이름 User로 아래 입력에 대해:

루트 이름 User로 {"id":1,"name":"Alice","tags":["a","b"],"address":{"city":"Paris"}}를 붙여넣으면 생성기가 다음을 생성합니다:

export interface User {
  id: number;
  name: string;
  tags: string[];
  address: Address;
}

export interface Address {
  city: string;
}

address가 자체 이름을 가진 인터페이스로 승격된 것을 주목하세요 — 이것이 의존성 순서 출력입니다. 동일한 JSON에 type 선언 스타일을 사용하면 export type User = {...}가 출력됩니다; readonly 토글을 켜면 모든 속성에 readonly 수정자가 추가됩니다.

생성기 옵션

선언 스타일

interface(객체 형태를 위한 표준 TypeScript 관용구)를 선택하거나 나중에 매핑 타입, 조건부 타입, 또는 교차 타입이 필요한 경우 type을 선택합니다. 두 가지 모두 런타임에 동일하게 동작합니다; 선택은 코딩 스타일 취향입니다.

옵션 nullable 필드

샘플 값이 null이면 필드의 타입이 T | null이 됩니다. 이 옵션을 켜면 TypeScript 측에서 필드를 옵션으로 만들기 위해 ? 수정자도 추가됩니다 — API가 때로는 null을 반환하는 대신 키를 완전히 생략할 때 유용합니다.

Readonly 수정자

모든 속성 선언 앞에 readonly를 붙여 생성된 인터페이스가 불변 데이터 모델과 일치하도록 합니다. Redux 상태 슬라이스, 동결된 API 응답, 또는 컴파일러가 우발적인 변경을 표시하도록 하는 모든 곳에 유용합니다.

중첩 객체와 배열을 지원하나요?

네. 모든 중첩 객체는 상위 속성 키에서 파생된 이름을 가진 인터페이스가 되고, 배열은 내용에서 항목 타입을 추론합니다. 객체 배열은 객체 형태당 하나의 인터페이스를 얻으며, 형태가 일치하지 않는 경우 유니온 타입이 됩니다.

옵션 필드는 어떻게 추론되나요?

"null 가능 필드를 옵션으로 표시" 토글을 켜면 샘플 값이 null인 필드에 키에 ? 수정자가 추가되고 타입에 | null이 추가됩니다. 토글 없이는 필드가 필수로 유지되고 타입은 그냥 T | null입니다.

판별 유니온을 지원하나요?

배열에 형태가 혼합된 항목이 있거나 필드에 값과 null 모두 있을 때 기본 유니온 타입이 나옵니다. 완전한 판별 유니온 추론(type이나 kind를 태그로 선택하고 변형 분리)은 여러 샘플이 필요합니다 — 계획되어 있지만 현재 빌드에는 없습니다.

여러 JSON 샘플에서 타입을 추론할 수 있나요?

아직은 — 현재 추론기는 한 번에 하나의 샘플을 읽습니다. 동일한 인터페이스를 공유해야 하는 두 페이로드가 있는 경우(예: 목록 엔드포인트와 단일 항목 엔드포인트), 실용적인 해결책은 하나의 배열로 병합하고, 그 배열에서 생성하고, 결과 유니온 타입의 이름을 변경하는 것입니다. 다중 샘플 추론은 한 응답에 있고 다른 응답에 없는 필드를 발견하는 유일한 방법이기 때문에 로드맵에 있습니다.

페이로드를 붙여넣고, 루트 이름을 지정하고, 인터페이스를 복사하세요. 전체 파이프라인이 브라우저에서 실행되므로 미출시 API나 서명된 웹훅 본문이 사용자의 기기에 머뭅니다.

JSON에서 TypeScript 인터페이스 생성 _

// 관련 도구