입력

출력

GraphQL 미니파이어란?

GraphQL 스키마를 배포 산출물, Lambda 번들, CDN으로 전달되는 SDL 문자열에 실어 보낼 때 설명과 `#` 주석은 생각보다 빨리 누적됩니다. 실제 운영 스키마는 바이트 기준으로 40~60%가 문서일 수도 있습니다 — 사람이 읽을 때는 유용하지만 클라이언트 부트스트랩을 위해 회선을 흐를 때는 그저 무거운 짐입니다. GraphQL 명세는 주석, 블록 문자열 설명, 그리고 대부분의 공백을 무시 가능한 토큰으로 정의하고 있어, 어떤 합리적인 파서든 어차피 무시합니다. 이 미니파이어는 그것을 모두 제거하고 파서 입장에서 원본과 바이트 단위로 동등한 한 줄짜리 SDL을 돌려드립니다.

미니파이어는 직접 구현되어 있어 graphql npm 패키지를 페이지에 로드하지 않으므로 초기 렌더링이 가볍게 유지됩니다. SDL을 토큰화하고 모든 주석과 블록 문자열 토큰을 버린 다음, 인접한 name 토큰을 구분하는 데 필요한 최소한의 공백만 남기고 구조적 토큰을 다시 내보냅니다(명세 준수 SDL에서 공백이 정말 필요한 곳은 거기뿐입니다). 출력은 포맷터에서 사용되는 동일한 경량 파서로 검증되므로, 시작할 때 graphql-js나 Apollo Server를 거치는 왕복 결과가 원본과 동일합니다.

모든 작업은 브라우저 안에서 이루어집니다. 업로드 없음, 어디에도 스키마 저장 없음. 붙여넣고, 압축하고, 복사하세요.

GraphQL 미니파이어 사용 방법

빠른 세 단계입니다. 아래에 설명하는 버튼은 이 페이지에 실제로 있는 버튼입니다 — 압축은 자동으로 실행되므로 Minify 버튼은 없습니다.

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

왼쪽 입력 패널에 GraphQL 스키마를 붙여넣으세요 — 타이핑을 멈춘 뒤 잠깐 사이에 압축이 자동으로 실행되므로 변환 버튼을 찾을 필요가 없습니다. .graphql, .graphqls, .gql 파일이라면 업로드를 누르고, 아니면 샘플을 누르면 주석과 블록 문자열 설명이 들어 있는 현실적인 이커머스 주문 스키마가 로드되어 그것들이 제거되는 모습을 볼 수 있습니다. 일반적인 입력은 다음과 같습니다:

"""An order placed by a customer."""
type Order {
  # The unique order identifier
  id: ID!
  placedAt: DateTime!
  customer: Customer!
  items: [OrderItem!]!
  status: OrderStatus!
}

서버 스타일 스키마(extend type Query가 있는 형태)와 독립적인 타입 정의 모두 동작합니다. 허용되는 형태는 GraphQL 스키마 정의 언어가 지원하는 것과 동일합니다.

압축된 출력 확인하기

