GraphQL

GraphQL이 해결하려는 문제

GraphQL은 클라이언트가 필요한 데이터 구조를 직접 지정할 수 있게 만든 API 질의 방식이다. REST처럼 엔드포인트별로 정해진 응답을 받는 대신, 하나의 스키마를 기준으로 필요한 필드만 요청한다.

이 방식이 주목받는 이유는 다음과 같다.

• 필요한 필드만 가져와 over-fetching을 줄일 수 있다.
• 여러 리소스를 한 요청에서 함께 가져올 수 있다.
• 타입 시스템 기반으로 API 계약을 명확히 표현할 수 있다.

핵심 개념

Query

데이터 조회를 위한 요청이다. 어떤 필드를 원하는지 클라이언트가 직접 명시한다.

Mutation

데이터 변경을 위한 요청이다. 생성, 수정, 삭제 같은 쓰기 작업을 다룬다.

Schema

GraphQL 서버가 제공할 수 있는 타입과 필드를 정의한 계약이다. GraphQL을 이해할 때 가장 중요한 것은 엔드포인트보다 스키마다.

REST와 비교했을 때 장점

예를 들어 게시글과 작성자 정보를 함께 보여주는 화면이 있다고 하자.

REST에서는:

• 게시글 목록 API 호출
• 작성자 정보 API를 추가 호출

같은 형태가 되기 쉽다.

GraphQL에서는 하나의 요청에서 게시글과 작성자 필드를 함께 가져올 수 있다. 모바일이나 복합 화면에서 이 점이 특히 유리하다.

하지만 항상 더 좋은 것은 아니다

GraphQL도 비용이 있다.

• 서버 쿼리 복잡도 제어가 필요하다.
• 캐싱 전략이 단순 REST보다 어려울 수 있다.
• 스키마와 리졸버 설계가 잘못되면 N+1 문제가 커진다.

즉 GraphQL은 만능 대체재가 아니라, 복잡한 조회 조합을 많이 다루는 시스템에서 강한 도구에 가깝다.

언제 잘 맞나

• 화면마다 필요한 데이터 조합이 자주 달라진다.
• 프런트엔드 팀이 응답 필드를 더 유연하게 제어해야 한다.
• 여러 리소스를 조합한 조회가 빈번하다.

반대로 단순 CRUD 중심 내부 API라면 REST가 더 단순하고 유지보수하기 쉬울 수 있다.

정리

GraphQL의 본질은 “쿼리 언어”보다 클라이언트가 데이터 모양을 제어하는 API 계약 방식에 있다. 장점은 유연성이고, 비용은 복잡도 관리다.