GraphQL
GraphQL
GraphQL이란?
- 필요한 데이터만 골라 한 번에 요청
- 과다·과소 응답 문제 해결
- REST의 대안
GraphQL을 얹으면 '어떤 데이터를 줄지' 결정하는 권한이 서버에서 클라이언트로 넘어옵니다. REST에서는 화면이 하나 바뀔 때마다 프런트엔드가 백엔드에 새 엔드포인트를 요청하고 배포 일정을 기다려야 했지만, GraphQL에서는 스키마에 정의된 필드 범위 안에서 쿼리만 고쳐 쓰면 그날 바로 화면이 바뀝니다. 팀 간 대기 시간이 사라지는 것이 현장에서 가장 먼저 체감하는 변화입니다. 대신 스키마를 설계하고 버전을 관리하는 책임이 백엔드의 새 업무로 추가됩니다.
엔드포인트는 보통 /graphql 하나이고, 연산은 조회(Query)·변경(Mutation)·실시간 구독(Subscription) 세 가지로 나뉩니다. REST와 갈라지는 결정적 지점은 캐싱입니다. REST는 URL 단위로 CDN과 브라우저 캐시를 그대로 쓰지만, GraphQL은 한 주소로 POST가 오가기 때문에 HTTP 캐시를 사실상 못 씁니다. 아폴로 같은 클라이언트 캐시나 영속 쿼리를 따로 붙여야 하고, 오류도 HTTP 200 응답 본문에 담겨 오므로 상태 코드로 장애를 잡던 모니터링은 처음부터 다시 짜야 합니다.
도입 판단 기준은 의외로 단순합니다. 화면 하나를 그리는 데 API를 3~4개 이상 연달아 호출하고, 웹·iOS·안드로이드처럼 클라이언트가 셋 이상일 때 효과가 큽니다. 반대로 관리자 화면 위주에 엔드포인트가 20개 남짓인 서비스라면 REST가 유지보수 비용이 훨씬 쌉니다. 전면 교체 대신 BFF 층에만 GraphQL을 올려 기존 REST를 감싸는 절충안이 국내에서는 더 흔합니다.
가장 흔한 오해는 '한 번에 받으니 무조건 빠르다'는 말입니다. 서버 안에서는 게시글 20건마다 작성자를 따로 조회하는 N+1 호출이 그대로 일어나, 데이터로더 없이 열면 DB 커넥션이 먼저 바닥납니다. 클라이언트가 중첩 깊이를 마음대로 지정할 수 있다는 점도 위험해서 깊이·복잡도 제한을 걸지 않으면 쿼리 한 방으로 서버가 멈춥니다. 권한도 URL이 아니라 필드 단위로 검사해야 하는데, 이걸 놓쳐 연봉이나 개인 연락처 필드가 그대로 노출되는 사고가 실제로 납니다.
페이스북이 2012년 내부적으로 개발하고 2015년 공개한 API 질의 언어로, 클라이언트가 필요한 데이터를 정확히 요청하는 방식을 표준화했습니다.
가상의 사례로 살펴보겠습니다. 임직원 320명, 연매출 1,800억 원 규모의 패션 이커머스 A사입니다. 앱 상품 상세 화면 하나를 띄우는 데 REST API를 7번 호출하다 보니 로딩이 평균 2.8초까지 늘어졌고, 기획이 바뀔 때마다 엔드포인트를 새로 파느라 배포가 2주씩 밀렸습니다. CTO가 3개월짜리 개선 과제를 붙였습니다.
- 모바일개발팀 김 리드가 진입 로그를 뽑아 보니 상품 상세 한 화면에 호출이 7번, LTE 환경 평균 로딩 2.8초, 첫 화면 이탈률이 18%로 나왔습니다.
- 백엔드 파트장이 "화면마다 엔드포인트를 파면 관리할 주소가 200개를 넘는다"고 반대해, 기존 REST는 두고 BFF 층에 GraphQL 게이트웨이를 얹는 안으로 정리했습니다.
- 첫 4주간 상품·리뷰·재고 세 도메인만 스키마로 옮겼는데, 리뷰 목록에서 작성자를 건별로 조회하는 N+1이 터져 데이터로더를 붙이고 DB 호출을 50건에서 3건으로 줄였습니다.
- 오픈 2주 차에 제휴사 한 곳이 중첩 6단계 쿼리를 던져 API 서버 CPU가 92%까지 치솟자, 쿼리 깊이 5·복잡도 1,000 제한과 영속 쿼리를 그날 밤 적용했습니다.
- 3개월 뒤 상품 상세 호출은 7번에서 1번, 평균 로딩은 2.8초에서 1.1초로 줄었고, 화면 수정 때문에 백엔드 배포를 기다리던 건수가 월 11건에서 2건으로 떨어졌습니다.