00-foundations

이 챕터가 답하는 질문: GraphQL은 도대체 무엇이고, REST/RPC와 어떻게 다르며, 왜 등장했는가? 한 줄 답 (Pyramid Top): “GraphQL은 RPC도 REST도 아닌, 클라이언트가 응답의 모양을 선언하는 그래프 질의 언어다.”

한 문장 답 (Pyramid Top)

GraphQL이라는 단어는 두 개의 다른 것을 동시에 가리킨다 — ① 타입 시스템을 가진 질의 언어 사양(query language)과 ② 그 사양을 해석해 응답을 만들어내는 실행 엔진(execution runtime). 이 챕터는 둘을 분리해서 이름을 붙이고, REST와 어떻게 다른지, 왜 2012년 Facebook에서 태어났는지를 한 층씩 벗긴다.

챕터 지도 (Mermaid)

Why — 왜 이 챕터부터 시작하나

“GraphQL은 Facebook이 만든 REST 대체재”라는 한 줄 정의가 거의 모든 오해의 출발점이다. 이 정의는 세 가지를 동시에 틀린다 — Facebook이 만든 것은 맞지만 지금은 GraphQL Foundation이 관리하고, REST의 대체재가 아니라 다른 문제를 푸는 도구이며, 언어와 런타임은 별개로 분리되어 있다.

상위 챕터에서 만나게 될 거의 모든 헷갈림이 여기서 출발한다.

• “왜 /graphql endpoint 하나만 있을까?” → 01-what-is-graphql.mdx
• “왜 우리 회사는 REST를 쓰는데 다른 회사는 GraphQL을 쓸까?” → 03-graphql-vs-rest.mdx
• “이 쿼리 안의 $id는 뭐고 ...UserFields는 뭐지?” → 04-anatomy-of-a-query.mdx
• “응답이 왜 요청과 똑같은 모양으로 오지?” → 05-mental-model.mdx

이 챕터는 ‘GraphQL’이라는 단어 안에 숨어 있는 5개의 분리된 개념에 각각 이름을 붙인다. 이름을 붙이고 나면, 위 질문들이 자동으로 풀린다.

How — 어떻게 읽나

다음 5개 문서를 순서대로 읽으면 한 시간 정도 걸린다. 각 문서는 독립적으로 읽혀도 되지만, 순서가 누적적이다.

의존성: 02는 01을, 03은 01을, 04는 0103을 가정한다. 05는 14 모두를 통합한다.

What — 한 페이지 요약 (모든 문서의 핵심 한 줄)

What-if — 이 챕터를 건너뛰면

• 언어와 런타임을 혼동하면: Apollo Server를 “GraphQL”이라고 부르며 Apollo가 사라지면 GraphQL도 끝난다고 오해한다. 런타임은 수십 개, 언어는 하나다.
• REST의 대체재로만 보면: 모든 endpoint를 /graphql로 옮긴 뒤, 캐싱·rate limit·관측이 모두 깨진 채 production에 올린다.
• 응답 동형성을 모르면: 클라이언트가 null을 보면서 “이건 에러인가 빈 값인가”를 분간 못 한다 — partial response는 기능이지 버그가 아니다.

Insight — 한 단락 이야기

“GraphQL은 facebook.com 모바일 앱의 N+1 사고에서 태어났다”

2012년 봄, Facebook은 자사 iOS 앱을 HTML5 wrapper에서 네이티브로 전환하고 있었다. 문제는 News Feed였다 — 한 화면을 그리려면 REST를 수십 번 호출해야 했고, 그 사이 셀룰러 네트워크에서 사용자는 빈 화면을 보고 있었다. Nick Schrock·Dan Schafer·Lee Byron 세 사람이 “응답의 모양을 클라이언트가 선언하면 되지 않나”라는 아이디어를 SuperGraph라는 이름의 프로토타입으로 만들었고, 2012년 8월 iOS 앱에 실렸다. 3년 뒤인 2015년에 오픈소스로 풀렸을 때 GraphQL은 이미 Facebook 모바일 트래픽의 거의 전부를 받아내고 있었다. 추상화의 이름은 가벼웠지만, 그 위에 쌓인 표준은 무겁다. — 이 챕터가 하는 일은 그 무게의 출발점을 다섯 층으로 분해하는 것.

한 단락 요약

GraphQL은 질의 언어(01) 위에 역사와 표준(02), REST와의 비교(03), 문법 해부(04), 멘탈 모델(05)이 차례로 쌓인 구조다. 이 챕터를 끝내면 “GraphQL이 뭐냐”라는 질문 대신 *“내 문제에서 응답의 모양이 가변적인가, 리소스가 고정인가”*라는 질문을 던지게 된다. 다음 챕터(01-schema-sdl)는 이 언어로 타입을 어떻게 정의하는지를 다룬다.