왼쪽에 깨진 GraphQL을 붙여넣고 "Fix GraphQL!!"을 클릭해 복구하세요깨진 GraphQL 붙여넣기

GraphQL Fixer란?

GraphQL 스키마를 도구에 붙여넣었더니 Syntax Error: Expected ":", found Name 가 돌아온 적, 또는 누군가 필드명 뒤 콜론을 빼먹어 Schema Registry diff가 실패하는 걸 본 적이 있다면 그 답답함을 아실 겁니다. SDL은 봐주는 게 없습니다 — 문장 부호 하나만 빠져도 문서 전체가 파싱을 거부합니다. 이 도구는 흔한 고장들을 고칩니다: 필드명 뒤 누락된 콜론, type 안의 중복 필드, 짝이 맞지 않는 중괄호, 떠도는 콤마, 잘못 친 스칼라 참조. 왼쪽 에디터에 깨진 스키마를 붙여넣고 녹색 Fix GraphQL!! 버튼을 누르면 오른쪽에 깨끗한 SDL이 돌아옵니다.

복구는 type, field, argument 문법에 대해 GraphQL October 2021 명세 를 따릅니다. 문법은 작지만 엄격합니다 — 규칙 전체는 공식 Schemas and Types 입문서 를 참고하세요. Fixer는 필드명, type, 디렉티브를 건드리지 않고 구조만 정리하므로 registry 대비 diff가 깨끗하게 유지됩니다. 결과를 한 번 더 확인하고 싶다면 Apollo Server 스키마 문서 의 검증기에 넣거나 graphql-js 에 들어 있는 레퍼런스 파서로 돌려보세요.

스키마는 작은 AI 서비스로 보내지며, 구문만 고치도록 지시되어 있습니다 — 필드를 만들어내거나, 이름을 바꾸거나, 지우는 일은 절대 없습니다. 복구된 SDL은 일반 텍스트로 반환되어 프로젝트에 바로 붙여넣을 수 있습니다. 우리 쪽에서는 아무것도 기록하지 않습니다.

GraphQL Fixer 사용법

세 단계. 각 단계는 이 페이지의 실제 버튼을 사용합니다.

깨진 SDL 붙여넣기 또는 샘플 불러오기

깨진 GraphQL SDL을 왼쪽 에디터에 넣으세요. 샘플 GraphQL 을 클릭하면 이 도구가 다루는 종류의 고장 — 누락된 콜론, 중복 필드, 닫는 중괄호 누락 — 이 일부러 들어간 Order/Customer 스키마가 로드됩니다.

type Order {
  id: ID!
  placedAt DateTime!
  total Money!
}

Fixer는 작성하지 않은 필드를 만들어내지 않습니다. GraphQL 문법이 거부하는 구문만 고칩니다. 유효 구문 위에서의 명명·설계 관습은 GraphQL 모범 사례 가이드 를 한 번 읽어볼 만합니다.

Fix GraphQL!! 클릭

녹색 버튼을 누르세요. Fixer가 깨진 SDL을 읽고 구조·문장 부호 오류를 찾아 문서를 다시 작성합니다. 작업 중에는 로딩 표시가 보입니다. 두 에디터 모두 SDL 구문 강조를 사용해 전후를 나란히 비교할 수 있습니다.

정리된 스키마 복사

오른쪽 패널에 복구된 SDL이 표시됩니다. 필드명, type, 설명, 디렉티브는 그대로 — 구문 오류만 고쳐졌습니다. 출력을 복사해 schema.graphql 파일이나 registry에 붙여넣으세요.

실제로 쓰게 되는 상황

직접 편집한 스키마 정리

큰 schema.graphql 을 손으로 고치다가 placedAt 과 DateTime! 사이 콜론을 빠뜨리셨나요? 오류 메시지는 "Expected :" 와 줄 번호만 알려줍니다. Fixer는 필드를 하나하나 뒤지지 않아도 콜론을 다시 넣어줍니다.

AI가 생성한 SDL 고치기

새 기능 스키마를 LLM에게 부탁했더니 중복 필드, 중괄호 자리에 들어간 콤마, 짝 없는 { 와 함께 돌아왔습니다. 흔한 실패 패턴이죠. 붙여넣고 Fix를 누르면 다시 쓰지 않고도 파싱 가능한 스키마를 얻습니다.

로그에서 스키마 복원

이스케이프에 감싸이거나 줄바꿈이 제거된 로그 한 줄에서 SDL 조각을 끄집어내셨나요? Fixer가 구조를 정리해 복원한 스키마가 실제로 다시 파싱되도록 만듭니다.

Schema Registry 사전 점검

페더레이티드 registry에 변경을 푸시하기 전에 SDL을 Fixer에 통과시켜 diff를 막을 만한 문장 부호 실수를 잡으세요. registry가 업로드를 거부해 왕복하는 시간을 아낍니다.

자주 묻는 질문

어떤 종류의 오류를 고치나요?

필드명과 그 타입 사이의 누락된 콜론(가장 흔한 고장), 같은 type 내 중복 필드, 누락되거나 남는 닫는 중괄호, input object 안의 떠도는 콤마, list type을 둘러싼 짝 없는 대괄호 등을 고칩니다. 필드, type, argument를 만들어내지 않습니다 — 파서가 거부하는 구문만 고칩니다.

제 필드명이나 타입을 바꾸나요?

아니요. 필드명, 스칼라명, type명, 설명, 디렉티브는 그대로 통과됩니다. Fixer가 손대는 건 구조적 구문뿐 — 작성한 이름은 작성한 그대로 유지됩니다.

커스텀 스칼라와 디렉티브를 지원하나요?

네. scalar Money, scalar DateTime, 커스텀 @auth 나 @deprecated 디렉티브 — 모두 보존됩니다. 커스텀 스칼라가 서버에 등록되어 있는지는 검증하지 않으며, SDL이 파싱되는지만 확인합니다.

페더레이티드 서브그래프(Apollo Federation)는요?

페더레이션 디렉티브(@key, @external, @requires)는 그대로 통과됩니다. Fixer는 순수하게 구문 복구 계층이며 — 페더레이션 컴포지션을 실행하지 않습니다. 정리된 출력은 이후에 registry의 컴포지션 단계로 따로 통과시키세요.

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

네 — 언어 모델이 거기 호스팅되어 있어 복구는 작은 백엔드 서비스에서 돌아갑니다. 입력은 기록하지 않으며 응답은 곧바로 브라우저로 돌아옵니다. 요청당 64 KB 크기 제한이 있습니다.

항상 파싱 가능한 스키마를 만들어 주나요?

위에서 설명한 흔한 고장은 그렇습니다. 입력에 구조가 너무 많이 빠져 원래 의도가 모호한 경우(예: type 본문 전체가 통째로 삭제) 추측 대신 오류를 표시할 수 있습니다. 그럴 땐 명확한 빈 곳을 손으로 채운 다음 결과를 한 번 더 통과시키세요.

다른 GraphQL 도구

복구는 GraphQL 작업 흐름의 한 부분입니다. 나머지는 이 도구들이 커버합니다: