JSON을 TypeScript Interface로 변환 — API 타입 가이드

JSON을 TypeScript interface로 바로 정리하는 작업 화면

프런트엔드 API 계약을 빠르게 확인할 수 있도록 interface 중심으로 구성한 전용 변환 페이지입니다.

JSON을 TypeScript interface로 바로 변환하고 optional field와 nested object 구조를 한 화면에서 검토할 수 있습니다.

{
  "orderId": "ORD-2026-001",
  "status": "PAID",
  "amount": 12900,
  "customer": {
    "name": "Lee",
    "email": "lee@example.com"
  }
}

export interface UserResponse {
  userId: string;
  name: string;
  active: boolean;
  roles: string[] | null;
  profile: Profile;
}

Explanation

왜 TypeScript 인터페이스가 중요한가

interface를 먼저 만들면 화면 로직, query layer, 테스트 fixture가 같은 응답 계약을 공유하기 쉬워집니다.

왜 인터페이스가 먼저 필요한가

프런트엔드에서 JSON을 바로 사용하면 화면 컴포넌트마다 필드 접근 방식이 달라지고, null 처리 규칙도 흐트러집니다. 인터페이스를 먼저 정의하면 네트워크 계층과 화면 계층 사이의 경계가 명확해지고, 응답 구조 변경 시 영향 범위를 좁힐 수 있습니다.

특히 `strictNullChecks`, `noImplicitAny` 같은 옵션을 적극적으로 쓰는 프로젝트에서는 샘플 JSON으로 인터페이스 초안을 빠르게 만드는 편이 훨씬 효율적입니다.

JSON에서 TypeScript로 바뀌는 예시

이 단계에서 `updatedAt`이 문자열인지 날짜 래퍼인지, `location`이 truly optional인지까지 팀이 함께 결정하면 이후 API 클라이언트 코드가 훨씬 안정적입니다.

입력 JSON

{
  "warehouseId": "ICN",
  "updatedAt": "2026-03-11T10:22:31Z",
  "items": [
    {
      "sku": "SKU-01",
      "stock": 12,
      "location": {
        "zone": "A"
      }
    }
  ]
}

생성 예시

export interface InventoryResponse {
  warehouseId: string;
  updatedAt: string;
  items: InventoryItem[];
}

export interface InventoryItem {
  sku: string;
  stock: number;
  location?: LocationHint | null;
}

export interface LocationHint {
  zone: string;
}

Type mapping에서 자주 보는 선택지

TypeScript는 표현력이 높기 때문에, 생성기 출력이 지나치게 넓거나 반대로 너무 엄격할 수 있습니다. 그래서 초안 생성 이후에 팀 규칙에 맞는 축소 작업이 자주 필요합니다.

배열은 `T[]`와 `readonly T[]` 중 어떤 규칙을 쓸지 결정
필드 누락은 `?`로, null 전송은 `| null`로 분리해 표현
문자열 literal 후보는 union type 또는 enum 후보로 검토
동적 키 구조는 `Record<string, T>`로 치환 가능한지 확인

React, Node, API client에서의 활용

React에서는 API 응답 인터페이스와 화면 전용 view model을 분리해 두면 컴포넌트 props가 안정적으로 유지됩니다. Node 백엔드에서는 같은 인터페이스를 Zod, Valibot, io-ts 같은 런타임 스키마 도구와 함께 사용할 수도 있습니다.

JSON2Class는 우선 구조를 빠르게 읽기 좋은 타입 선언으로 바꾸는 데 집중하고, 이후 실제 런타임 검증은 프로젝트 스택에 맞는 도구로 이어 붙이는 흐름이 가장 현실적입니다.

optional과 nullable을 섞지 않는 기준

프런트엔드 코드에서 가장 흔한 혼란은 필드가 아예 없을 수 있는지, 아니면 null로는 오지만 키 자체는 항상 있는지 구분하지 않는 데서 시작합니다. 이 둘을 분리해 두지 않으면 조건문이 불필요하게 복잡해지고, 런타임 버그도 늘어납니다.

샘플 JSON이 한 가지뿐이라면 optional과 nullable을 과하게 확정하지 말고, 실제 응답 패턴을 한 번 더 모아보는 편이 낫습니다. JSON2Class는 구조 파악을 빠르게 돕는 도구이지, 운영 계약을 독단적으로 확정하는 도구는 아닙니다.

nested object와 배열 다루기

중첩 객체는 별도 인터페이스로 분리해야 재사용성과 가독성이 좋아집니다. 배열은 요소 타입이 확정되는 순간 강력한 문서 역할을 하기 때문에, 빈 배열 샘플만 보고 `any[]` 비슷한 타입으로 남기지 않는 것이 중요합니다.

동적 키가 섞여 있다면 억지로 인터페이스 필드로 나열하지 말고 `Record<string, T>` 또는 인덱스 시그니처로 전환하는 편이 훨씬 현실적입니다.

실무 워크플로우

이 흐름을 따르면 선언문이 문서 역할도 함께 하게 됩니다. 코드 리뷰에서 구조 변경을 설명할 때도 인터페이스 diff 하나로 대부분의 맥락을 전달할 수 있습니다.

샘플 JSON을 붙여 넣고 루트 타입명을 먼저 고정
생성된 인터페이스를 API client 계층에 배치
optional/null 규칙을 실제 응답과 대조하면서 축소
필요하면 runtime schema 도구로 한 단계 더 검증

프런트엔드 생산성 관점의 장점

인터페이스가 고정되면 화면 컴포넌트가 다루는 데이터 범위가 좁아집니다. 그 결과 props 설계가 단순해지고, 테스트 더블 작성도 쉬워집니다. IDE 자동완성과 hover 정보가 풍부해지는 것도 직접적인 생산성 향상입니다.

서버와 클라이언트가 함께 일하는 팀이라면, 같은 JSON을 Java나 Kotlin 탭에도 넣어 보면서 해석 차이를 줄이는 것이 좋습니다. JSON2Class는 이 비교 작업을 빠르게 할 수 있는 도구라는 점에서 가치가 큽니다.

Related Tools

같이 보면 좋은 도구

언어별 변환기와 JSON 보조 도구를 연결해 내부 링크 구조를 강화했습니다.