스키마 A (구버전)

스키마 B (신버전)

Diff

각 패널에 스키마를 붙여넣으세요 — 입력하는 동안 diff가 업데이트됩니다.

GraphQL 스키마 Diff란?

모든 API 변경은 누군가의 클라이언트를 깨뜨립니다. 스키마 PR을 머지하기 전에 가장 먼저 필요한 것은 실제로 무엇이 바뀌었는지에 대한 명확한 목록입니다 — 공백, 재포맷, 진짜 변경을 빨강과 초록의 벽에 한꺼번에 섞어버린 600줄짜리 GitHub diff가 아니라요. 왼쪽에 옛 스키마, 오른쪽에 새 스키마를 붙여넣으면 이 도구는 세 가지 목록을 줍니다: 추가된 것, 제거된 것, 그리고 기존 필드 중 타입이 바뀐 것. 스키마는 2021년 10월 GraphQL 사양에 따라 파싱되므로, 도구가 "타입"이나 "필드"라고 간주하는 것은 서버가 인식하는 것과 일치합니다.

diff는 구조적이지 텍스트적이 아닙니다. 타입 안에서 필드를 재정렬해도 보이지 않습니다. SDL을 재포맷해도 보이지 않습니다. 인자 이름 변경은 표시됩니다. Order.total에서 Int를 Float로 바꾼 것은 표시됩니다. OrderStatus.REFUNDED 같은 새 enum 값은 추가에 표시됩니다. union 멤버 제거는 제거에 표시됩니다. 출력 스타일은 GraphQL Inspector와 Apollo schema checks가 쓰는 분류에 맞춰져 있어서, 결국 검사를 CI로 옮길 때 워크플로우가 그대로 옮겨집니다.

모든 것은 브라우저에서 실행됩니다. 업로드 없음, 로그 없음. 공개 전 내부 스키마에도 안전합니다.

GraphQL 스키마 Diff 사용법

붙여넣고, 붙여넣고, 읽으세요. Compare 버튼은 없습니다 — 입력하는 동안 diff가 업데이트됩니다.

패널 A에 옛 스키마 붙여넣기

스키마 A (구버전)로 표시된 왼쪽 패널에 현재 프로덕션 스키마를 넣으세요. .graphql, .graphqls, .gql 파일은 업로드를 클릭하거나, 짝지어진 시작/이터레이션 예제를 로드하려면 샘플을 누르세요. 스키마가 예쁠 필요는 없습니다 — 포맷 차이는 무시됩니다.

패널 B에 새 스키마 붙여넣기

스키마 B (신버전)로 표시된 오른쪽 패널에 후보 스키마(PR에 있는 것)를 넣으세요. 도구는 두 스키마를 토큰화하고 모든 타입 정의를 순회하며, 입력을 멈춘 후 1초도 안 되어 diff를 재계산합니다. 레퍼런스 파서의 시맨틱은 graphql-js를 충분히 가깝게 따르므로, 여기서 보이는 것이 서버가 보게 될 것입니다.

세 목록 읽기

아래 패널에는 세 개 섹션이 있습니다. 추가(초록)는 새 타입, 새 필드, 새 enum 값, 새 union 멤버를 나열합니다. 제거(빨강)는 같은 카테고리를 반대로 나열합니다 — 보통 이게 breaking change이므로 이 목록을 먼저 훑으세요. 변경(호박색)은 타입이 바뀐 필드와 인자를 나열합니다. 예: Order.total: Int → Float. 스키마가 동등하면 그렇다고 알리는 단일 초록 배너가 나옵니다.

실제로 이걸 쓸 때

PR 리뷰

팀원이 다섯 개의 새 필드를 추가하고 인자 하나를 리네임한 PR을 엽니다. 그가 스키마를 포맷터로 돌렸기 때문에 GitHub diff는 읽을 수가 없습니다. 두 버전을 여기에 붙여넣어 진짜 변경 목록을 받으세요 — 보통 300개가 아니라 서너 개입니다. 리뷰어는 들여쓰기 논쟁 대신 실제 의미에 대해 논쟁할 수 있습니다.

Breaking Change 잡기

필드 제거, 반환 타입 좁히기, 필수 인자 리네임은 실서비스 클라이언트에 breaking change입니다. 제거와 변경 목록이 이를 곧바로 드러냅니다. 머지 전에 diff를 돌려 breaking change가 의도된 것임을 확인하세요. 같은 검사는 결국 CI에 들어가야 합니다 — 이 워크플로우의 프로덕션 버전은 Apollo schema checks 문서를 참조하세요.

온보딩 문서화

새 엔지니어가 "지난 스프린트에서 뭐가 바뀌었어요?"라고 물으면 월요일 버전과 금요일 버전을 패널에 붙여넣고 diff를 스프린트 노트에 복사하세요. 커밋을 스크롤하는 것보다 빠르고 훨씬 읽기 쉽습니다.

페더레이션 컴포지션 정합성 점검

Apollo Rover 같은 페더레이트 컴포저를 실행한 뒤, 이전 합성 스키마와 새 합성 스키마를 붙여넣으세요. diff는 컴포지션이 subgraph PR에서 기대한 변경을 가져왔는지 — 아니면 다른 어딘가에서 조용히 뭔가 바뀌었는지 — 알려줍니다.

자주 묻는 질문

diff가 breaking change를 특정해서 잡아주나요?

제거와 변경 목록의 모든 항목은 잠재적으로 breaking입니다 — 필드 제거, 반환 타입 좁히기, 인자 리네임. 도구는 GraphQL Inspector처럼 각 변경을 "breaking" 대 "non-breaking"으로 분류하지 않지만, 구조화된 목록 덕분에 어떤 것을 봐야 할지 분명합니다.

필드 순서는 변경으로 간주되나요?

아닙니다. 타입 안에서 필드를 재정렬하는 것은 구조적으로 동일하며 무시됩니다. enum 값, union 멤버, 인자 재정렬도 마찬가지입니다. 추가, 제거, 또는 타입이 바뀐 항목만 보고됩니다.

설명과 주석은요?

블록 문자열 설명과 주석은 구조 비교 시 무시됩니다. 필드에 설명을 추가해도 diff에 나타나지 않습니다. 문서 변경을 추적하고 싶다면 여기가 아니라 PR의 포맷된 SDL diff에서 하세요.

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

아닙니다. 토크나이저와 diff는 전적으로 브라우저에서 실행됩니다. 아무것도 업로드되지 않고 아무것도 로그되지 않습니다. 내부 또는 공개 전 스키마를 붙여넣어도 안전합니다.

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

페이지는 각 입력을 5 MB로 제한합니다. 그 이상이면 Ace 에디터 자체가 버벅이기 시작합니다. 수백 개 타입의 스키마는 문제없습니다.

CI에서 돌릴 수 있나요?

PR을 푸시하기 전 로컬 정합성 점검에는 이 페이지면 충분합니다. breaking change에서 빌드를 실패시키는 CI 게이트에는 전용 GraphQL Inspector CLI나 Apollo schema checks를 쓰세요 — 둘 다 적절한 exit-code 시맨틱과 정책 설정을 갖추고 있습니다.

다른 GraphQL 도구

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