GraphQL

GraphQL이란

GraphQL은 API를 위한 질의 언어이자, 그 질의를 실행하는 런타임이다. 서버는 데이터의 모양을 타입 스키마로 정의하고, 클라이언트는 그 스키마 안에서 필요한 필드만 골라 한 번에 요청한다. Meta가 2012년 사내용으로 만들어 2015년에 공개했고, 지금은 GraphQL Foundation이 명세를 관리한다.

GraphQL 서버는 클라이언트와 여러 백엔드 사이에 서서 자원을 그래프로 엮는다. 사용자 → 주문 → 상품처럼 관계를 따라 내려가는 질의를 한 요청으로 처리하고, 각 필드 값은 리졸버(resolver) 함수가 DB나 다른 API에서 가져온다.

type User { id: ID!, name: String!, orders(first: Int): [Order!]! }
type Order { id: ID!, total: Int!, items: [Item!]! }
 
query {
  user(id: "42") {
    name
    orders(first: 3) { total }
  }
}

응답은 질의와 같은 모양의 JSON이다. 요청하지 않은 필드는 오지 않는다.

세 가지 작업

스키마, 리졸버, 연산 이름과 변수

SQL과 이름이 닮았지만 쓰는 자리가 다르다. SQL은 백엔드가 DB에서 데이터를 꺼내려고 쓰는 언어이고, GraphQL은 클라이언트가 서버에서 데이터를 꺼내려고 쓰는 언어다. 특정 DB나 전송 방식에 묶이지도 않는다. 보통 HTTP POST로 보내고 구독은 WebSocket을 쓰지만, 명세상 다른 전송 계층도 쓸 수 있다.

쿼리와 뮤테이션은 내부 실행 방식이 거의 같고, 읽기와 쓰기를 나누는 규약이다. 차이는 뮤테이션의 최상위 필드가 순서대로 실행된다는 점이다(쿼리는 병렬로 실행될 수 있다).

REST에서는 프론트엔드가 백엔드가 정한 요청·응답 형식에 의존한다. GraphQL에서는 화면에 필요한 모양을 클라이언트가 질의로 정하므로 그 의존이 줄고, 협업의 접점이 스키마로 옮겨 간다.

REST 대신 GraphQL을 고를 때

GraphQL은 REST의 대체재라기보다 다른 선택지다. 화면마다 필요한 필드가 제각각이고 여러 소스의 데이터를 한 요청으로 묶어야 하며 프론트엔드 요구가 빠르게 바뀔 때 이득이 크다. 계약이 단순하고 고정적인 공개 API, HTTP 캐시가 중요한 읽기 위주 API는 REST가 운영하기 쉽다. 복잡도는 사라지지 않고 서버의 엔드포인트에서 클라이언트 질의와 서버 리졸버로 옮겨 간다는 점을 감안한다. 엔드포인트·계약·캐시·오류 처리 같은 축별 비교는 API 아키텍처 스타일에 있다.

약점과 대책

도입 패턴

① 클라이언트 래핑

flowchart TB
  app["앱"] --> gql["GraphQL 층(앱 안)"]
  gql --> ra["REST A"]
  gql --> rb["REST B"]

② BFF

flowchart TB
  web["웹"] --> bff1["BFF"]
  mob["모바일"] --> bff2["BFF"]
  bff1 --> be["백엔드 API들"]
  bff2 --> be

③ 모놀리식

flowchart TB
  web["웹"] --> gql["GraphQL 서버 하나"]
  mob["모바일"] --> gql
  partner["파트너"] --> gql
  gql --> be["백엔드 API들"]

④ 페더레이션

flowchart TB
  clients["클라이언트들"] --> gw["페더레이션 게이트웨이"]
  gw --> s1["서브그래프(사용자팀)"]
  gw --> s2["서브그래프(주문팀)"]
  gw --> s3["서브그래프(상품팀)"]

보통 클라이언트 하나가 GraphQL 서버 하나를 부르는 단순한 구조로 시작해, 팀과 클라이언트가 늘면 BFF나 페더레이션으로 옮겨 간다. 대형 서비스의 API 계층이 이렇게 바뀌어 온 흐름은 아키텍처와 API 계층의 진화에 있다.

운영 예: 등록된 쿼리

대규모 서비스는 클라이언트가 임의 질의를 보내게 두지 않고, 미리 등록한 질의만 실행하는 방식을 쓰기도 한다. 링크드인이 이 방식의 예다.

flowchart TB
  n1["1. 개발<br/>클라이언트 개발자가 질의를 작성하고 백엔드와 테스트"] --> n2["2. 등록<br/>질의를 커밋하면 쿼리 레지스트리에 게시된다<br/>(라우팅 메타데이터 포함)"] --> n3["3. 배포<br/>질의가 클라이언트 코드와 함께 배포된다"] --> n4["4. 실행<br/>요청은 질의 ID로 오고, 라우팅 계층이 메타데이터를 보고 맞는 서비스 클러스터로 보낸다<br/>서비스는 등록된 질의를 캐시해 두고 실행하며, 필요하면 여러 서비스(신원 → 조직)를 차례로 조회한다"]

이 구조에서는 별도의 GraphQL 게이트웨이를 두지 않을 수 있다. 네트워크 홉 하나와 단일 장애점을 없애기 위해서다. 등록된 쿼리는 악성 질의 차단과 캐시라는 GraphQL의 두 약점도 함께 줄인다.

정리

• GraphQL은 스키마 위에서 클라이언트가 필드를 고르는 질의 언어다. 쿼리·뮤테이션·구독 세 작업이 있다.
• 강점은 한 번에 필요한 만큼 가져오기와 강한 타입 계약이다.
• 약점은 N+1, 캐시, 악성 질의, 서버 복잡도다. DataLoader, 등록된 쿼리, 복잡도 제한으로 다룬다.
• 조직이 커지면 클라이언트 래핑 → BFF → 페더레이션으로 구조를 옮긴다.

관련 노트: API 아키텍처 스타일, REST API 설계, BFF (Backend For Frontend), gRPC, API 게이트웨이, 아키텍처와 API 계층의 진화