GraphQL SDL

TypeScript

이 변환기가 하는 일

GraphQL 스키마가 있고 프론트엔드는 TypeScript. 그 사이 어딘가에서 스키마와 필드 단위로 맞아떨어지는 타입 한 세트가 지금 바로 필요합니다 — 5분짜리 codegen 빌드를 기다리지 않고, 새 프로젝트에 graphql-code-generator를 연결한 뒤도 아니고, 주니어에게 어떤 플러그인을 깔아야 하는지 설명한 뒤도 아닙니다. 왼쪽 패널에 GraphQL SDL을 붙여넣으면 오른쪽 패널에 관용적인 TypeScript가 돌아옵니다: object와 input 타입은 interface, enum은 enum, union과 스칼라는 단순한 type 별칭으로요.

매핑은 대부분의 TypeScript 코드가 기대하는 규칙을 따릅니다. 내장 스칼라는 TypeScript의 기본형 대응으로 정렬됩니다: String과 ID는 string, Int와 Float는 number, Boolean은 boolean. DateTime 같은 커스텀 스칼라는 기본적으로 string이 되고, 나중에 넓혀야 할 것을 잊지 않도록 // custom scalar 마커가 붙습니다. non-null 필드(name: String!)는 필수 프로퍼티로 출력되고, nullable 필드는 ? 한정자가 붙어 출력됩니다. 리스트 타입 [Order!]!는 Order[]가 됩니다. type Order implements Node는 interface Order extends Node가 됩니다 — GraphQL의 interface 관계는 TS의 구조적 확장으로 깔끔하게 매핑됩니다.

업로드 없음, 네트워크 호출 없음, AI 없음. 변환은 손수 만든 SDL 토크나이저로 클라이언트 측에서 일어납니다 — 스키마는 페이지를 떠나지 않으며, 내부 스키마나 미공개 스키마를 다룰 때 정확히 원하는 동작입니다.

사용 방법

세 단계입니다. 변환은 자동으로 일어납니다 — Convert 버튼은 없습니다.

붙여넣거나, 업로드하거나, 샘플 불러오기

왼쪽 GraphQL SDL 패널에 SDL을 넣어주세요. 입력을 멈추는 즉시 오른쪽 패널이 갱신됩니다. .graphql / .graphqls / .gql 파일이라면 업로드, 현실적인 이커머스 스키마를 불러오려면 샘플을 누르세요. SDL 일부는 이런 모양입니다:

type Order implements Node { id: ID! placedAt: DateTime! status: OrderStatus! items: [OrderItem!]! } enum OrderStatus { PENDING PAID SHIPPED DELIVERED CANCELLED }

서버 스타일 스키마(extend type Query가 있는)와 독립적인 타입 정의 모두 동작합니다. 블록 문자열 설명("""...""")은 그대로 잡혀서 생성된 타입 위에 JSDoc 주석으로 출력됩니다 — GraphQL 레퍼런스 구현이 문서화한 관례입니다.

생성된 TypeScript 읽기

오른쪽 패널은 종류별로 묶어서 타입을 출력합니다: 먼저 스칼라, 그다음 enum, union, interface, input 타입, 마지막으로 object 타입. 각 그룹 안에서는 정의가 소스 순서를 유지하므로 직접 작성한 타입과의 diff가 가능한 한 작아집니다. SDL에 파싱 오류(중괄호 짝 안 맞음, 미완료 블록 문자열 등)가 있으면 출력 패널은 예외를 던지는 대신 // Invalid GraphQL: ... 한 줄 주석을 보여줍니다 — Apollo Server가 시작 시 파싱에 실패할 때 쓰는 것과 같은 패턴입니다.

복사 또는 다운로드

복사를 누르면 프로젝트의 schema.types.ts 파일에 바로 붙여넣을 수 있습니다. 다운로드를 누르면 .ts 파일로 저장됩니다. 출력은 평문 텍스트입니다 — 모듈 import도 없고 런타임 코드도 없어서 — 프론트엔드든 백엔드든 어떤 TS 프로젝트에도 그대로 들어갑니다.

실제로 쓸 만한 상황

codegen 셋업 없이 빠르게 타입만

기존 GraphQL 엔드포인트에 맞춰 프론트를 프로토타이핑 중인데, 쿼리 세 개의 타입을 위해서 codegen 파이프라인 전체를 띄우긴 싫습니다. 스키마를 붙여넣고, 출력을 types.ts에 복사한 뒤 프로토타입을 띄우세요. 프로젝트가 본격화되면 그때 제대로 된 codegen 파이프라인으로 옮기면 됩니다.

codegen이 만들어낼 타입 미리보기

스키마에 새 타입을 추가하기 전에 제안한 SDL을 여기에 붙여서 TypeScript 호출자 쪽이 어떤 모양이 될지 봅니다. SDL에서는 멀쩡해 보이는 필드가 어색한 TS를 만들어낼 때가 있습니다 — nullable의 옵셔널 리스트, TS 예약어와 충돌하는 값의 enum — 이건 PR이 머지된 뒤보다 여기서 발견하는 편이 훨씬 쌉니다.

TypeScript 위주 팀에 스키마 문서화

TS 우선 팀이 GraphQL API에 온보딩하나요? 스키마를 붙여넣고 생성된 타입을 위키에 복사하세요. TS interface로 사고하는 엔지니어들은 원시 SDL보다 TS 뷰로 스키마를 더 빨리 이해합니다 — 데이터 형태는 같고, 문법은 그들이 매일 막힘 없이 읽는 것일 뿐이니까요.

GraphQL 엔드포인트를 치는 일회용 스크립트

일회성 CLI, Node 스크립트, 관리 작업 — codegen 풀 셋업까지 가지 않고도 응답에 대해 타입이 좀 있었으면 하는 모든 경우. 붙여넣고, 복사하고, 응답에 타입을 달고, 스크립트를 돌리세요. 일회용이지만 망신은 안 당할 정도의 타입 안전성은 있습니다.

자주 묻는 질문

오퍼레이션 타입(Query / Mutation 결과 타입)도 생성하나요, 아니면 스키마 타입만?

스키마 타입만 — SDL에 선언된 타입들 말입니다. 오퍼레이션 결과 타입은 클라이언트가 실행하는 특정 쿼리나 뮤테이션에 의존하는데, 그게 정확히 typed-document-node 플러그인을 곁들인 graphql-code-generator가 하는 일입니다. 이 페이지는 스키마 쪽 절반을 다룹니다: SDL 안의 모든 type, interface, enum, input, union, scalar가 TS 선언으로 변환됩니다.

nullable 대 non-null 필드는 어떻게 처리되나요?

non-null 필드(name: String!)는 필수, 옵셔널이 아닌 TS 프로퍼티로 출력됩니다: name: string;. nullable 필드(name: String)는 옵셔널로 출력됩니다: name?: string;. 출력은 깔끔하게 유지됩니다 — 여기저기 | null 유니온이 깔리지 않아요 — 대부분의 사용자가 원하는 모양입니다. strict null checks 스타일이 좋다면 출력에 find-and-replace를 돌리면 됩니다.

[Order]나 [Order!]! 같은 리스트 타입은요?

리스트는 TS 배열이 됩니다. [Order!]!는 필수 필드에서 Order[]로 나옵니다. [Order]는 옵셔널 필드에서 Order[]로 나옵니다. 요소 단위의 nullability는 가독성을 위해 합쳐버립니다 — 보존이 필요하다면 생성된 T[]를 손으로 (T | null)[]로 바꾸면 되지만, 실무에서 내부 nullability를 별도로 읽는 코드베이스는 거의 없습니다.

커스텀 스칼라는 어떻게 처리되나요?

커스텀 스칼라(ID, String, Int, Float, Boolean이 아닌 모든 것)는 기본적으로 string이 되고, 찾아서 넓히기 쉽도록 // custom scalar 마커가 붙습니다. DateTime 스칼라라면 string | Date로 넓힐 수 있고, JSON 스칼라라면 unknown이나 타입이 있는 모양으로 넓힐 수 있습니다. 기본 string은 대부분의 서버가 JSON으로 와이어를 통해 보내는 것과 일치합니다.

제 스키마가 서버로 전송되나요?

아닙니다. 변환은 전적으로 브라우저 안에서 동작합니다 — SDL은 클라이언트에서 토큰화되고 TypeScript 출력은 곧장 오른쪽 패널에 렌더링됩니다. 업로드되는 것도, 로깅되는 것도 없습니다. 내부용이거나 미공개인 스키마도 안전하게 붙여넣을 수 있습니다.

출력을 다시 붙여넣으면 같은 SDL로 돌아오나요?

아닙니다 — 그런 의도도 아니에요. 출력은 TypeScript이고, 다른 언어입니다. TS 출력을 SDL 패널에 다시 붙여넣으면 파싱 오류가 납니다. GraphQL SDL 자체를 정렬하려면 아래 링크된 GraphQL Formatter를 쓰세요. 그게 그 일을 하라고 만든 도구입니다.

다른 GraphQL 도구

타입 생성은 한 부분일 뿐입니다. 이 도구들이 GraphQL 워크플로의 나머지를 처리합니다:

GraphQL 스키마를 TypeScript로