GraphQL이란 무엇인가 - REST API와 비교로 쉽게 이해하는 데이터 쿼리 언어
GraphQL이란 무엇인가 궁금하셨다면, REST와의 차이점부터 실전 활용법까지 개발자 눈높이에 맞춰 핵심만 정리했습니다
API를 설계하다 보면 한 번쯤 이런 경험을 하게 됩니다. 화면에 사용자 이름과 이메일만 필요한데, 서버에서는 주소, 전화번호, 가입일까지 전부 내려주는 상황입니다. 반대로 한 화면에 여러 데이터를 보여줘야 해서 API를 3~4번 연달아 호출하는 경우도 있습니다. 이런 문제를 근본적으로 해결하기 위해 등장한 것이 바로 GraphQL입니다.
GraphQL이란 무엇인가 - 기본 개념 정리
GraphQL은 2012년 Facebook(현 Meta) 내부에서 개발되어 2015년에 오픈소스로 공개된 데이터 쿼리 언어이자 런타임입니다. 쉽게 말하면, 클라이언트가 서버에 "이 데이터를 이런 형태로 주세요"라고 정확하게 요청할 수 있는 규격입니다.
기존 REST API에서는 서버가 응답의 구조를 결정합니다. 클라이언트는 정해진 엔드포인트에 요청을 보내고, 서버가 정의한 형태 그대로 데이터를 받아야 합니다. GraphQL은 이 관계를 뒤집습니다. 클라이언트가 필요한 필드를 직접 명시하고, 서버는 요청받은 필드만 정확히 반환합니다.
GraphQL의 3가지 핵심 연산
- Query - 데이터를 조회하는 연산입니다. REST의 GET 요청에 해당합니다
- Mutation - 데이터를 생성, 수정, 삭제하는 연산입니다. REST의 POST, PUT, DELETE에 해당합니다
- Subscription - 실시간으로 데이터 변경을 감지하는 연산입니다. WebSocket 기반으로 동작합니다
2024년 기준 GitHub, Shopify, Twitter(X), Airbnb 등 글로벌 기업 상당수가 GraphQL을 공식 API로 채택하고 있습니다. GitHub의 경우 REST API v3와 함께 GraphQL API v4를 운영 중이며, 새로운 기능은 GraphQL 우선으로 추가하고 있습니다.
GraphQL과 REST API 핵심 차이점
GraphQL이란 무엇인가를 제대로 이해하려면 REST와의 비교가 가장 직관적입니다. 아래 표에서 주요 차이점을 정리했습니다.
| 구분 | REST API | GraphQL |
|---|---|---|
| 엔드포인트 | 리소스별 다수 (예: /users, /posts) | 단일 엔드포인트 (예: /graphql) |
| 데이터 결정권 | 서버가 응답 구조 결정 | 클라이언트가 필요한 필드 지정 |
| Over-fetching | 불필요한 데이터도 함께 수신 | 요청한 필드만 수신 |
| Under-fetching | 여러 엔드포인트 호출 필요 | 한 번의 요청으로 해결 |
| 버전 관리 | v1, v2 등 URL 버전 관리 | 스키마 진화로 버전 불필요 |
| 캐싱 | HTTP 캐싱 자연스럽게 활용 | 별도 캐싱 전략 필요 |
| 학습 곡선 | 상대적으로 낮음 | 스키마, 리졸버 등 추가 학습 필요 |
REST에서 사용자 프로필 페이지를 구성한다고 가정해 봅시다. 사용자 정보는 /api/users/1, 게시글 목록은 /api/users/1/posts, 팔로워 수는 /api/users/1/followers로 총 3번 요청해야 합니다. GraphQL에서는 하나의 쿼리로 세 가지 데이터를 한 번에 가져옵니다.
GraphQL의 핵심 가치는 '정확히 필요한 데이터만, 한 번의 요청으로'라는 원칙에 있습니다. 이 원칙이 모바일 환경처럼 네트워크가 제한적인 상황에서 특히 큰 차이를 만듭니다.
GraphQL 쿼리 구조와 문법
GraphQL의 쿼리는 JSON과 비슷한 구조를 가지고 있어 직관적입니다. 기본 쿼리 예시를 살펴보겠습니다.
기본 쿼리 작성법
GraphQL 쿼리는 중괄호로 원하는 필드를 감싸는 형태입니다. 예를 들어 사용자의 이름과 이메일만 필요하다면 다음과 같이 작성합니다.
query { user(id: 1) { name, email } }- 기본 조회. id가 1인 사용자의 이름과 이메일만 반환됩니다query { user(id: 1) { name, posts { title, createdAt } } }- 중첩 조회. 사용자 이름과 함께 작성한 게시글의 제목, 작성일을 한 번에 가져옵니다mutation { createPost(title: "제목", content: "내용") { id, title } }- 데이터 생성. 새 게시글을 만들고 생성된 id와 title을 반환받습니다
스키마와 타입 시스템
GraphQL은 강력한 타입 시스템을 기반으로 합니다. 서버에서 스키마를 정의하면, 클라이언트는 해당 스키마 범위 안에서만 쿼리를 작성할 수 있습니다. 잘못된 필드명이나 타입을 요청하면 실행 전에 오류가 발생합니다. 이 덕분에 런타임 에러가 줄고, IDE에서 자동완성 지원도 받을 수 있습니다.
GraphQL을 선택해야 하는 상황
모든 프로젝트에 GraphQL이 정답은 아닙니다. 하지만 다음과 같은 상황에서는 GraphQL이 확실한 장점을 발휘합니다.
GraphQL이 빛나는 경우
- 다양한 클라이언트 지원 - 웹, 모바일 앱, 태블릿 등 각 플랫폼이 필요로 하는 데이터가 다를 때 효과적입니다. 하나의 API로 각 클라이언트에 맞는 응답을 제공할 수 있습니다
- 복잡한 데이터 관계 - 사용자, 게시글, 댓글, 좋아요 등 엔티티 간 관계가 깊은 서비스에서 중첩 쿼리로 효율적으로 데이터를 가져올 수 있습니다
- 빠른 프론트엔드 개발 - 프론트엔드 팀이 백엔드에 새 엔드포인트를 요청하지 않고도 필요한 데이터를 바로 조합해서 사용할 수 있습니다
- 마이크로서비스 통합 - 여러 마이크로서비스의 데이터를 하나의 GraphQL 게이트웨이에서 통합 제공할 수 있습니다. Apollo Federation이 이 패턴의 대표 사례입니다
실제로 Shopify는 GraphQL 도입 후 API 호출 횟수가 평균 47% 감소했다고 발표한 바 있습니다. 모바일 앱에서의 데이터 전송량도 크게 줄어 사용자 체감 속도가 개선되었습니다.
개발 과정에서 API 응답 데이터를 가공하거나 특정 패턴을 추출해야 할 때가 있습니다. 예를 들어 API 응답에서 이메일 주소나 특정 형식의 문자열을 걸러내야 한다면, 정규식 테스터 같은 도구를 활용하면 정규표현식을 실시간으로 테스트하며 정확한 패턴을 작성할 수 있습니다.
GraphQL의 한계와 주의할 점
GraphQL에도 분명한 한계가 있습니다. 도입 전에 반드시 검토해야 할 사항들입니다.
| 한계점 | 설명 | 대응 방안 |
|---|---|---|
| 캐싱 복잡성 | 단일 엔드포인트라 HTTP 캐싱이 어려움 | Apollo Client 등 전용 캐싱 라이브러리 활용 |
| N+1 문제 | 중첩 쿼리 시 DB 쿼리가 기하급수적으로 증가 | DataLoader 패턴으로 배치 처리 |
| 파일 업로드 | 기본 스펙에 파일 업로드 미포함 | graphql-upload 라이브러리 또는 REST 혼용 |
| 보안 | 복잡한 쿼리로 서버 부하 유발 가능 | 쿼리 깊이 제한, 복잡도 분석 미들웨어 적용 |
| 학습 비용 | 스키마 설계, 리졸버 구현 등 초기 학습 필요 | 공식 튜토리얼과 단계적 도입 |
특히 N+1 쿼리 문제는 GraphQL에서 가장 흔하게 마주치는 성능 이슈입니다. 사용자 목록을 조회하면서 각 사용자의 게시글도 함께 요청하면, 사용자 수만큼 추가 DB 쿼리가 발생합니다. Facebook이 만든 DataLoader를 사용하면 이러한 요청을 자동으로 배치 처리하여 DB 호출을 최소화할 수 있습니다.
GraphQL 시작하기 - 실전 도입 가이드
GraphQL을 실제 프로젝트에 도입하려면 서버와 클라이언트 양쪽 모두 준비가 필요합니다.
서버 구축 도구
- Apollo Server - Node.js 환경에서 가장 널리 쓰이는 GraphQL 서버입니다. Express, Fastify 등과 쉽게 통합됩니다
- Hasura - PostgreSQL 기반으로 스키마를 자동 생성하는 GraphQL 엔진입니다. 코드 없이 빠르게 API를 만들 수 있습니다
- Prisma + Nexus - 타입 안전한 ORM과 GraphQL 스키마를 코드로 정의하는 조합입니다
클라이언트 라이브러리
- Apollo Client - React, Vue, Angular 등 주요 프레임워크를 지원합니다. 캐싱, 상태 관리 기능이 내장되어 있습니다
- urql - Apollo보다 가볍고 번들 크기가 작습니다. 간단한 프로젝트에 적합합니다
- Relay - Meta가 만든 클라이언트로, 대규모 프로젝트에 최적화되어 있지만 학습 곡선이 가파릅니다
처음 시작한다면 Apollo Server + Apollo Client 조합이 가장 무난합니다. 공식 문서가 충실하고, 커뮤니티가 크기 때문에 문제 해결 시 참고 자료를 찾기 쉽습니다.
GraphQL이란 무엇인가에 대한 답을 한 문장으로 정리하면, 클라이언트가 주도권을 갖는 유연한 데이터 요청 방식입니다. 지금 바로 해볼 수 있는 가장 좋은 첫걸음은 두 가지입니다. 첫째, 공식 GraphQL 데모에서 직접 쿼리를 작성해 보는 것입니다. 둘째, 기존 프로젝트의 REST API 하나를 골라 GraphQL로 변환하는 연습을 해보는 것입니다. 작은 것부터 시작하면 실전 감각을 가장 빠르게 익힐 수 있습니다.
