GraphQL

클라이언트가 필요한 데이터의 모양을 직접 명시해 요청하는 쿼리 언어이자 런타임.

무엇을 해결하려 했나

REST의 두 가지 고질적 문제다.

① 오버페칭 — 필요 없는 것까지 받는다

• GET /users/1
• { id, name, email, address, phone, createdAt, profile, settings, … }
  • 화면에는 name만 필요한데 전부 내려온다

② 언더페칭 — 여러 번 호출해야 한다

• GET /users/1 — → 사용자
• GET /users/1/orders — → 주문 목록
• GET /orders/5/items — → 주문 항목
• 화면 하나를 그리는 데 3번 왕복. 모바일에서는 치명적

GraphQL의 방식

query {
  user(id: 1) {
    name
    orders(last: 5) {
      totalPrice
      items { productName }
    }
  }
}

{ "data": { "user": { "name": "김철수",
  "orders": [{ "totalPrice": 30000, "items": [{ "productName": "노트북" }] }] } } }

한 번의 요청으로, 요청한 필드만 정확히 받는다.

핵심 개념

스키마가 곧 문서다. 타입이 강제되므로 별도 API 문서 없이도 클라이언트가 무엇을 요청할 수 있는지 안다. 자동 완성·타입 생성도 가능하다.

REST와의 비교

캐시가 어려운 이유 — 가장 큰 실무 부담

REST는 GET /users/1이라는 URL 자체가 캐시 키가 된다. CDN·브라우저·프록시가 알아서 캐시한다.

GraphQL은 POST로 /graphql 한 곳에 보내므로 URL이 구분되지 않는다. → HTTP 캐시 계층을 못 쓴다.

대응 — Persisted Query(쿼리를 미리 등록하고 해시로 호출해 GET 가능하게), Apollo Client의 정규화 캐시, 서버 측 필드 캐시.

N+1 문제 — GraphQL에서 더 심각하다

{ users { name  orders { total } } }

사용자 100명 → 각각 orders를 부르는 리졸버가 100번 호출된다.

DataLoader 패턴으로 해결한다 — 같은 이벤트 루프 틱 안의 요청을 모아 IN (…) 한 번으로 조회한다. 배치 + 캐시를 합친 것으로, GraphQL 서버 구현에서 사실상 필수다.

쿼리 복잡도 제어 — 보안 이슈

{ user { friends { friends { friends { friends { … } } } } } }

클라이언트가 쿼리를 만들 수 있다는 것은 악의적 쿼리도 만들 수 있다는 뜻이다. 중첩을 깊게 만들면 서버가 폭발한다.

• 깊이 제한(depth limit)
• 복잡도 점수 제한(cost analysis)
• 쿼리 화이트리스트(persisted query)
• 타임아웃

언제 쓰나

✅ 클라이언트가 다양하고 각자 필요한 데이터가 다를 때 (웹·앱·파트너) ✅ 화면마다 조합이 자주 바뀌는 프런트엔드 ✅ 여러 마이크로서비스의 데이터를 하나로 묶어 줄 때 (BFF)

❌ 단순 CRUD 위주 ❌ HTTP 캐시가 성능의 핵심인 서비스 ❌ 파일 업로드·스트리밍이 주된 기능 ❌ 팀에 GraphQL 경험이 없고 일정이 촉박할 때

"REST를 대체한다"가 아니라 "이런 문제에 더 맞는다" 로 이해하는 것이 정확하다. 실제로 두 방식을 함께 쓰는 조직이 많다.