오른쪽 출력 패널은 압축된 SDL을 한 줄로 표시하며, 패널 헤더의 절약 바이트 알약으로 얼마나 줄었는지 한눈에 볼 수 있습니다. 주석(# ...)과 블록 문자열 설명("""...""")은 완전히 제거됩니다 — Relay GraphQL 명세에 따르면 의미상 0이며, 인트로스펙션 기반 도구는 어차피 리졸버 계층에서 설명을 가져옵니다. SDL의 중괄호 짝이 맞지 않거나 다른 파싱 오류가 있어도 미니파이어는 친절한 인라인 메시지를 보여줍니다 — 예외를 던지거나 죽지 않습니다.

복사 또는 다운로드

복사를 눌러 압축된 스키마를 가져와 배포 스크립트, Lambda 환경 변수, 설정 파일에 넣으세요. 다운로드를 누르면 .graphql로 저장됩니다. 입력 패널의 지우기 버튼으로 빈 상태로 되돌릴 수 있습니다. 압축은 전적으로 클라이언트에서 일어나며 — 스키마는 페이지를 떠나지 않습니다.

실제로 이걸 쓸 만한 상황

더 작은 배포 산출물

스키마를 서버리스 함수나 Docker 레이어에 번들링하시나요? 설명과 주석을 제거하면 보통 바이트 수가 절반으로 줄어듭니다. 거기에 모든 콜드 스타트와 모든 레이어 다운로드를 곱하면 청구서에 차이가 보이기 시작합니다. 런타임 파서는 신경 쓰지 않습니다 — 설명은 인트로스펙션 전용 메타데이터이고, 대부분의 운영 배포는 Apollo Router 운영 가이드에 따라 어차피 인트로스펙션을 끕니다.

CDN으로 전달되는 스키마

게이트웨이가 부팅 시 CDN에서 SDL을 가져온다면(Federation 슈퍼그래프 컴포지션, 스키마 레지스트리 가져오기 등), 콜드 패스에서는 모든 바이트가 지연 시간이 됩니다. 압축된 SDL은 동일하게 파싱되면서 회선 사이즈를 크게 깎아냅니다 — 이미 사라진 것을 gzip은 압축할 수 없으므로, 종종 gzip보다 더 효과적입니다.

소스에 스키마 인라이닝

가끔은 설정 파일, 환경 변수, 직접 만든 도구에 스키마 문자열을 인라이닝해야 할 때가 있습니다. 한 줄짜리 압축 버전은 모든 줄바꿈을 일일이 이스케이프하지 않아도 TypeScript 템플릿 리터럴이나 YAML 스칼라에 깔끔하게 들어갑니다.

디프 노이즈 줄이기

스키마의 두 리비전이 설명이나 주석에서만 다를 때, 진짜 구조 차이는 도큐멘트 문자열 변경 아래에 묻힙니다. 디프 전에 양쪽을 압축하면 진짜 스키마 변화만 드러나며, 변경 관리와 호환성 깨짐 감지에 유용합니다.

자주 묻는 질문

압축된 스키마는 여전히 유효한 GraphQL인가요?

네 — 명세가 무시 가능하다고 정의한 모든 토큰(주석, 설명, 불필요한 공백, 콤마)은 제거되지만, 모든 이름, 구두점, 문자열 리터럴, 숫자는 남습니다. 출력은 입력과 정확히 같은 AST로 파싱됩니다. 둘 다 graphql-js를 거쳐 생성된 문서를 비교해 확인할 수 있습니다.

스키마 문서가 사라지나요?

네 — 그게 핵심입니다. 설명과 `#` 주석은 제거됩니다. 압축되지 않은 원본은 버전 관리에 두고, 산출물을 막 보낼 때만 압축하세요. 클라이언트에 정말 노출하고 싶은 문서는 인트로스펙션 응답에 존재하며, 이는 배포된 SDL 문자열이 아니라 런타임 리졸버 메타데이터에서 생성됩니다.

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

아니요. 압축은 전적으로 브라우저 안에서 일어납니다. 아무것도 업로드되지 않고 어떤 것도 로깅되지 않습니다. 사내용이나 미공개 스키마를 붙여넣어도 안전합니다.

얼마나 절약할 수 있나요?

스키마에 문서가 얼마나 들어가 있느냐에 따라 다릅니다. 설명이 없는 기본 SDL은 10~15%(공백만) 절약됩니다. 모든 타입과 필드에 블록 문자열 설명이 달린 잘 문서화된 스키마는 보통 40~60% 절약됩니다. 출력 패널 헤더의 절약 바이트 알약이 입력에 대한 정확한 숫자를 알려줍니다.

디렉티브, 커스텀 스칼라, 페더레이션도 처리하나요?

네. @deprecated, @key, @external, scalar DateTime, 그리고 모든 커스텀 디렉티브나 스칼라는 유지됩니다. 미니파이어는 무시 가능한 토큰만 제거 — 의미가 있는 것은 모두 그대로 둡니다. Federation 디렉티브도 깔끔하게 왕복합니다.

얼마나 큰 스키마까지 압축할 수 있나요?

브라우저가 무리 없이 렌더링하는 만큼이면 무엇이든 가능합니다. 수백 개의 타입이 있는 스키마도 문제없습니다. 약 5MB를 넘어가면 Ace 에디터 자체가 느려지기 시작 — 병목은 미니파이어가 아니라 에디터입니다.

다른 GraphQL 도구

압축은 GraphQL 작업의 한 부분일 뿐입니다. 나머지는 이 도구들로 처리하세요: