입력

출력

GraphQL 뷰어가 뭔가요?

한 줄로 압축돼서 돌아온 GraphQL SDL을 어디선가 복사해 와서 읽어보려고 한 적이 있다면, 그 문제를 알 겁니다. 타입, 필드, 인자, 디렉티브, 유니온 멤버가 다 한 덩어리로 뭉쳐서 구조가 사라져 버리죠. 이 도구가 그걸 해결합니다. 왼쪽 패널에 스키마를 붙여 넣으면 오른쪽 패널이 2칸 들여쓰기, 한 줄에 한 필드, 인자는 인라인, 블록 문자열 설명은 그것이 문서화하는 타입이나 필드 위에 그대로 남긴 형태로 렌더링합니다.

예쁘게 출력하는 로직은 직접 구현했어요 — graphql npm 패키지를 페이지에 로드하지 않으니 첫 페인트가 가볍게 유지됩니다. SDL을 토큰화하고, 중괄호 구조를 따라가며, 2021년 10월 GraphQL 사양에 맞는 일관된 간격으로 다시 출력합니다. 실제로 마주치는 SDL 구문은 다 처리합니다: type, interface, union, enum, input, scalar, extend, schema, 리스트와 non-null 수정자([Foo!]!), 기본값, 디렉티브, 삼중 따옴표 설명. 이미 잘 정렬된 입력은 그대로 같은 출력으로 돌아옵니다.

모든 처리는 브라우저 안에서 일어납니다. 업로드 없음, 스키마 어디에도 저장되지 않음. 붙여 넣고, 읽고, 복사하면 끝.

GraphQL 뷰어 사용법

세 단계면 됩니다. 아래 설명하는 버튼들은 이 페이지에 실제로 있는 버튼입니다.

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

왼쪽 입력 패널에 GraphQL 스키마를 붙여 넣습니다. .graphql, .graphqls, .gql 파일이라면 업로드를 클릭하고, 현실적인 이커머스 스키마를 보고 싶다면 샘플을 누르세요. 압축된 SDL이 어떻게 생겼는지 빠른 예:

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

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

정렬된 출력 읽기

오른쪽 출력 패널이 파싱된 SDL을 2칸 들여쓰기로 렌더링합니다. 각 필드, enum 값, 유니온 멤버는 자기만의 줄을 가집니다. 인자는 필드 줄에 인라인으로 남아 있어서 시그니처가 자연스럽게 읽힙니다. 블록 문자열("""...""")로 작성된 설명은 그것이 설명하는 타입이나 필드 위에 남는데, 이는 Relay GraphQL 사양이 스키마 문서화 방식으로 권장하는 형태입니다. SDL의 중괄호가 안 맞거나 다른 파싱 오류가 있어도 뷰어는 죽지 않고 친절한 메시지를 보여 줍니다.

복사하거나 다운로드

복사를 누르면 정렬된 스키마를 풀 리퀘스트, 문서, 채팅에 바로 가져갈 수 있습니다. 다운로드를 누르면 .graphql로 저장됩니다. 입력 패널의 지우기 버튼은 빈 상태로 되돌립니다. 파싱은 전부 클라이언트 쪽에서 처리됩니다 — 스키마는 페이지를 떠나지 않습니다.

실제로 쓰게 되는 상황

스키마 PR 리뷰

스키마 PR을 리뷰 중인데, 파일이 코드 생성기를 거치면서 포맷이 다 날아가서 diff를 읽기 어려운가요? 새 버전을 여기에 붙여 넣고 구조를 눈으로 훑은 다음, 무엇이 바뀌었는지 더 명확한 멘탈 모델로 diff에 돌아가세요. 팀이 좋은 스키마 설계가 뭔지 다듬는 중이라면 특히 유용합니다.

페더레이션과 서브그래프 디버깅

Apollo 페더레이션 게이트웨이를 디버깅하는데 합성된 슈퍼그래프 스키마가 거대한 한 덩어리로 돌아오나요? 머지된 SDL을 붙여 넣고, 이상하게 동작하는 타입을 찾고, 어떤 필드가 어느 서브그래프에서 왔는지 확인하세요. 출력에 나타나는 페더레이션 디렉티브도 나머지 스키마 구문과 함께 그대로 표시됩니다.

API 문서화

팀에서 운영하는 GraphQL API의 공개 문서를 쓰는 중인가요? 뷰어에 스키마를 떨어뜨리고 정렬된 버전을 위키나 README로 복사하세요. 타입, 인터페이스, 유니온의 트리 구조는 한 줄에 한 필드로 펼쳐지면 자연스럽게 읽힙니다.

새로운 엔지니어 온보딩

새로 합류한 동료가 GraphQL API의 모양을 익히려 합니다. 각 타입 위에 설명이 보이는 정렬된 스키마는 코드젠 출력의 포맷 없는 덩어리보다 훨씬 친근한 출발점입니다.

자주 묻는 질문

스키마를 검증해 주나요, 아니면 그냥 정렬만 하나요?

그냥 정렬만 합니다. 뷰어는 예쁘게 출력하는 데 필요한 만큼만 중괄호와 따옴표 균형을 확인하고, Query가 존재하는지, 참조된 타입이 정의되어 있는지, 디렉티브 인자가 정의와 일치하는지는 확인하지 않습니다. 완전한 검증은 레퍼런스 구현인 graphql-js를 쓰거나 서버의 시작 검증을 통과시키세요.

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

아니요. 정렬 처리는 전부 브라우저에서 돌아갑니다. 아무것도 업로드되지 않고, 아무것도 로깅되지 않습니다. 사내용이나 미공개 스키마를 붙여 넣어도 안전합니다.

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

네. 삼중 따옴표 설명("""고객이 낸 주문.""")은 보존되어 그것이 설명하는 타입이나 필드의 윗줄에 출력됩니다. 이것이 GraphQL 사양에 따른 SDL 문서화의 정통 방식입니다.

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

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

이미 정렬된 SDL이 다시 정렬되나요?

멱등입니다 — 이미 정렬된 SDL을 다시 정렬해도 같은 출력이 나옵니다. 그래서 CI 검사나 붙여 넣고 비교하는 워크플로에 뷰어를 넣어도 공백 차이를 걱정할 필요가 없습니다.

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

브라우저가 무리 없이 렌더링할 수 있는 정도라면 뭐든. 타입이 수백 개인 스키마는 문제없습니다. 5 MB를 넘으면 Ace 에디터 자체가 느려지기 시작합니다 — 병목은 거기지 파서가 아닙니다.

다른 GraphQL 도구

보기는 GraphQL 작업의 일부일 뿐입니다. 나머지는 이 도구들이 처리해 줍니다: