GraphQL Subscription이란? 원하는 이벤트·필드만 구독하기

Query · Mutation 에 이은 세 번째 작업 — 안쪽은 WebSocket

GraphQL Subscription은 Query/Mutation과 함께 GraphQL의 세 번째 작업 타입입니다. 내부적으로 WebSocket을 transport로 사용하며, GraphQL 스키마에 정의된 타입 시스템을 통해 어떤 이벤트를 구독할지, 어떤 필드를 받을지를 선언적으로 지정할 수 있습니다.

구조 다이어그램

🌐

클라이언트

subscription {
  messageAdded {
    id
    text
  }
}

① subscription 쿼리 →

WebSocket

← ④ 데이터 push

🖥️

GraphQL 서버

② 구독 등록

③ Mutation 발생 ←

✏️

Mutation

데이터 변경 트리거

흐름 설명

클라이언트가 subscription 쿼리 전송 (WebSocket 연결)
서버가 해당 이벤트에 대한 구독 등록
다른 클라이언트/시스템에서 Mutation으로 데이터 변경
서버가 구독 중인 클라이언트에 GraphQL 형식으로 push

동작 흐름

클라이언트가 subscription 쿼리를 서버에 전송 (WebSocket 연결)

서버가 해당 이벤트에 대한 구독 등록

서버 측에서 데이터 변경(Mutation) 발생

서버가 구독 중인 클라이언트에 GraphQL 형식으로 데이터 push

장점

✓ 타입 안전한 실시간 통신
✓ 필요한 필드만 선택적 구독
✓ 기존 GraphQL 스키마와 통합
✓ Query/Mutation과 일관된 개발 경험

단점

✗ WebSocket 위에 추가 추상화 계층
✗ 서버 구현 복잡도 높음
✗ N+1 구독 문제 가능
✗ 스케일링 시 Pub/Sub 백엔드 필요

사용 사례

실시간 댓글/알림 주문 상태 추적 협업 도구 실시간 동기화 GitHub의 GraphQL API