GraphQL 포맷터 완벽 가이드
GraphQL은 Facebook이 개발한 API 쿼리 언어로, REST API의 한계를 극복하기 위해 탄생했습니다. 클라이언트가 필요한 데이터의 구조를 직접 명시할 수 있어 오버페칭(over-fetching)과 언더페칭(under-fetching) 문제를 해결합니다. 현재 GitHub, Shopify, Twitter(X), Airbnb 등 수많은 대형 서비스에서 GraphQL을 채택하고 있으며, 프론트엔드와 백엔드 개발자 모두가 일상적으로 GraphQL 쿼리와 스키마를 작성하고 있습니다.
그러나 GraphQL 쿼리는 복잡한 중첩 구조를 가지는 경우가 많아, 정렬되지 않은 상태로는 구조를 파악하기 어렵습니다. 특히 여러 필드와 인자, 프래그먼트, 디렉티브가 포함된 쿼리는 적절한 들여쓰기 없이는 가독성이 크게 떨어집니다. 이 GraphQL 포맷터 도구는 이러한 문제를 해결하기 위해 만들어졌습니다. 입력한 GraphQL 텍스트를 자동으로 분석하여 들여쓰기가 적용된 보기 좋은 형태(Pretty Print)로 변환해 줍니다.
본 도구의 핵심 기능인 구문 하이라이팅은 GraphQL의 각 요소를 색상으로 구분하여 표시합니다. query, mutation, subscription, type, input, enum, interface, union, scalar, fragment, extend, implements 등의 키워드는 빨간색 계열로 강조됩니다. 타입명(String, Int, Float, Boolean, ID 및 사용자 정의 타입)은 보라색으로, 인자(argument)는 파란색으로, 디렉티브(@deprecated, @skip, @include 등)는 주황색으로, 문자열 값은 진한 파란색으로 표시되어 복잡한 GraphQL 문서도 한눈에 구조를 파악할 수 있습니다.
축소(Minify) 모드를 활성화하면 모든 공백, 줄바꿈, 주석을 제거하여 네트워크 전송에 최적화된 최소 크기의 GraphQL 쿼리로 변환합니다. 이는 프로덕션 환경에서 GraphQL 쿼리의 전송 크기를 줄여 성능을 개선하는 데 유용합니다. 특히 모바일 환경이나 대역폭이 제한된 네트워크에서 효과적입니다.
들여쓰기 크기는 2칸 스페이스, 4칸 스페이스, 탭(Tab) 중에서 선택할 수 있어 팀의 코딩 컨벤션에 맞게 조정할 수 있습니다. 모든 처리는 사용자의 브라우저 내에서 JavaScript로 이루어지며, 입력한 GraphQL 데이터는 외부 서버로 전송되지 않습니다. LocalStorage를 활용하여 마지막으로 입력한 내용을 자동 저장하므로, 페이지를 새로고침하더라도 작업 내용이 유지됩니다. 복사, 공유, 이미지 저장 기능도 제공하여 팀원과의 협업에도 편리합니다.
주요 기능
- Pretty Print: GraphQL 쿼리와 스키마를 들여쓰기가 적용된 보기 좋은 형태로 변환
- Minify: 모든 공백, 줄바꿈, 주석을 제거하여 최소 크기로 축소
- 구문 하이라이팅: 키워드, 필드, 타입, 인자, 디렉티브, 변수를 색상으로 구분
- 줄 번호 표시: 대용량 GraphQL 문서에서도 특정 위치를 쉽게 찾을 수 있음
- 들여쓰기 설정: 2칸, 4칸 스페이스 또는 탭 중 선택 가능
- 복사 및 공유: 결과를 클립보드에 복사하거나 SNS로 공유 가능
- 이미지 저장: 결과 요약을 이미지 카드로 저장하여 공유 가능
- 자동 저장: LocalStorage를 활용한 입력 내용 자동 저장
자주 묻는 질문 (FAQ)
Q. GraphQL 포맷터란 무엇인가요?
A. GraphQL 포맷터는 정렬되지 않거나 축소된 GraphQL 쿼리, 뮤테이션, 스키마를 사람이 읽기 쉬운 형태로 변환하는 도구입니다. 들여쓰기와 줄바꿈을 자동으로 적용하여 중첩된 필드 구조를 한눈에 파악할 수 있게 합니다. 반대로 축소(Minify) 기능을 사용하면 불필요한 공백과 주석을 모두 제거하여 전송 크기를 최소화할 수 있습니다.
Q. 입력한 GraphQL 데이터가 서버로 전송되나요?
A. 아닙니다. 이 도구의 모든 처리는 사용자의 브라우저 내에서 JavaScript로 이루어지며, 입력한 데이터는 외부 서버로 전송되지 않습니다. 따라서 API 키, 인증 토큰, 개인정보 등 민감한 데이터가 포함된 GraphQL 쿼리도 안전하게 사용할 수 있습니다.
Q. GraphQL 스키마 정의도 포맷할 수 있나요?
A. 네, 이 도구는 GraphQL 쿼리(query), 뮤테이션(mutation), 서브스크립션(subscription)뿐만 아니라 type, input, enum, interface, union 등의 스키마 정의 언어(SDL)도 지원합니다. 스키마 파일 전체를 붙여넣어도 올바르게 정렬됩니다.
Q. 구문 하이라이팅에서 각 색상은 무엇을 의미하나요?
A. 키워드(query, mutation, type 등)는 빨간색, 타입명(String, Int, 사용자 정의 타입)은 보라색, 인자(argument)는 파란색, 디렉티브(@deprecated 등)는 주황색, 문자열 값은 진한 파란색, 주석은 회색으로 표시됩니다. 이를 통해 복잡한 GraphQL 문서의 구조를 직관적으로 파악할 수 있습니다.
Q. 축소(Minify) 모드는 언제 사용하나요?
A. 축소 모드는 GraphQL 쿼리를 네트워크로 전송할 때 전송 크기를 최소화하고 싶을 때 사용합니다. 프로덕션 환경에서 클라이언트가 서버로 보내는 쿼리의 크기를 줄여 성능을 개선할 수 있습니다. 특히 persisted query를 사용하지 않는 환경에서 유용합니다.
Q. 잘못된 GraphQL 구문을 입력하면 어떻게 되나요?
A. 중괄호 불일치, 괄호 불일치 등의 기본적인 구문 오류를 감지하여 에러 메시지를 표시합니다. 다만 이 도구는 경량 포맷터로서, 전체 GraphQL 문법 검증(validation)보다는 정렬과 하이라이팅에 초점을 맞추고 있습니다. 완전한 문법 검증이 필요한 경우 GraphQL IDE(예: GraphiQL, Apollo Studio)를 함께 사용하는 것을 권장합니다.