GraphQL 잘 쓰고 계신가요? (Production-ready GraphQL)

발표의 뼈대를 스키마 → 스칼라/리졸버 → 프래그먼트 순으로 잡은 뒤, 가장 중요한 스키마의 의미부터 다시 세운다. 스키마의 어원은 그리스어로 "모양·형태"이고, 데이터 레이어에서는 "우리가 다룰 데이터의 모양"이다. 다만 결정적인 차이가 있다. 데이터베이스 스키마가 스토리지의 읽기·쓰기 최적화를 목표로 설계된다면, GraphQL 스키마는 철저히 그 API를 "사용하는 입장", 즉 클라이언트의 시선에서 그려져야 한다.

리뷰 페이지가 그 예다. 화면에 실제로 보이는 데이터 구조를 기준으로 리뷰 타입, 그 안의 리뷰 내용 타입, 방문 정보 타입을 연결해 스키마를 짠다. 텍스트 리뷰 한 줄을 그리는 데에도 닉네임·썸네일은 유저 DB에서, 리뷰 텍스트는 리뷰 API에서 와야 하지만, 클라이언트는 그 출처를 알 필요가 없다. GraphQL이 이 복잡한 데이터 조합을 대신 처리해 주기에, 클라이언트는 화면에 필요한 필드만 선언적으로 요청하면 된다. 결국 스키마를 클라이언트 중심으로 짠다는 말은, GraphQL을 "데이터가 어디서 오는지를 감추는 클라이언트 중심의 레이어"로 본다는 뜻이다. 이 관점이 이후 모든 사례의 출발점이 된다.

클라이언트 중심 스키마라는 원칙을 실제 코드로 증명하는 두 사례가 이어진다. 공통된 적은 "API 제공자의 관점이 그대로 새어 나온 스키마"다.

첫 사례는 이미지 리사이징이다. 메인 화면에는 60px 유저 썸네일과 42px 리뷰 썸네일이 있고 이미지 서버는 리사이즈된 URL을 내려준다. 이를 소박하게 옮기면 프로필에 60px 필드, 리뷰에 42px 필드를 각각 두게 되는데, 같은 썸네일인데도 지면이 늘 때마다 사이즈별 필드가 끝없이 불어난다. 근본 해법은 클라이언트가 원하는 크기를 직접 선언하게 하는 것, 즉 필드 아규먼트로 사이즈를 인자로 받아 해당 URL을 리턴하는 것이다. 다만 정수로 받으면 스키마만 봐서는 어떤 사이즈를 지원하는지 알 수 없으니, 지원 사이즈를 멤버로 가진 이넘 타입을 도입하고 기본값(42px)도 지정한다. 그러면 클라이언트는 GraphiQL 같은 IDE에서 지원 사이즈를 정확히 확인하고 실수 없이 요청할 수 있고, 흩어진 썸네일 필드들이 하나의 이미지 필드로 압축된다.

둘째 사례는 "암시적인 파라미터를 명시적으로" 바꾸는 이야기다. 장소 페이지의 "사진 리뷰만" 버튼을 위해 API 문서의 boolean 파라미터 `hasMedia`를 썼는데, 켜면 사진 리뷰·끄면 사진 없는 리뷰일 거라는 기대와 달리 실제로는 true면 사진 리뷰, false면 텍스트 리뷰, 값이 없어야 전체가 오는 비직관적 동작이었다. 전형적인 제공자 관점 설계다. 여기서도 답은 이넘이다. `WITH_MEDIA`·`WITHOUT_MEDIA`·`ALL` 같은 멤버를 가진 미디어 필터를 만들어 쿼리에 인자 하나로 붙이고 기본값을 전체로 둔다. 두 사례가 함께 말하는 핵심은, 값이 "없을 때"의 상태조차 의미가 있다면 이넘으로 명시화해 사용자 관점에서 더 명확하고 유연한 스키마로 끌어올릴 수 있다는 것이다.

마지막 묶음은 프론트에서 가장 까다로운 문제들을 차례로 타입의 세계로 끌어올린다. 시작은 에러 핸들링이다. 닉네임 변경은 중복 검사와 금칙어 검사를 동시에 하는데, GraphQL 응답은 모두 200이라 HTTP 상태 코드로 분기할 수 없고, errors 필드에 코드를 담아도 타입이 없어 클라이언트가 신뢰하기 어렵다. 그래서 에러를 errors가 아니라 "데이터"로 스키마에 담되, 성공일 때 무의미한 필드가 한 타입에 뒤섞이는 문제를 유니언 타입으로 푼다. 결과를 "성공 | 중복 에러 | 금칙어 에러"로 리턴하는 것이다.

클라이언트는 이 유니언을 인라인 프래그먼트로 소비해 타입별로 필요한 필드만 받는다. 다만 배포 후 새 에러 타입이 추가되면 기존 쿼리가 그것을 몰라 아무 데이터도 못 받는, 확장에 닫힌 구조가 된다. 이를 메시지 필드를 가진 BaseError 인터페이스로 풀어, 클라이언트가 인터페이스 수준에서 메시지를 미리 요청해 두면 모르던 새 에러도 인지하게 만든다. 유니언과 인터페이스를 함께 써 명시적이면서도 유연한 에러 핸들링이 완성된다.

이어 타입 안전성을 더 좁히는 커스텀 스칼라가 나온다. 이메일·전화번호·URL·ISO 날짜는 모두 String보다 좁은 집합이므로 전용 스칼라로 표현하고, 스칼라는 타입 시스템의 리프 노드로서 `serialize`와 `parseValue` 함수로 직렬화와 유효성 검사를 맡는다(흔한 것들은 graphql-scalars 라이브러리로 대체 가능). 그다음 필드 리졸버는 리뷰 노출 조건처럼 여러 클라이언트가 기억해야 할 비즈니스 로직을 NestJS 같은 코드 퍼스트 환경에서 서버로 호이스팅하며, 요청할 때만 계산하므로 성능에도 유리하다.

끝으로 캐시와 프래그먼트다. 팔로우 후 UI 갱신처럼 프로필은 me 쿼리로, 피드 탭은 페이지네이션 쿼리로 그려진 상황에서 수동 스토어 갱신이나 리패치는 유지보수·트래픽 문제를 낳는다. Apollo Client의 정규화는 타입 이름과 ID를 캐시 키로 삼아 데이터를 레퍼런스로 저장하고 갱신을 그 데이터를 쓰는 모든 컴포넌트의 리렌더로 전파하므로, 뮤테이션 응답에 갱신할 필드만 잘 셀렉션하면 UI가 자동으로 따라온다. 마지막으로 데이터를 쓰는 곳과 부르는 곳의 거리에서 생기는 변경 어려움을, 컴포넌트가 스스로 데이터 의존성을 선언해 상향식으로 합치는 프래그먼트 콜로케이션으로 푼다. 이것이 Relay의 탄생 배경이기도 하며, 결국 GraphQL의 잠재력은 DX 향상으로 이어진다는 메시지로 발표를 맺는다.