GraphQL 성능 튜닝: N+1 문제, DataLoader, Persisted Query로 병목 줄이기

GraphQL 성능 튜닝: N+1 문제, DataLoader, Persisted Query로 병목 줄이기

GraphQL은 필요한 데이터를 정확히 요청할 수 있게 해 주지만, 서버가 자동으로 효율적인 쿼리를 만들어 주는 것은 아니다.

중급 운영에서는 스키마 설계, resolver 호출 패턴, 캐싱, persisted query를 함께 다뤄야 실제 성능이 좋아진다.

왜 지금 이 주제가 중요한가

• N+1 문제는 작은 데이터셋에서는 안 보이다가 실서비스에서 폭발한다.
• 복잡한 쿼리는 DB 병목뿐 아니라 네트워크 payload와 캐시 무효화 비용도 키운다.
• 쿼리 자유도가 높을수록 서버는 guardrail을 명확히 둬야 한다.

핵심 설계 포인트

• resolver는 각각 독립적으로 DB를 때리지 않도록 DataLoader 또는 batch layer를 둔다.
• persisted query를 사용해 쿼리 길이와 캐시 키를 안정화한다.
• depth/complexity 제한을 두어 과도한 쿼리를 차단한다.
• 필드별 비용이 큰 경우 캐시 가능한 읽기 모델을 분리한다.

예시 구성

const userLoader = new DataLoader(async (ids) => {
  const rows = await db.users.findByIds(ids);
  return ids.map((id) => rows.find((row) => row.id === id));
});

적용 순서(실무 플로우)

설계 자체보다도 '작게 도입하고 관측하면서 확장하는 순서'가 운영 성공률을 좌우한다.

1. 상위 10개 GraphQL query와 resolver 호출 패턴을 먼저 측정한다.
2. N+1이 심한 경로에 DataLoader를 적용하고, 배치 키를 설계한다.
3. persisted query를 도입해 캐시와 보안 정책을 단순화한다.
4. complexity limit를 붙이고 운영 알람 기준을 정한다.
5. 쿼리 변경 시 DB 플랜과 payload 크기를 같이 검토한다.

운영 체크포인트

• GraphQL query 이름(operationName)을 로그에 남겨야 병목 분석이 가능하다.
• persisted query 캐시 미스율이 높으면 배포/빌드 파이프라인을 점검한다.
• schema 변경 시 클라이언트 쿼리 수집 데이터를 함께 본다.

운영 지표/알람 추천

• 버전별 트래픽 비율과 미지원 버전 접근 수
• deprecation/sunset 헤더 적용률
• 클라이언트 오류율(4xx)과 호환성 이슈 건수
• 변경 후 고객사별 migration 진행률

빠른 점검 명령/쿼리

curl -I https://example.com/api/resource
curl -H 'Accept: application/vnd.example.v2+json' https://example.com/api/resource
rg 'Sunset|Deprecation|api-version' ./logs -n

구조화 로그 필드 추천

• traceId/requestId/eventId처럼 흐름을 이어주는 키를 남긴다.
• endpoint/topic/flag/version 등 주제별 핵심 차원을 구조화한다.
• 실패 이유(reasonCode)와 재시도 횟수(retryAttempt)를 분리한다.
• 민감정보는 마스킹하고, payload는 샘플링 또는 요약 저장한다.

{
  "level": "INFO",
  "message": "request completed",
  "traceId": "4bf92f...",
  "requestId": "req_123",
  "path": "/api/example",
  "status": 200,
  "latencyMs": 123,
  "reasonCode": null
}

테스트 케이스 샘플

테스트 케이스(최소 3종):
1) 정상: 기대한 성공 경로와 상태 전이가 유지되는지
2) 실패: 다운스트림 오류/잘못된 입력이 예측 가능한 에러로 떨어지는지
3) 동시성/재시도: 같은 요청 또는 이벤트가 반복돼도 부작용이 없는지

추가(가능하면):
- 장애 복구: 프로세스 재시작 후 중간 상태를 정상 회복하는지
- 부하: p95/p99와 queue/pool saturation이 임계값 안에 드는지

트레이드오프/대안

• 운영 복잡도를 줄이면 기능 유연성이 떨어질 수 있고, 반대도 마찬가지다.
• 기본값은 출발점일 뿐이다. 실제 트래픽과 실패 패턴을 보고 다시 조정해야 한다.
• 관측 없이 최적화하면 체감 개선과 회귀를 구분하기 어렵다.
• 팀 경계가 많은 시스템일수록 인터페이스 계약과 문서가 코드만큼 중요하다.

성공 기준(SLO) 예시

• 핵심 경로 에러율: 0.1% 이하
• 핵심 요청/이벤트 p95 지연: 서비스 목표 내 유지
• 중복 실행 또는 데이터 유실: 0건
• 장애 감지 후 임시 조치까지 걸리는 시간: 10분 이내

자주 터지는 실수/트러블슈팅

1. DataLoader를 전역 싱글턴으로 둔다: 요청 간 캐시 오염이 생길 수 있다.
2. 복잡도 제한 없이 외부 공개 GraphQL을 연다: 비용 예측이 어려워진다.
3. persisted query를 도입하면서 버전 관리가 없다: 배포 직후 미스가 늘어난다.

바로 적용 템플릿

GraphQL 성능 템플릿:
operationName 로깅
요청 스코프 DataLoader
persisted query + hash registry
depth/complexity limit

검증 방법

• 같은 쿼리에서 resolver 호출 횟수가 DataLoader 전후로 줄었는지 확인한다.
• persisted query 강제 후 미등록 쿼리가 적절히 차단되는지 검증한다.

장애 대응 Runbook(초안)

• 현상: 어떤 사용자/서비스/플랫폼에서 무엇이 깨졌는지 한 문장으로 정리한다.
• 범위: 언제부터 시작됐고, 영향받은 비율과 핵심 경로를 적는다.
• 증거: 로그 3줄, 지표 1개, 최근 배포/설정 변경 1개를 먼저 모은다.
• 임시 조치: 차단, 롤백, 스위치 전환, 재시도 제한 중 무엇을 할지 결정한다.
• 근본 원인: 계약, 타임아웃, 락, 캐시, 버전, 운영 절차 중 어디가 깨졌는지 좁힌다.
• 재발 방지: 테스트, 알람, 문서, 기본값을 함께 수정한다.

리뷰 체크리스트

1. 실패 시나리오가 문서와 코드에서 같은 의미로 정의돼 있다.
2. 타임아웃/재시도/락/캐시 같은 보호 장치가 상호 충돌하지 않는다.
3. 관측 지표와 상관관계 키가 있어 운영 중 재현이 가능하다.
4. 롤백 또는 비상 스위치가 준비돼 있다.
5. 최소 1개 이상의 동시성/부하/중간 실패 테스트가 자동화돼 있다.
6. 공식 문서 링크와 팀 의사결정 근거가 남아 있다.

팀 문서 템플릿

팀 문서 템플릿(복붙용):
1) 목표/배경: 어떤 운영 비용 또는 장애를 줄이려는가
2) 범위: API/잡/토픽/디바이스/리전 중 어디까지 적용하는가
3) 규칙: 키, 상태, 버전, TTL, timeout, retry 기본값
4) 예외: 허용하지 않는 상황과 에러 코드/조치 기준
5) 운영: 대시보드, 알람, 소유 팀, 점검 주기
6) 장애 대응: 임시 조치, 롤백, 후속 공지 절차
7) 변경 이력: 언제 누가 왜 기본값을 바꿨는가

FAQ(자주 묻는 질문)

Q. 처음부터 완벽하게 설계해야 하나요?
A. 아니다. 핵심 경로 1개부터 적용하고, 운영 지표를 보며 기본값을 보정하는 편이 실제로 더 안전하다.

Q. "GraphQL 성능 튜닝: N+1 문제, DataLoader, Persisted Query로 병목 줄이기"를 도입했는데도 문제가 남아 있습니다. 어디부터 봐야 하나요?
A. 먼저 상관관계 키가 있는 로그와 지표로 실패 범위를 좁히고, 최근 배포/설정 차이를 확인한다. 대부분은 기본값보다 경계 조건에서 터진다.

Q. 팀 합의가 자꾸 흔들립니다. 무엇을 문서로 남겨야 하나요?
A. 상태 전이, 기본값, 예외 처리, 롤백 기준 네 가지는 반드시 남겨야 한다. 이 네 가지가 없으면 장애 때 판단이 흔들린다.

참고/출처

• GraphQL Learn
• Apollo Persisted Queries