GraphQL — 도메인 홈
이 도메인이 답하는 질문: “REST가 있는데 왜 GraphQL이 등장했고, 어떻게 동작하며, 언제 쓰지 말아야 하나?” 한 줄 답 (Pyramid Top): “GraphQL은 클라이언트가 필요한 모양을 한 번에 선언하면 서버가 그 모양 그대로 돌려주는 그래프 질의 언어다 — 단일 엔드포인트 위에 강타입 스키마를 얹어 over-fetching/under-fetching과 N개 endpoint 문제를 한꺼번에 해결한다.”
도메인 지도 (5-레이어)
어떤 챕터가 들어 있나
| # | 챕터 | 한 줄 답 | 핵심 키워드 |
|---|---|---|---|
| 00 | 기초 | GraphQL은 RPC도 REST도 아닌 그래프 질의 언어다. | 2012 Meta · over-fetching · single endpoint · spec |
| 01 | 스키마 & SDL | 스키마는 클라이언트와 서버 사이의 강제 가능한 계약이다. | SDL · type · interface · union · directive |
| 02 | 실행 & 리졸버 | 리졸버는 필드 단위 함수의 트리고, 실행은 그 트리의 깊이 우선 평가다. | resolver · context · execution tree · partial error |
| 03 | N+1 & DataLoader | N+1은 GraphQL의 본질이고, DataLoader는 그것을 단일 tick에서 batch + cache로 흡수한다. | N+1 · batch · cache · dataloader |
| 04 | 전송 계층 | GraphQL은 전송과 무관하다 — POST/GET/WebSocket/SSE/multipart가 모두 가능하다. | HTTP · graphql-over-ws · SSE · multipart upload |
| 05 | 캐시 & 성능 | GraphQL은 URL이 없어 HTTP 캐시가 어렵다 — 그래서 클라이언트 정규화 캐시와 persisted query가 등장했다. | normalized cache · APQ · response cache · ETag |
| 06 | Federation | 한 회사의 거대 그래프를 여러 팀이 나눠 가지려면 subgraph + supergraph가 필요하다. | Apollo Federation v2 · @key · @shareable · stitching |
| 07 | 보안 & 거버넌스 | GraphQL은 공격 면적이 query 자체다 — depth·complexity·introspection을 제어해야 한다. | depth limit · complexity · auth · linting |
| 08 | 이론 & 대안 | GraphQL이 만능은 아니다 — REST·gRPC·tRPC가 더 적합한 자리가 있다. | REST · gRPC · tRPC · BFF · 적합성 |
| 09 | 실전 사례 | Meta·GitHub·Shopify·Netflix가 같은 도구를 전혀 다르게 쓰고 있다. | Meta · GitHub · Shopify · Netflix · Airbnb |
| ★ | 용어 사전 | 100+ 용어 사전. | SDL · DataLoader · APQ · subgraph |
Why — 왜 GraphQL 도메인을 한 묶음으로 보는가
세 가지 잘못된 직관이 거의 모든 GraphQL 사고의 출처다.
| 잘못된 직관 | 실제 | 어디서 다루나 |
|---|---|---|
| ”GraphQL은 REST의 대체다” | RPC도, REST도 아니다. 그래프 질의 언어다. | 00 |
| ”스키마는 문서다” | 스키마는 런타임 강제력을 가진 계약이다. | 01 |
| ”GraphQL이 느린 건 GraphQL 탓이다” | 99%는 N+1이고, 그건 DataLoader로 해결한다. | 03 |
이 도메인을 5-레이어로 보면 — Schema가 약속을 정하고, Execution이 그것을 평가하며, Transport가 운반하고, Cache가 비용을 낮추고, Federation이 조직을 묶는다. 각 레이어가 자기 책임 영역의 문제만 갖는다.
How — 어떻게 읽나
- 처음 GraphQL을 만나는 사람: 00 → 01 → 02 → 03 순서. 4시간이면 운영 가능한 멘탈모델이 잡힌다.
- 이미 쓰고 있는데 N+1로 고통받는 사람: 03만 봐도 된다. 그 다음 04(transport)로.
- 마이크로서비스에서 그래프를 통합하려는 사람: 06(Federation) → 07(보안) → 09(Netflix 사례).
- GraphQL을 도입할지 결정해야 하는 사람: 00 → 08(대안 비교) → 09(사례). 결정 시간 1시간.
What — 도메인 한 페이지 요약
| 챕터 | 한 줄 결론 |
|---|---|
| 00 | GraphQL은 쿼리 언어이고, 런타임이 아니다. 스키마/실행/전송이 분리되어 있다. |
| 01 | SDL은 type system이 강제하는 API 계약이다. 디렉티브는 메타데이터가 아니라 동작 변경자다. |
| 02 | 리졸버는 필드 함수의 트리고, GraphQL의 응답 시간은 가장 느린 리졸버의 깊이에 비례한다. |
| 03 | N+1은 GraphQL의 고유 문제가 아니라 드러나기 쉬운 문제다. DataLoader가 사실상 표준 해결책. |
| 04 | GraphQL은 전송 무관하다 — HTTP가 가장 흔하지만 WS(subscription)·SSE(stream)·multipart(upload)가 모두 표준이다. |
| 05 | HTTP 캐시가 안 듣는 자리는 클라이언트 정규화 캐시가 채운다. Persisted Query가 그 위에서 네트워크 비용을 낮춘다. |
| 06 | 모놀리식 그래프는 조직적으로 깨진다 — Federation은 팀 단위 subgraph를 하나의 supergraph로 합성한다. |
| 07 | 공격 면적이 쿼리 자체이므로 depth · complexity · introspection · auth를 서버에서 강제해야 한다. |
| 08 | REST는 리소스가 안정적일 때, gRPC는 서버-서버 강타입일 때, GraphQL은 클라이언트가 모양을 매번 다르게 원할 때. |
| 09 | Meta는 모바일, GitHub은 공개 API, Shopify는 상점, Netflix는 스튜디오 — 같은 도구가 다른 문제를 푼다. |
What-if — 이 도메인을 단편적으로만 알면
- Schema만 알고 Execution을 모르면: N+1로 프로덕션 DB가 죽는다.
- Execution만 알고 Cache를 모르면: 같은 화면에서 같은 데이터를 매번 재요청한다.
- Cache만 알고 Federation을 모르면: 한 팀이 모든 그래프를 소유하다 조직 병목이 된다.
- Federation만 알고 Security를 모르면: 한 subgraph의 복잡 쿼리 한 방이 전체 supergraph를 마비시킨다.
Insight — 한 단락 이야기
“GraphQL은 2012년 Facebook의 iOS 앱이 너무 느려서 태어났다”
Lee Byron, Dan Schafer, Nick Schrock 세 사람은 RESTful API가 모바일 화면 한 개를 그리기 위해 N번을 호출하는 것을 보고 — “차라리 클라이언트가 원하는 모양을 통째로 보내라”는 단순한 아이디어를 냈다. 3년 뒤 그것이 spec이 되었고, GitHub이 공개 API v4로 채택하면서 사실상 표준이 되었다. 추상화의 출발은 모바일 앱의 화면 한 장이었지만, 도착지는 마이크로서비스 시대의 API 게이트웨이 패러다임이다 — 이 도메인이 하는 일은 그 출발과 도착 사이의 다섯 층을 분해하는 것.
Mermaid 4색 규약
이 도메인의 모든 다이어그램은 다음 색을 따른다.
색은 역할이고 모양은 의미다 — 다른 도메인과도 일관된다.
한 단락 요약
GraphQL은 클라이언트가 모양을 선택하는 그래프 질의 언어다. 그 위에 스키마(약속) · 실행(평가) · 전송(운반) · 캐시(절약) · 페더레이션(조직) 다섯 층이 쌓여 있다. 이 도메인을 끝내면 “GraphQL 써야 하나?”라는 질문 대신 “우리 문제는 어느 레이어에 있나?” 라는 질문을 던지게 된다.