입력

검증

왼쪽에 GraphQL 스키마를 붙여넣으면 여기에 검증 결과가 표시됩니다.

GraphQL 검증기란?

연합 컴포저, 코드 생성기, 또는 코드 리뷰 중 손으로 편집한 결과로 돌아온 스키마는 첫 처리에서 거의 항상 적어도 하나의 구문 문제를 가지고 있습니다. 잘못 들어간 }, 종료되지 않은 설명 문자열, 누군가가 채팅에 SDL의 절반 화면을 복사하면서 잘려나간 enum 본문 — 그리고 어느새 Apollo Server 시작이 1번 줄을 가리키는 파서 오류로 폭발하는데, 거기는 실제 문제가 있는 위치인 경우가 거의 없죠. 이 검증기는 SDL을 토큰 단위로 훑어보고 진짜 줄을 짚어줍니다.

2021년 10월 GraphQL 명세의 구조적 규칙을 검사합니다: 모든 {, (, [는 올바른 종류의 닫는 짝이 필요하고, """..."""로 작성된 설명은 종료되어야 하며, 인수 안의 따옴표 문자열은 같은 줄에서 닫혀야 합니다. 검증기는 의미론은 확인하지 *않습니다* — Query가 누락되었는지, 필드가 선언되지 않은 타입을 참조하는지는 알려주지 않습니다. 그건 참조 구현인 graphql-js에 스키마를 돌려보세요. 이 페이지가 잘하는 것은 구문 패스와 통계 블록이라서, 방금 붙여넣은 스키마가 14개의 타입인지 4개인지, 187개 필드인지 12개인지 한눈에 볼 수 있습니다.

모든 것은 브라우저에서 동작합니다. 업로드 없음, 스키마는 어디에도 저장되지 않습니다. 붙여넣고, 검증하고, 복사.

GraphQL 검증기 사용 방법

간단한 세 단계입니다. 아래 버튼은 이 페이지의 실제 버튼과 일치합니다.

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

왼쪽 입력 패널에 GraphQL 스키마를 붙여넣으세요 — 입력을 멈춘 뒤 1초도 안 되어 자동으로 검증이 실행되므로 Validate 버튼은 없습니다. .graphql, .graphqls, .gql 파일이라면 업로드를 클릭하거나, 실제와 같은 e커머스 Order 스키마를 불러오려면 샘플을 누르세요. 일반적인 붙여넣기는 이렇게 생겼습니다:

type Order { id: ID! placedAt: DateTime! customer: Customer! items: [OrderItem!]! status: OrderStatus! } enum OrderStatus { PENDING PAID SHIPPED }

서버 스타일의 스키마(extend type Query가 포함된 것)와 단독 타입 파일 모두 동작합니다. 주석(#)과 블록 문자열 설명("""...""")은 GraphQL learn-schema 문서가 설명하는 방식 그대로 처리됩니다.

통계 블록 읽기

오른쪽 패널은 스키마가 깔끔하게 파싱되면 초록색 배너를, 그렇지 않으면 빨간색 배너를 보여줍니다 — 그리고 어느 쪽이든 스키마가 선언한 type, interface, enum, input, union, scalar, directive 정의의 수와 함께 전체 필드 수, 인수 수, 설명 수의 내역을 얻을 수 있습니다. 연합 머지의 정상성 점검이나 같은 스키마의 두 리비전을 비교할 때 유용합니다. 카운트는 Relay GraphQL 명세가 정의의 구조적 부품이라고 부르는 것을 그대로 반영합니다.

고치고 다시 붙여넣기

스키마가 유효하지 않으면 배너가 짝이 맞지 않는 중괄호나 종료되지 않은 문자열의 정확한 줄을 알려줍니다. 고치고, 다시 붙여넣고, 배너가 초록으로 변하는 걸 확인하세요. 오른쪽의 복사 버튼은 PR 설명이나 채팅 메시지에 떨어뜨릴 수 있는 작은 JSON 통계 보고서를 줍니다 — SDL 자체를 공유하지 않고도 동료에게 "그래, 스키마 괜찮아, 통계는 이거야"라고 보여주고 싶을 때 편리합니다.

실제로 쓰게 될 상황

머지 전 정상성 점검

연합 게이트웨이 변경이나 schema-stitching 업데이트를 머지하기 전에, 합성된 스키마를 여기에 붙여넣으세요. 중괄호 균형이 어긋났거나 설명이 종료되지 않았다면, 10분 뒤 CI 실패가 아니라 2초 안에 보게 됩니다. 의미론 쪽은 rover subgraph check 명령과 함께 쓰면 잘 어울립니다.

두 리비전 디핑

버전 A를 붙여넣고 통계 숫자를 메모하세요(28 타입, 142 필드, 6 enum). 버전 B를 붙여넣고 비교. 필드 수가 40 늘어났는데 새 타입은 하나만 추가됐다면, 누군가가 프래그먼트를 중복시켰을 가능성이 큽니다. 통계 블록은 2000줄짜리 diff를 스크롤하는 것보다 훨씬 빠릅니다.

신규 외주 개발자 온보딩

스키마 파일을 건네주고, 이 페이지를 가리키며, "빨간색으로 가면 네 붙여넣기가 깨진 거고, 필드 수가 갑자기 800 줄어들었으면 절반만 복사한 거야"라고 말해 주세요. 리졸버를 쓰기도 전에 "이게 전부야?"를 주고받는 수고를 덜어줍니다.

채팅에서 붙여넣기

Slack과 Discord는 긴 메시지를 줄바꿈할 때 백틱과 따옴표 문자를 망가뜨리는 걸 좋아해서, 누군가가 스레드에 붙여넣은 스키마는 닫는 중괄호 한두 개를 잃어버린 경우가 많습니다. IDE에서 열기 전에 먼저 여기에 떨어뜨려 확인하세요.

자주 묻는 질문

의미론을 검증하나요, 아니면 구문만 검증하나요?

구문만입니다 — 중괄호 균형, 문자열 종료, 그리고 토큰 스트림에 대한 통계 훑기입니다. Query의 존재 여부, 참조된 타입이 정의되어 있는지, 인수가 디렉티브 정의에 맞는지, 필드 타입이 유효한지는 *확인하지 않습니다*. 완전한 의미론 검증은 참조 라이브러리인 graphql-js나 서버 시작 시 점검을 사용하세요.

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

아니요. 검증은 전적으로 브라우저에서 실행됩니다. 업로드도, 로깅도 없습니다. 내부용 또는 비공개 스키마를 붙여넣어도 안전합니다.

실제로 어떤 구문 문제를 잡아주나요?

짝이 없는 { / ( / [와 그 여는 짝의 줄 번호, }가 와야 할 자리에 )처럼 잘못 매치된 닫는 짝, 종료되지 않은 "strings"나 """block strings""", 그리고 GraphQL 토큰 문법에 속하지 않는 떠도는 문자입니다.

분명히 타입이 있는데 왜 스키마가 0 타입으로 표시되나요?

통계 카운터는 정의의 키워드(type, interface 등)와 본문 중괄호가 모두 있을 때만 그 정의를 한 번 셉니다. 타입 중간에 잘린 스키마를 붙여넣으면, 그 타입의 카운트는 본문을 마칠 때까지 0으로 남습니다. 그 경우 검증기 배너도 빨갛게 표시되며, 짝이 없는 여는 짝을 가리킵니다.

블록 문자열 설명을 이해하나요?

네. """An order placed by a customer."""은 설명 토큰으로 인식되어 Descriptions 통계에 카운트됩니다. 검증기는 설명이 어디에 나타나야 하는지를 강제하지 않습니다 — 그건 스타일의 문제입니다 — 하지만 카운트를 통해 스키마가 얼마나 문서화되어 있는지 빠르게 파악할 수 있습니다.

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

브라우저가 무리 없이 렌더링할 수 있는 만큼이라면 무엇이든. 수백 개의 타입과 수천 개의 필드 스키마는 1초가 채 안 되어 검증됩니다. 5 MB를 넘어서면 Ace 에디터 자체가 느려지기 시작하는데, 그것이 병목이고 — 검증기가 아닙니다.

다른 GraphQL 도구

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