입력

출력

GraphQL 포매터란

코드 제너레이터, 페더레이션 컴포저, 또는 채팅창에서 복사해 온 GraphQL 스키마는 거의 항상 원하는 공백 모양이 아닙니다. 타입이 붙어 있고, 필드가 한 줄에 몰려 있으며, 설명문이 다음 정의에 짓눌려 있죠. GraphQL 스키마 정의 언어는 프론트엔드와 백엔드 사이의 읽기 좋은 계약이어야 하지만, 제대로 포맷되어 있어야만 그 역할을 합니다. SDL을 왼쪽 패널에 붙여넣으면 오른쪽 패널이 정리해서 돌려줍니다: 2칸 들여쓰기, 한 줄에 한 필드, 인자는 인라인, 블록 문자열 설명은 그것이 문서화하는 타입이나 필드 위에 그대로.

pretty-printer는 직접 작성된 것입니다 — graphql npm 패키지를 페이지에 로드하지 않으니 첫 페인트가 가볍게 유지됩니다. SDL을 토큰화하고 중괄호 구조를 따라가며 2021년 10월 GraphQL 사양에 맞춘 일관된 간격으로 다시 출력합니다. 실제 스키마에서 등장하는 모든 SDL 구문을 처리합니다: type, interface, union, enum, input, scalar, extend, schema, directive, 리스트 및 non-null 수정자([Foo!]!), 기본값, 디렉티브, 삼중 따옴표 설명. 포매터는 멱등(idempotent)합니다 — 이미 정리된 SDL은 그대로 왕복하므로 CI 게이트나 pre-commit 훅 안에 안전하게 넣어 돌릴 수 있습니다.

모든 처리는 브라우저에서 돌아갑니다. 업로드도 없고, 스키마가 어디에도 저장되지 않습니다. 붙여넣고, 정리하고, 복사하세요.

GraphQL 포매터 사용법

빠른 3단계. 아래에서 설명하는 버튼은 이 페이지에 실제로 있는 버튼입니다.

붙여넣기, 업로드, 또는 샘플 불러오기

GraphQL 스키마를 왼쪽 입력 패널에 붙여넣으세요 — 타이핑을 멈추고 찰나 뒤에 자동으로 포맷되므로 Convert 버튼을 찾을 필요가 없습니다. 업로드를 누르면 .graphql, .graphqls, .gql 파일을 불러올 수 있고, 샘플을 누르면 실제 같은 이커머스 Order 스키마가 로드됩니다. 전형적인 지저분한 붙여넣기는 이런 모양입니다:

type Order{id:ID! placedAt:DateTime! customer:Customer! items:[OrderItem!]!} type OrderItem{sku:String! name:String! quantity:Int! unitPrice:Money!}

서버 스타일 스키마(extend type Query 포함)와 독립된 타입 정의 모두 작동합니다. 받아들이는 형태는 Apollo Server 같은 도구가 시작 시 파싱하는 것과 같습니다.

정리된 출력 읽기

오른쪽 출력 패널에 2칸 들여쓰기로 정리된 SDL이 표시됩니다. 각 필드, enum 값, union 멤버는 자기 줄을 가집니다. 인자는 시그니처가 자연스럽게 읽히도록 필드 줄에 인라인으로 남습니다. 블록 문자열로 작성된 설명("""...""")은 그것이 설명하는 타입이나 필드 위 줄에 유지되며, 이는 Relay GraphQL 사양이 스키마 문서화에 권장하는 방식입니다. SDL에 중괄호 불균형이나 다른 파싱 오류가 있으면 포매터는 인라인으로 친절한 메시지를 표시합니다 — 예외를 던지거나 죽지 않습니다.

복사 또는 다운로드

복사를 눌러 풀 리퀘스트, 문서, 채팅용으로 정리된 스키마를 가져가세요. 다운로드로 .graphql로 저장할 수 있습니다. 입력 패널의 지우기 버튼은 빈 상태로 되돌립니다. 포맷은 전적으로 클라이언트 측에서 일어납니다 — 스키마는 페이지를 떠나지 않습니다.

실제로 쓰게 되는 상황

PR 리뷰 가독성

동료가 스키마에 새 타입 5개를 추가하는 PR을 엽니다. 코드젠 출력이 포맷을 잃은 탓에 diff가 거대한 한 덩어리처럼 보입니다. 파일을 포매터에 통과시키고 정리된 버전을 PR 설명에 붙여 두면 리뷰어가 추가된 내용을 실제로 읽을 수 있습니다. GraphQL 스키마 모범 사례를 따르는 일은 리뷰어가 구조를 볼 수 있을 때 훨씬 쉽습니다.

스키마 레지스트리 diff

대부분의 스키마 레지스트리(Apollo Studio, GraphQL Hive, Hasura)는 diff를 줄 단위 텍스트로 보여줍니다. 한 리비전은 압축되어 있고 다음은 정리되어 있다면 모든 줄이 변경된 것으로 보이고 진짜 변경 사항은 노이즈에 묻힙니다. 업로드 전에 양쪽 모두 정리하세요 — 같은 포매터, 같은 출력, 진짜 diff.

문서와 온보딩

GraphQL API의 공개 문서를 쓰거나 새 엔지니어를 온보딩 중인가요? 스키마를 붙여넣고 정리된 버전을 위키나 README에 복사하세요. 각 타입 위에 설명이 보이는 스키마는 코드젠 도구가 뱉어낸 포맷 없는 덩어리보다 훨씬 친절한 출발점입니다.

pre-commit과 CI 게이트

포매터가 멱등이기 때문에 pre-commit 훅이나 CI 체크로 돌릴 수 있습니다: 스키마를 포맷하고, 결과가 커밋된 파일과 다르면 빌드를 실패시키세요. 기여자 사이의 공백 드리프트가 사라지고 diff의 절반이 재포맷 노이즈인 PR도 사라집니다.

자주 묻는 질문

스키마를 검증해 주나요, 아니면 포맷만 하나요?

포맷만 합니다. 포매터는 pretty-print에 필요한 만큼만 중괄호와 따옴표 균형을 확인하고, Query가 존재하는지, 참조된 타입이 정의되어 있는지, 디렉티브 인자가 정의와 맞는지는 검증하지 않습니다. 전체 검증은 레퍼런스 구현 graphql-js나 서버의 시작 시 체크를 통과시키세요.

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

아니요. 포맷은 전적으로 브라우저에서 돌아갑니다. 아무것도 업로드되지 않고 아무것도 로깅되지 않습니다. 사내용이나 미공개 스키마도 안심하고 붙여넣어도 됩니다.

블록 문자열 설명을 처리하나요?

네. 삼중 따옴표 설명("""고객이 등록한 주문.""")은 보존되어 그것이 문서화하는 타입이나 필드 위 줄에 출력됩니다. GraphQL 사양에 따라 SDL 문서를 작성하는 표준 방법입니다.

디렉티브와 커스텀 스칼라는요?

둘 다 유지됩니다. @deprecated, @key, 모든 커스텀 디렉티브는 필드에 인라인으로 남습니다. scalar DateTime 같은 커스텀 스칼라는 자기 줄로 출력됩니다. 포매터는 디렉티브의 의미를 해석하려 하지 않습니다 — 그건 서버의 몫입니다.

이미 정리된 SDL이 다시 포맷되나요?

멱등합니다 — 이미 정리된 SDL을 정리해도 같은 출력이 나옵니다. 그래서 CI 체크나 붙여넣고 비교하는 워크플로에서 공백 드리프트 걱정 없이 포매터를 돌릴 수 있습니다.

얼마나 큰 스키마까지 붙여넣을 수 있나요?

브라우저가 무리 없이 렌더링하는 만큼이면 됩니다. 수백 타입 규모의 스키마는 문제없습니다. 5 MB를 넘으면 Ace 에디터 자체가 느려지기 시작합니다 — 병목은 거기지 파서가 아닙니다.

다른 GraphQL 도구

포맷은 GraphQL 작업의 한 부분일 뿐입니다. 나머지는 이 도구들이 처리합니다: