콘텐츠 대표 이미지 - GraphQL과 Apollo Client를활용한 데이터 페칭
🚀 JavaScript · 프로그램개발

GraphQL과 Apollo Client를
활용한 데이터 페칭

REST API의 한계를 넘어서, 더 스마트하게 데이터를 가져오는 법 🎯
📋 목차
1. GraphQL이 뭔데? REST API랑 뭐가 달라? 2. GraphQL 핵심 개념 완전 정복 3. Apollo Client 소개 및 설치 4. Apollo Client 기본 설정하기 5. Query로 데이터 가져오기 6. Mutation으로 데이터 변경하기 7. Subscription으로 실시간 데이터 받기 8. Apollo Client 캐싱 전략 9. 에러 핸들링과 로딩 상태 관리 10. 실전 프로젝트 패턴과 최적화

1. GraphQL이 뭔데? REST API랑 뭐가 달라? 🤔

자, 친구야! 개발하다 보면 이런 경험 한 번쯤 있지 않아? 🙋

백엔드한테 "유저 이름이랑 프로필 사진만 주세요~" 했더니, 돌아오는 응답은 유저의 생년월일, 주소, 전화번호, 가입일, 마지막 로그인 시간, 친구 목록까지 한 트럭이 날아오는 거야. 😅
이게 바로 REST API의 고질적인 문제인 Over-fetching이야.

반대로 이런 경우도 있어. 게시글 목록 페이지를 만드는데, 게시글 정보 API 하나로는 작성자 이름을 못 가져와서 유저 API를 또 따로 호출해야 하는 상황. 이게 Under-fetching이고, 이 때문에 API를 여러 번 호출하는 N+1 문제가 생기지.

REST API vs GraphQL 비교 REST API 방식 클라이언트 /api/users /api/posts /api/comments ⚠ 여러 번 요청 필요! Over/Under-fetching 발생 N+1 문제 발생 가능 불필요한 데이터 수신 엔드포인트 관리 복잡 GraphQL 방식 클라이언트 /graphql 단일 엔드포인트 필요한 데이터만 정확히 요청 ✅ 한 번의 요청으로 해결! 정확한 데이터만 수신 타입 시스템으로 안전 자동 문서화 지원 실시간 구독 기능 내장

GraphQL은 2012년 Facebook(현 Meta)이 내부적으로 개발하고, 2015년에 오픈소스로 공개한 API를 위한 쿼리 언어야. 단순히 데이터를 가져오는 방법이 아니라, 클라이언트가 원하는 데이터의 구조를 직접 정의해서 요청하는 완전히 새로운 패러다임이지.

💡 GraphQL의 핵심 철학: "클라이언트가 필요한 것을 정확히 요청하고, 그것만 받는다."
하나의 엔드포인트(/graphql)에서 모든 요청을 처리하며, 요청 형태에 따라 응답이 달라져.
🔵 REST API

여러 엔드포인트
고정된 응답 구조
Over/Under-fetching
버전 관리 필요 (v1, v2...)
문서 별도 작성 필요

🟣 GraphQL

단일 엔드포인트
유연한 응답 구조
정확한 데이터 요청
버전 관리 불필요
자동 문서화 (Introspection)


2. GraphQL 핵심 개념 완전 정복 📚

GraphQL을 제대로 쓰려면 세 가지 핵심 개념을 알아야 해. 이걸 모르면 Apollo Client 써도 반쪽짜리야! 😤

🔷 Schema와 Type System

GraphQL의 모든 것은 스키마(Schema)에서 시작해. 스키마는 API가 제공하는 데이터의 타입과 구조를 정의하는 계약서야. SDL(Schema Definition Language)이라는 문법을 사용해.

# GraphQL 스키마 예시 (SDL)
type User {
  id: ID!
  name: String!
  email: String!
  age: Int
  posts: [Post!]!
  createdAt: String!
}

type Post {
  id: ID!
  title: String!
  content: String!
  author: User!
  likes: Int!
  published: Boolean!
}

type Query {
  user(id: ID!): User
  users: [User!]!
  post(id: ID!): Post
  posts(limit: Int, offset: Int): [Post!]!
}

type Mutation {
  createUser(name: String!, email: String!): User!
  updateUser(id: ID!, name: String): User!
  deleteUser(id: ID!): Boolean!
  createPost(title: String!, content: String!, authorId: ID!): Post!
}

type Subscription {
  postAdded: Post!
  userOnline(userId: ID!): User!
}
⚡ 느낌표(!)의 의미: GraphQL에서 !는 "Non-null"을 의미해. String!은 절대 null이 될 수 없다는 뜻이고, [Post!]!는 배열 자체도 null이 아니고 배열 안의 각 요소도 null이 아니라는 뜻이야.

GraphQL의 기본 스칼라 타입들은 이렇게 있어:

Int Float String Boolean ID 커스텀 스칼라 (Date, JSON 등)

🔷 Query - 데이터 읽기

Query는 REST의 GET 요청과 비슷해. 데이터를 읽기만 할 때 사용해. 근데 REST랑 다른 점은, 내가 원하는 필드만 골라서 요청할 수 있다는 거야!

# 기본 Query
query GetUser {
  user(id: "1") {
    id
    name
    email
    # age는 필요없으니까 요청 안 함!
    posts {
      title
      likes
    }
  }
}

# 응답 결과
{
  "data": {
    "user": {
      "id": "1",
      "name": "김철수",
      "email": "chulsoo@example.com",
      "posts": [
        { "title": "GraphQL 입문기", "likes": 42 },
        { "title": "Apollo Client 정복", "likes": 87 }
      ]
    }
  }
}

여러 쿼리를 한 번에 보낼 수도 있어. 이게 진짜 GraphQL의 강점이야! 🎯

# 여러 데이터를 한 번에 요청 (REST라면 API 2번 호출해야 함)
query GetDashboardData {
  users {
    id
    name
  }
  posts(limit: 5) {
    title
    author {
      name
    }
    likes
  }
}

🔷 Mutation - 데이터 변경

Mutation은 REST의 POST, PUT, DELETE에 해당해. 데이터를 생성, 수정, 삭제할 때 사용해.

# Mutation 예시
mutation CreateNewPost($title: String!, $content: String!, $authorId: ID!) {
  createPost(title: $title, content: $content, authorId: $authorId) {
    id
    title
    author {
      name
    }
    createdAt
  }
}

# Variables (변수)
{
  "title": "GraphQL 완전 정복!",
  "content": "오늘은 GraphQL을 배워보자...",
  "authorId": "1"
}

🔷 Subscription - 실시간 데이터

Subscription은 REST에는 없는 GraphQL만의 특별한 기능이야! WebSocket을 통해 서버에서 클라이언트로 실시간 데이터 푸시가 가능해. 채팅 앱, 실시간 알림, 라이브 업데이트 같은 기능에 딱이지.

# Subscription 예시
subscription OnPostAdded {
  postAdded {
    id
    title
    author {
      name
    }
    likes
  }
}

# 서버에서 새 게시글이 추가될 때마다 자동으로 데이터가 날아와!

🔷 Fragment - 재사용 가능한 쿼리 조각

Fragment는 쿼리의 일부를 재사용 가능한 조각으로 만드는 기능이야. DRY(Don't Repeat Yourself) 원칙을 GraphQL에서 실현하는 방법이지!

# Fragment 정의
fragment UserBasicInfo on User {
  id
  name
  email
}

# Fragment 사용
query GetUsers {
  users {
    ...UserBasicInfo
    posts {
      title
    }
  }
}

query GetSingleUser($id: ID!) {
  user(id: $id) {
    ...UserBasicInfo
    age
    createdAt
  }
}
GraphQL 핵심 개념 구조도 Schema 타입 시스템 Query 데이터 읽기 (R) GET과 유사 Mutation 데이터 변경 (CUD) POST/PUT/DELETE Subscription 실시간 데이터 WebSocket 기반 Fragment 재사용 쿼리 조각 DRY 원칙 적용 모든 요청은 단일 엔드포인트 /graphql 로 전송 클라이언트가 원하는 데이터 구조를 직접 정의 타입 시스템으로 컴파일 타임에 오류 감지 가능

3. Apollo Client 소개 및 설치 🛸

GraphQL 쿼리를 직접 fetch로 날릴 수도 있지만, 그러면 캐싱, 에러 처리, 로딩 상태 관리, 실시간 구독 등을 전부 직접 구현해야 해. 그게 얼마나 고통스러운 일인지는... 해본 사람만 알지 😂

Apollo Client는 GraphQL을 위한 가장 인기 있는 클라이언트 라이브러리야. React, Vue, Angular, 심지어 바닐라 JS에서도 쓸 수 있어. 특히 React와의 조합이 최강이지!

🌟 Apollo Client가 제공하는 것들

✅ 자동 캐싱: 같은 데이터를 두 번 요청하지 않아도 돼
✅ 로딩/에러 상태 자동 관리: loading, error, data 상태를 자동으로 제공
✅ Optimistic UI: 서버 응답 전에 UI를 미리 업데이트
✅ Pagination 지원: 페이지네이션과 무한 스크롤 구현 용이
✅ React Hooks 지원: useQuery, useMutation, useSubscription
✅ DevTools: 브라우저 확장 프로그램으로 캐시 상태 확인 가능

📦 설치하기

React 프로젝트 기준으로 설치해볼게. 터미널 열고 따라와!

# npm 사용 시
npm install @apollo/client graphql

# yarn 사용 시
yarn add @apollo/client graphql

# pnpm 사용 시
pnpm add @apollo/client graphql
📌 패키지 설명 @apollo/client: Apollo Client 본체 (캐싱, 상태 관리, React 훅 포함)
graphql: GraphQL 쿼리 파싱을 위한 핵심 라이브러리 (필수 의존성)

WebSocket을 통한 Subscription을 사용하려면 추가 패키지가 필요해:

# Subscription을 위한 WebSocket 링크
npm install graphql-ws

# 또는 구버전 방식 (subscriptions-transport-ws)
npm install subscriptions-transport-ws
⚡ 버전 확인: 이 글은 Apollo Client v3 기준이야. @apollo/client 버전 3.x 이상을 사용하면 돼. 2024년 기준 최신 버전은 3.11.x야.

4. Apollo Client 기본 설정하기 ⚙️

설치가 끝났으면 이제 Apollo Client를 설정해야 해. 이 부분이 좀 중요하니까 집중해! 👀

🔧 기본 클라이언트 설정

// src/apollo/client.js
import { ApolloClient, InMemoryCache, createHttpLink } from '@apollo/client';

// HTTP 링크 설정 (GraphQL 서버 주소)
const httpLink = createHttpLink({
  uri: 'https://your-graphql-server.com/graphql',
});

// Apollo Client 인스턴스 생성
const client = new ApolloClient({
  link: httpLink,
  cache: new InMemoryCache(), // 인메모리 캐시 사용
  defaultOptions: {
    watchQuery: {
      fetchPolicy: 'cache-and-network', // 캐시 우선, 네트워크로 업데이트
    },
  },
});

export default client;

🔐 인증 헤더 추가하기

실제 프로젝트에서는 JWT 토큰 같은 인증 정보를 헤더에 담아야 하잖아. setContext를 사용하면 돼!

// src/apollo/client.js
import { ApolloClient, InMemoryCache, createHttpLink } from '@apollo/client';
import { setContext } from '@apollo/client/link/context';

const httpLink = createHttpLink({
  uri: 'https://your-graphql-server.com/graphql',
});

// 인증 링크 설정
const authLink = setContext((_, { headers }) => {
  // localStorage에서 토큰 가져오기
  const token = localStorage.getItem('authToken');
  
  return {
    headers: {
      ...headers,
      authorization: token ? `Bearer ${token}` : '',
    },
  };
});

const client = new ApolloClient({
  // authLink와 httpLink를 체인으로 연결
  link: authLink.concat(httpLink),
  cache: new InMemoryCache(),
});

export default client;

🌐 ApolloProvider로 앱 감싸기

React 앱에서 Apollo Client를 사용하려면 ApolloProvider로 앱 전체를 감싸야 해. Context API 방식이라서 어디서든 훅을 사용할 수 있게 돼.

// src/index.js (또는 src/main.jsx)
import React from 'react';
import ReactDOM from 'react-dom/client';
import { ApolloProvider } from '@apollo/client';
import client from './apollo/client';
import App from './App';

const root = ReactDOM.createRoot(document.getElementById('root'));

root.render(
  <React.StrictMode>
    <ApolloProvider client={client}>
      <App />
    </ApolloProvider>
  </React.StrictMode>
);

🔗 Subscription을 위한 WebSocket 링크 설정

실시간 기능이 필요하다면 HTTP 링크와 WebSocket 링크를 함께 설정해야 해. 쿼리/뮤테이션은 HTTP로, 구독은 WebSocket으로 자동 분기되도록 설정하는 거야.

// src/apollo/client.js (Subscription 포함 버전)
import { ApolloClient, InMemoryCache, createHttpLink, split } from '@apollo/client';
import { GraphQLWsLink } from '@apollo/client/link/subscriptions';
import { createClient } from 'graphql-ws';
import { getMainDefinition } from '@apollo/client/utilities';
import { setContext } from '@apollo/client/link/context';

// HTTP 링크
const httpLink = createHttpLink({
  uri: 'https://your-graphql-server.com/graphql',
});

// WebSocket 링크 (Subscription용)
const wsLink = new GraphQLWsLink(
  createClient({
    url: 'wss://your-graphql-server.com/graphql',
    connectionParams: () => ({
      authToken: localStorage.getItem('authToken'),
    }),
  })
);

// 인증 링크
const authLink = setContext((_, { headers }) => {
  const token = localStorage.getItem('authToken');
  return {
    headers: {
      ...headers,
      authorization: token ? `Bearer ${token}` : '',
    },
  };
});

// 쿼리 타입에 따라 링크 분기
const splitLink = split(
  ({ query }) => {
    const definition = getMainDefinition(query);
    return (
      definition.kind === 'OperationDefinition' &&
      definition.operation === 'subscription'
    );
  },
  wsLink,        // Subscription → WebSocket
  authLink.concat(httpLink) // Query/Mutation → HTTP
);

const client = new ApolloClient({
  link: splitLink,
  cache: new InMemoryCache(),
});

export default client;
📌 split 함수는 조건에 따라 두 링크 중 하나를 선택해. 첫 번째 인자가 true면 두 번째 링크(wsLink), false면 세 번째 링크(httpLink)를 사용해.

5. Query로 데이터 가져오기 📡

드디어 실전이야! 🎉 Apollo Client에서 데이터를 가져오는 방법은 크게 두 가지야: useQuery 훅과 useLazyQuery 훅. 각각 언제 쓰는지 알아보자!

📌 gql 태그로 쿼리 정의하기

먼저 GraphQL 쿼리를 JavaScript에서 사용하려면 gql 태그 함수로 감싸야 해. 이게 쿼리 문자열을 AST(Abstract Syntax Tree)로 파싱해줘.

// src/graphql/queries.js
import { gql } from '@apollo/client';

// 유저 목록 쿼리
export const GET_USERS = gql`
  query GetUsers {
    users {
      id
      name
      email
      posts {
        id
        title
        likes
      }
    }
  }
`;

// 특정 유저 쿼리 (변수 사용)
export const GET_USER = gql`
  query GetUser($id: ID!) {
    user(id: $id) {
      id
      name
      email
      age
      createdAt
    }
  }
`;

// 게시글 목록 쿼리 (페이지네이션)
export const GET_POSTS = gql`
  query GetPosts($limit: Int, $offset: Int) {
    posts(limit: $limit, offset: $offset) {
      id
      title
      content
      likes
      published
      author {
        id
        name
      }
    }
  }
`;

🎣 useQuery 훅 사용하기

useQuery는 컴포넌트가 렌더링될 때 자동으로 쿼리를 실행해. 가장 기본적인 데이터 페칭 방법이야!

// src/components/UserList.jsx
import React from 'react';
import { useQuery } from '@apollo/client';
import { GET_USERS } from '../graphql/queries';

function UserList() {
  const { loading, error, data } = useQuery(GET_USERS);

  // 로딩 상태
  if (loading) return <p>로딩 중... ⏳</p>;
  
  // 에러 상태
  if (error) return <p>에러 발생: {error.message} 😢</p>;

  // 데이터 렌더링
  return (
    <div>
      <h2>유저 목록</h2>
      {data.users.map((user) => (
        <div key={user.id}>
          <h3>{user.name}</h3>
          <p>{user.email}</p>
          <p>게시글 수: {user.posts.length}</p>
        </div>
      ))}
    </div>
  );
}

export default UserList;

🎯 변수(Variables)와 함께 useQuery 사용하기

// src/components/UserDetail.jsx
import React from 'react';
import { useQuery } from '@apollo/client';
import { GET_USER } from '../graphql/queries';

function UserDetail({ userId }) {
  const { loading, error, data, refetch } = useQuery(GET_USER, {
    variables: { id: userId }, // 변수 전달
    skip: !userId,             // userId가 없으면 쿼리 건너뜀
    fetchPolicy: 'cache-first', // 캐시 우선 정책
    pollInterval: 30000,        // 30초마다 자동 새로고침
    onCompleted: (data) => {
      console.log('데이터 로드 완료!', data);
    },
    onError: (error) => {
      console.error('에러 발생!', error);
    },
  });

  if (loading) return <p>유저 정보 로딩 중...</p>;
  if (error) return <p>에러: {error.message}</p>;
  if (!data?.user) return <p>유저를 찾을 수 없어요.</p>;

  const { user } = data;

  return (
    <div>
      <h2>{user.name}</h2>
      <p>이메일: {user.email}</p>
      <p>나이: {user.age ?? '미입력'}</p>
      <p>가입일: {user.createdAt}</p>
      <button onClick={() => refetch()}>새로고침 🔄</button>
    </div>
  );
}

export default UserDetail;
📋 useQuery 주요 옵션들

variables: 쿼리에 전달할 변수 객체
skip: true면 쿼리 실행 안 함
fetchPolicy: 캐시 정책 설정
pollInterval: 자동 폴링 간격 (ms)
notifyOnNetworkStatusChange: 네트워크 상태 변경 시 리렌더링
onCompleted: 쿼리 성공 콜백
onError: 쿼리 실패 콜백

⏰ useLazyQuery - 원할 때만 실행하기

useQuery는 컴포넌트 마운트 시 자동 실행되는데, 버튼 클릭이나 특정 이벤트 시에만 쿼리를 실행하고 싶다면 useLazyQuery를 써야 해!

// src/components/SearchUser.jsx
import React, { useState } from 'react';
import { useLazyQuery } from '@apollo/client';
import { GET_USER } from '../graphql/queries';

function SearchUser() {
  const [userId, setUserId] = useState('');
  
  // useLazyQuery는 [실행함수, 결과객체] 튜플을 반환
  const [getUser, { loading, error, data, called }] = useLazyQuery(GET_USER, {
    fetchPolicy: 'network-only', // 항상 네트워크에서 최신 데이터 가져오기
  });

  const handleSearch = () => {
    if (!userId.trim()) return;
    
    // 원할 때 직접 실행!
    getUser({
      variables: { id: userId },
    });
  };

  return (
    <div>
      <input
        type="text"
        value={userId}
        onChange={(e) => setUserId(e.target.value)}
        placeholder="유저 ID 입력"
      />
      <button onClick={handleSearch} disabled={loading}>
        {loading ? '검색 중...' : '검색 🔍'}
      </button>

      {called && !loading && !error && data?.user && (
        <div>
          <h3>{data.user.name}</h3>
          <p>{data.user.email}</p>
        </div>
      )}

      {error && <p>유저를 찾을 수 없어요: {error.message}</p>}
    </div>
  );
}

export default SearchUser;

📄 페이지네이션 구현하기

실제 앱에서 빠질 수 없는 페이지네이션! Apollo Client에서는 fetchMore를 사용해서 구현해.

// src/components/PostList.jsx
import React from 'react';
import { useQuery } from '@apollo/client';
import { GET_POSTS } from '../graphql/queries';

const POSTS_PER_PAGE = 10;

function PostList() {
  const { loading, error, data, fetchMore } = useQuery(GET_POSTS, {
    variables: {
      limit: POSTS_PER_PAGE,
      offset: 0,
    },
  });

  const loadMore = () => {
    fetchMore({
      variables: {
        offset: data.posts.length, // 현재 로드된 개수부터 시작
        limit: POSTS_PER_PAGE,
      },
      updateQuery: (prev, { fetchMoreResult }) => {
        if (!fetchMoreResult) return prev;
        
        // 기존 데이터에 새 데이터 추가 (무한 스크롤)
        return {
          posts: [...prev.posts, ...fetchMoreResult.posts],
        };
      },
    });
  };

  if (loading && !data) return <p>로딩 중...</p>;
  if (error) return <p>에러: {error.message}</p>;

  return (
    <div>
      {data?.posts.map((post) => (
        <article key={post.id}>
          <h3>{post.title}</h3>
          <p>작성자: {post.author.name}</p>
          <p>좋아요: {post.likes}</p>
        </article>
      ))}
      
      <button onClick={loadMore} disabled={loading}>
        {loading ? '로딩 중...' : '더 보기 ⬇️'}
      </button>
    </div>
  );
}

export default PostList;

6. Mutation으로 데이터 변경하기 ✏️

데이터를 읽는 것만큼 중요한 게 데이터를 변경하는 거잖아! useMutation 훅으로 생성, 수정, 삭제를 구현해보자.

📝 Mutation 정의하기

// src/graphql/mutations.js
import { gql } from '@apollo/client';

export const CREATE_POST = gql`
  mutation CreatePost($title: String!, $content: String!, $authorId: ID!) {
    createPost(title: $title, content: $content, authorId: $authorId) {
      id
      title
      content
      author {
        id
        name
      }
      likes
      published
    }
  }
`;

export const UPDATE_POST = gql`
  mutation UpdatePost($id: ID!, $title: String, $content: String) {
    updatePost(id: $id, title: $title, content: $content) {
      id
      title
      content
    }
  }
`;

export const DELETE_POST = gql`
  mutation DeletePost($id: ID!) {
    deletePost(id: $id)
  }
`;

export const LIKE_POST = gql`
  mutation LikePost($postId: ID!) {
    likePost(postId: $postId) {
      id
      likes
    }
  }
`;

🚀 useMutation 훅 사용하기

// src/components/CreatePostForm.jsx
import React, { useState } from 'react';
import { useMutation } from '@apollo/client';
import { CREATE_POST, GET_POSTS } from '../graphql';

function CreatePostForm({ authorId }) {
  const [title, setTitle] = useState('');
  const [content, setContent] = useState('');

  const [createPost, { loading, error, data }] = useMutation(CREATE_POST, {
    // 뮤테이션 성공 후 GET_POSTS 쿼리 자동 리페치
    refetchQueries: [
      { query: GET_POSTS, variables: { limit: 10, offset: 0 } }
    ],
    // 또는 쿼리 이름으로 지정
    // refetchQueries: ['GetPosts'],
    
    onCompleted: (data) => {
      console.log('게시글 생성 완료!', data.createPost);
      setTitle('');
      setContent('');
      alert('게시글이 등록되었어요! 🎉');
    },
    onError: (error) => {
      console.error('게시글 생성 실패:', error.message);
    },
  });

  const handleSubmit = async (e) => {
    e.preventDefault();
    
    if (!title.trim() || !content.trim()) {
      alert('제목과 내용을 입력해주세요!');
      return;
    }

    try {
      await createPost({
        variables: {
          title,
          content,
          authorId,
        },
      });
    } catch (err) {
      // onError에서 처리되지만 async/await 패턴에서는 catch도 필요
      console.error(err);
    }
  };

  return (
    <form onSubmit={handleSubmit}>
      <input
        type="text"
        value={title}
        onChange={(e) => setTitle(e.target.value)}
        placeholder="게시글 제목"
        disabled={loading}
      />
      <textarea
        value={content}
        onChange={(e) => setContent(e.target.value)}
        placeholder="내용을 입력하세요"
        disabled={loading}
      />
      {error && <p style={{ color: 'red' }}>에러: {error.message}</p>}
      <button type="submit" disabled={loading}>
        {loading ? '등록 중...' : '게시글 등록 📝'}
      </button>
    </form>
  );
}

export default CreatePostForm;

⚡ Optimistic UI - 서버 응답 전에 UI 미리 업데이트

좋아요 버튼을 눌렀을 때 서버 응답을 기다리지 않고 즉시 UI를 업데이트하면 훨씬 빠른 느낌을 줄 수 있어. 이게 바로 Optimistic UI야!

// src/components/LikeButton.jsx
import React from 'react';
import { useMutation } from '@apollo/client';
import { LIKE_POST } from '../graphql/mutations';

function LikeButton({ post }) {
  const [likePost] = useMutation(LIKE_POST, {
    // Optimistic Response 설정
    optimisticResponse: {
      likePost: {
        __typename: 'Post',
        id: post.id,
        likes: post.likes + 1, // 서버 응답 전에 미리 +1
      },
    },
    // 캐시 직접 업데이트 (더 세밀한 제어)
    update: (cache, { data: { likePost } }) => {
      cache.modify({
        id: cache.identify(post),
        fields: {
          likes: () => likePost.likes,
        },
      });
    },
  });

  const handleLike = () => {
    likePost({
      variables: { postId: post.id },
    });
  };

  return (
    <button onClick={handleLike}>
      ❤️ {post.likes}
    </button>
  );
}

export default LikeButton;
💡 Optimistic UI의 동작 방식 1. 버튼 클릭 → optimisticResponse로 캐시 즉시 업데이트 → UI 반영
2. 서버에 실제 요청 전송
3. 서버 응답 도착 → 실제 데이터로 캐시 업데이트
4. 서버 에러 시 → 캐시 롤백 (원래 상태로 복구)

🗑️ 삭제 구현하기

// src/components/DeleteButton.jsx
import React from 'react';
import { useMutation } from '@apollo/client';
import { DELETE_POST, GET_POSTS } from '../graphql';

function DeleteButton({ postId }) {
  const [deletePost, { loading }] = useMutation(DELETE_POST, {
    variables: { id: postId },
    
    // 캐시에서 직접 삭제 (refetch 없이!)
    update: (cache, { data: { deletePost: success } }) => {
      if (success) {
        // 캐시에서 해당 게시글 제거
        cache.evict({ id: `Post:${postId}` });
        cache.gc(); // 가비지 컬렉션
      }
    },
    
    onCompleted: () => {
      alert('게시글이 삭제되었어요!');
    },
  });

  const handleDelete = () => {
    if (window.confirm('정말 삭제할까요?')) {
      deletePost();
    }
  };

  return (
    <button onClick={handleDelete} disabled={loading}>
      {loading ? '삭제 중...' : '삭제 🗑️'}
    </button>
  );
}

export default DeleteButton;

7. Subscription으로 실시간 데이터 받기 🔴

채팅 앱, 실시간 알림, 라이브 대시보드... 이런 기능들의 핵심은 실시간 데이터야. Apollo Client의 useSubscription으로 구현해보자!

WebSocket 실시간 통신 흐름 클라이언트 Apollo Client useSubscription GraphQL 서버 Subscription Resolver WebSocket 연결 (wss://) 이벤트 발생 (새 게시글 추가) 서버 → 클라이언트 자동 푸시 UI 자동 업데이트 ✅ 폴링: 매 N초마다 요청 구독: 이벤트 시에만 수신 → 훨씬 효율적! 🚀

📡 useSubscription 훅 사용하기

// src/graphql/subscriptions.js
import { gql } from '@apollo/client';

export const POST_ADDED_SUBSCRIPTION = gql`
  subscription OnPostAdded {
    postAdded {
      id
      title
      content
      author {
        id
        name
      }
      likes
      createdAt
    }
  }
`;

export const USER_ONLINE_SUBSCRIPTION = gql`
  subscription OnUserOnline($userId: ID!) {
    userOnline(userId: $userId) {
      id
      name
      isOnline
      lastSeen
    }
  }
`;
// src/components/LivePostFeed.jsx
import React from 'react';
import { useSubscription, useQuery } from '@apollo/client';
import { POST_ADDED_SUBSCRIPTION } from '../graphql/subscriptions';
import { GET_POSTS } from '../graphql/queries';

function LivePostFeed() {
  // 기존 게시글 목록 가져오기
  const { data: postsData, loading } = useQuery(GET_POSTS, {
    variables: { limit: 20, offset: 0 },
  });

  // 실시간 새 게시글 구독
  const { data: subscriptionData } = useSubscription(
    POST_ADDED_SUBSCRIPTION,
    {
      onData: ({ client, data }) => {
        // 새 게시글이 오면 캐시 업데이트
        const newPost = data.data.postAdded;
        
        client.cache.modify({
          fields: {
            posts: (existingPosts = []) => {
              const newPostRef = client.cache.writeFragment({
                data: newPost,
                fragment: gql`
                  fragment NewPost on Post {
                    id
                    title
                    content
                    author {
                      id
                      name
                    }
                    likes
                    createdAt
                  }
                `,
              });
              return [newPostRef, ...existingPosts];
            },
          },
        });
      },
      onError: (error) => {
        console.error('구독 에러:', error);
      },
    }
  );

  if (loading) return <p>로딩 중...</p>;

  return (
    <div>
      <h2>🔴 실시간 게시글 피드</h2>
      {postsData?.posts.map((post) => (
        <article key={post.id}>
          <h3>{post.title}</h3>
          <p>작성자: {post.author.name}</p>
          <p>❤️ {post.likes}</p>
        </article>
      ))}
    </div>
  );
}

export default LivePostFeed;
⚡ subscribeToMore: useQuery와 함께 구독을 사용하는 또 다른 방법이야. 기존 쿼리 결과에 실시간 업데이트를 합치는 패턴으로, 초기 데이터는 쿼리로, 이후 업데이트는 구독으로 받는 방식이야.
// subscribeToMore 패턴
function LivePostFeedV2() {
  const { data, loading, subscribeToMore } = useQuery(GET_POSTS, {
    variables: { limit: 20, offset: 0 },
  });

  React.useEffect(() => {
    const unsubscribe = subscribeToMore({
      document: POST_ADDED_SUBSCRIPTION,
      updateQuery: (prev, { subscriptionData }) => {
        if (!subscriptionData.data) return prev;
        
        const newPost = subscriptionData.data.postAdded;
        
        return {
          posts: [newPost, ...prev.posts],
        };
      },
    });

    // 컴포넌트 언마운트 시 구독 해제
    return () => unsubscribe();
  }, [subscribeToMore]);

  // ... 렌더링 로직
}

8. Apollo Client 캐싱 전략 🗄️

Apollo Client의 가장 강력한 기능 중 하나가 바로 InMemoryCache야. 이걸 잘 이해하면 불필요한 네트워크 요청을 줄이고 앱 성능을 크게 향상시킬 수 있어!

🔑 캐시 정규화 (Normalization)

Apollo Cache는 데이터를 정규화해서 저장해. 같은 객체가 여러 쿼리에서 반환되더라도 캐시에는 하나만 저장되고, 모든 참조가 그 하나를 가리키는 방식이야.

💡 기본적으로 Apollo는 __typename + id 조합으로 캐시 키를 만들어.
예: User:1, Post:42 이런 식으로 저장돼.
그래서 어떤 쿼리에서 User:1을 업데이트하면, 그 유저를 참조하는 모든 컴포넌트가 자동으로 업데이트돼! 🎯

📊 fetchPolicy 옵션 완전 정리

🗂️ fetchPolicy 종류와 특징

cache-first (기본값): 캐시에 있으면 캐시 사용, 없으면 네트워크 요청
cache-and-network: 캐시 데이터 즉시 반환 + 백그라운드에서 네트워크 업데이트
network-only: 항상 네트워크 요청, 결과는 캐시에 저장
no-cache: 항상 네트워크 요청, 캐시에 저장 안 함
cache-only: 캐시에서만 읽기, 네트워크 요청 안 함
standby: 활성 쿼리에서 제외 (수동으로 refetch 가능)

// 상황별 fetchPolicy 선택 가이드

// 1. 자주 변하지 않는 데이터 (카테고리 목록, 설정 등)
const { data } = useQuery(GET_CATEGORIES, {
  fetchPolicy: 'cache-first', // 캐시 우선 (기본값)
});

// 2. 실시간성이 중요한 데이터 (재고, 가격 등)
const { data } = useQuery(GET_STOCK_PRICE, {
  fetchPolicy: 'network-only', // 항상 최신 데이터
});

// 3. 빠른 초기 로딩 + 최신 데이터 보장
const { data } = useQuery(GET_POSTS, {
  fetchPolicy: 'cache-and-network', // 캐시 먼저 보여주고 업데이트
});

// 4. 민감한 데이터 (결제 정보 등)
const { data } = useQuery(GET_PAYMENT_INFO, {
  fetchPolicy: 'no-cache', // 캐시에 저장하지 않음
});

🔧 캐시 직접 조작하기

뮤테이션 후 캐시를 직접 업데이트하면 불필요한 네트워크 요청을 줄일 수 있어!

// 캐시 읽기/쓰기
import { useApolloClient } from '@apollo/client';

function SomeComponent() {
  const client = useApolloClient();

  const updateCacheManually = () => {
    // 캐시에서 읽기
    const cachedData = client.cache.readQuery({
      query: GET_POSTS,
      variables: { limit: 10, offset: 0 },
    });

    // 캐시에 쓰기
    client.cache.writeQuery({
      query: GET_POSTS,
      variables: { limit: 10, offset: 0 },
      data: {
        posts: [newPost, ...cachedData.posts],
      },
    });

    // 특정 필드만 수정
    client.cache.modify({
      id: client.cache.identify({ __typename: 'Post', id: '42' }),
      fields: {
        likes: (currentLikes) => currentLikes + 1,
        title: () => '수정된 제목',
      },
    });

    // 캐시에서 특정 항목 제거
    client.cache.evict({
      id: client.cache.identify({ __typename: 'Post', id: '42' }),
    });

    // 전체 캐시 초기화 (로그아웃 시 유용)
    client.clearStore();
    // 또는 캐시 초기화 후 활성 쿼리 리페치
    client.resetStore();
  };
}

⚙️ InMemoryCache 고급 설정

// src/apollo/client.js
import { ApolloClient, InMemoryCache } from '@apollo/client';

const cache = new InMemoryCache({
  // 타입별 캐시 키 커스터마이징
  typePolicies: {
    User: {
      // id 필드를 캐시 키로 사용 (기본값)
      keyFields: ['id'],
    },
    
    // 복합 키 사용
    UserSettings: {
      keyFields: ['userId', 'settingType'],
    },
    
    // 캐시 키 없는 타입 (싱글톤)
    AppConfig: {
      keyFields: false,
    },
    
    Query: {
      fields: {
        // 페이지네이션 필드 병합 정책
        posts: {
          keyArgs: ['limit'], // 캐시 키에 포함할 인자
          merge(existing = [], incoming) {
            return [...existing, ...incoming];
          },
          read(existing) {
            return existing;
          },
        },
      },
    },
  },
});

const client = new ApolloClient({
  link: httpLink,
  cache,
});

9. 에러 핸들링과 로딩 상태 관리 🛡️

실제 프로덕션 앱에서는 에러 처리와 로딩 상태 관리가 정말 중요해. Apollo Client가 제공하는 도구들을 잘 활용해보자!

🚨 에러 타입 이해하기

Apollo Client에서 발생하는 에러는 크게 두 가지야:

🔴 GraphQL Errors vs Network Errors

GraphQL Errors: 서버가 요청을 처리했지만 비즈니스 로직 에러 발생
(예: 권한 없음, 데이터 없음, 유효성 검사 실패)
→ error.graphQLErrors 배열에 담겨 옴

Network Errors: 서버에 아예 연결 못 한 경우
(예: 인터넷 끊김, 서버 다운, CORS 에러)
→ error.networkError에 담겨 옴

// src/components/ErrorHandlingExample.jsx
import React from 'react';
import { useQuery } from '@apollo/client';
import { GET_USER } from '../graphql/queries';

function ErrorHandlingExample({ userId }) {
  const { loading, error, data, refetch } = useQuery(GET_USER, {
    variables: { id: userId },
    errorPolicy: 'all', // 에러가 있어도 부분 데이터 반환
  });

  if (loading) {
    return (
      <div className="loading-skeleton">
        {/* 스켈레톤 UI */}
        <div style={{ background: '#eee', height: 20, borderRadius: 4, marginBottom: 8 }} />
        <div style={{ background: '#eee', height: 16, borderRadius: 4, width: '60%' }} />
      </div>
    );
  }

  if (error) {
    // 네트워크 에러
    if (error.networkError) {
      return (
        <div>
          <p>🌐 네트워크 연결을 확인해주세요.</p>
          <button onClick={() => refetch()}>다시 시도</button>
        </div>
      );
    }

    // GraphQL 에러
    if (error.graphQLErrors.length > 0) {
      const firstError = error.graphQLErrors[0];
      
      switch (firstError.extensions?.code) {
        case 'UNAUTHENTICATED':
          return <p>🔐 로그인이 필요해요.</p>;
        case 'FORBIDDEN':
          return <p>🚫 접근 권한이 없어요.</p>;
        case 'NOT_FOUND':
          return <p>🔍 찾을 수 없어요.</p>;
        default:
          return <p>❌ 에러: {firstError.message}</p>;
      }
    }
  }

  return <div>{data?.user?.name}</div>;
}

export default ErrorHandlingExample;

🌐 전역 에러 핸들링 (Error Link)

모든 요청에서 공통으로 처리해야 하는 에러(예: 401 인증 만료)는 onError 링크로 처리하는 게 깔끔해!

// src/apollo/client.js
import { ApolloClient, InMemoryCache, createHttpLink } from '@apollo/client';
import { onError } from '@apollo/client/link/error';

// 전역 에러 핸들러
const errorLink = onError(({ graphQLErrors, networkError, operation, forward }) => {
  if (graphQLErrors) {
    graphQLErrors.forEach(({ message, locations, path, extensions }) => {
      console.error(`[GraphQL Error]: ${message}`);
      
      // 인증 만료 처리
      if (extensions?.code === 'UNAUTHENTICATED') {
        // 토큰 갱신 시도
        return refreshTokenAndRetry(operation, forward);
      }
    });
  }

  if (networkError) {
    console.error(`[Network Error]: ${networkError.message}`);
    
    // 401 에러 처리
    if ('statusCode' in networkError && networkError.statusCode === 401) {
      // 로그아웃 처리
      localStorage.removeItem('authToken');
      window.location.href = '/login';
    }
  }
});

const client = new ApolloClient({
  link: errorLink.concat(authLink).concat(httpLink),
  cache: new InMemoryCache(),
});

⏳ 로딩 상태 고급 관리

// networkStatus를 활용한 세밀한 로딩 상태 관리
import { useQuery, NetworkStatus } from '@apollo/client';

function PostListWithStatus() {
  const { loading, data, error, networkStatus, refetch } = useQuery(GET_POSTS, {
    notifyOnNetworkStatusChange: true, // 네트워크 상태 변경 시 리렌더링
  });

  // NetworkStatus 값들:
  // 1: loading (초기 로딩)
  // 2: setVariables (변수 변경)
  // 3: fetchMore (더 불러오기)
  // 4: refetch (새로고침)
  // 6: poll (폴링)
  // 7: ready (완료)
  // 8: error (에러)

  if (networkStatus === NetworkStatus.refetch) {
    return <p>새로고침 중... 🔄</p>;
  }

  if (networkStatus === NetworkStatus.fetchMore) {
    return (
      <div>
        {/* 기존 데이터 보여주면서 */}
        {data?.posts.map(post => <div key={post.id}>{post.title}</div>)}
        <p>더 불러오는 중... ⏳</p>
      </div>
    );
  }

  if (loading) return <p>로딩 중...</p>;
  if (error) return <p>에러 발생!</p>;

  return (
    <div>
      {data?.posts.map(post => (
        <div key={post.id}>{post.title}</div>
      ))}
      <button onClick={() => refetch()}>새로고침</button>
    </div>
  );
}

10. 실전 프로젝트 패턴과 최적화 🏆

이론은 충분히 배웠으니, 이제 실제 프로젝트에서 쓰이는 패턴들을 알아보자! 재능넷 같은 플랫폼을 만든다고 생각하면서 읽어봐. 😄

📁 프로젝트 구조 추천

src/
├── apollo/
│   ├── client.js          # Apollo Client 설정
│   └── cache.js           # 캐시 정책 설정
├── graphql/
│   ├── queries/
│   │   ├── user.queries.js
│   │   ├── post.queries.js
│   │   └── index.js
│   ├── mutations/
│   │   ├── user.mutations.js
│   │   ├── post.mutations.js
│   │   └── index.js
│   ├── subscriptions/
│   │   └── post.subscriptions.js
│   └── fragments/
│       ├── user.fragments.js
│       └── post.fragments.js
├── hooks/
│   ├── useUser.js         # 커스텀 훅
│   └── usePosts.js
└── components/
    └── ...

🎣 커스텀 훅으로 로직 분리하기

컴포넌트에서 GraphQL 로직을 분리하면 재사용성과 테스트 용이성이 높아져!

// src/hooks/usePosts.js
import { useQuery, useMutation } from '@apollo/client';
import { GET_POSTS, CREATE_POST, DELETE_POST } from '../graphql';

export function usePosts(options = {}) {
  const { limit = 10, offset = 0 } = options;

  const {
    data,
    loading: postsLoading,
    error: postsError,
    fetchMore,
    refetch,
  } = useQuery(GET_POSTS, {
    variables: { limit, offset },
    fetchPolicy: 'cache-and-network',
  });

  const [createPost, { loading: creating }] = useMutation(CREATE_POST, {
    update: (cache, { data: { createPost: newPost } }) => {
      cache.modify({
        fields: {
          posts: (existingPosts = []) => {
            const newPostRef = cache.writeFragment({
              data: newPost,
              fragment: POST_FRAGMENT,
            });
            return [newPostRef, ...existingPosts];
          },
        },
      });
    },
  });

  const [deletePost, { loading: deleting }] = useMutation(DELETE_POST, {
    update: (cache, _, { variables: { id } }) => {
      cache.evict({ id: `Post:${id}` });
      cache.gc();
    },
  });

  const loadMore = () => {
    fetchMore({
      variables: { offset: data?.posts.length ?? 0, limit },
      updateQuery: (prev, { fetchMoreResult }) => ({
        posts: [...(prev.posts ?? []), ...(fetchMoreResult?.posts ?? [])],
      }),
    });
  };

  return {
    posts: data?.posts ?? [],
    loading: postsLoading,
    error: postsError,
    creating,
    deleting,
    createPost,
    deletePost,
    loadMore,
    refetch,
  };
}

// 사용 예시
function PostPage() {
  const { posts, loading, createPost, deletePost, loadMore } = usePosts({ limit: 20 });

  // 깔끔한 컴포넌트!
  if (loading) return <p>로딩 중...</p>;

  return (
    <div>
      {posts.map(post => (
        <div key={post.id}>
          <h3>{post.title}</h3>
          <button onClick={() => deletePost({ variables: { id: post.id } })}>
            삭제
          </button>
        </div>
      ))}
      <button onClick={loadMore}>더 보기</button>
    </div>
  );
}

🔄 React Query와의 비교

Apollo Client vs React Query (TanStack Query)

Apollo Client: GraphQL 전용, 강력한 캐시 정규화, Subscription 내장, 번들 크기 큼
React Query: REST/GraphQL 모두 지원, 간단한 API, 가벼움, Subscription 미지원

→ GraphQL을 주로 쓴다면 Apollo Client
→ REST API 위주이거나 간단한 GraphQL이라면 React Query + graphql-request

⚡ 성능 최적화 팁

1
Fragment Colocation: 컴포넌트가 필요한 데이터를 Fragment로 정의하고, 부모 쿼리에서 조합해. 컴포넌트와 데이터 요구사항을 함께 관리할 수 있어.
2
@defer 디렉티브: 중요하지 않은 데이터는 나중에 받아. 초기 로딩 속도를 높일 수 있어. (서버 지원 필요)
3
Persisted Queries: 쿼리 문자열 대신 해시값을 전송해서 네트워크 페이로드를 줄여. 특히 모바일 환경에서 효과적이야.
4
Apollo DevTools: 크롬 확장 프로그램으로 캐시 상태, 쿼리 히스토리를 실시간으로 확인해. 디버깅 필수 도구야!
5
TypeScript 연동: @graphql-codegen으로 스키마에서 TypeScript 타입을 자동 생성해. 타입 안전성을 확보하고 개발 생산성을 높여!

🔷 TypeScript + GraphQL Codegen 설정

# 설치
npm install -D @graphql-codegen/cli @graphql-codegen/typescript @graphql-codegen/typescript-operations @graphql-codegen/typescript-react-apollo

# codegen.yml 설정
schema: "https://your-graphql-server.com/graphql"
documents: "src/**/*.graphql"
generates:
  src/generated/graphql.ts:
    plugins:
      - typescript
      - typescript-operations
      - typescript-react-apollo
    config:
      withHooks: true
      withComponent: false

# 실행
npx graphql-codegen
// 자동 생성된 타입과 훅 사용 예시
import { useGetUsersQuery, useCreatePostMutation } from '../generated/graphql';

function TypeSafeComponent() {
  // 완전한 타입 안전성!
  const { data, loading } = useGetUsersQuery({
    variables: { limit: 10 },
  });

  const [createPost] = useCreatePostMutation();

  // data.users는 자동으로 User[] 타입
  return (
    <div>
      {data?.users.map(user => (
        <span key={user.id}>{user.name}</span>
      ))}
    </div>
  );
}
Apollo Client 전체 데이터 흐름 React 컴포넌트 useQuery / useMutation Apollo Client 캐시 확인 → 링크 체인 → 서버 요청 InMemoryCache 정규화된 데이터 저장소 GraphQL 서버 Resolver 실행 HTTP/WS 응답 데이터 반환 Apollo Link 체인 구조 Error Link → Auth Link → HTTP Link or WS Link 요청이 링크 체인을 통과하며 처리됨 (미들웨어 패턴) Query/Mutation → HTTP Link | Subscription → WebSocket Link

🧪 테스트 작성하기

// src/components/__tests__/UserList.test.jsx
import React from 'react';
import { render, screen, waitFor } from '@testing-library/react';
import { MockedProvider } from '@apollo/client/testing';
import UserList from '../UserList';
import { GET_USERS } from '../../graphql/queries';

// Mock 데이터 설정
const mocks = [
  {
    request: {
      query: GET_USERS,
    },
    result: {
      data: {
        users: [
          { id: '1', name: '김철수', email: 'chulsoo@test.com', posts: [] },
          { id: '2', name: '이영희', email: 'younghee@test.com', posts: [] },
        ],
      },
    },
  },
];

// 에러 케이스 Mock
const errorMocks = [
  {
    request: { query: GET_USERS },
    error: new Error('서버 에러!'),
  },
];

describe('UserList 컴포넌트', () => {
  test('유저 목록을 올바르게 렌더링한다', async () => {
    render(
      <MockedProvider mocks={mocks} addTypename={false}>
        <UserList />
      </MockedProvider>
    );

    // 로딩 상태 확인
    expect(screen.getByText('로딩 중... ⏳')).toBeInTheDocument();

    // 데이터 로드 후 확인
    await waitFor(() => {
      expect(screen.getByText('김철수')).toBeInTheDocument();
      expect(screen.getByText('이영희')).toBeInTheDocument();
    });
  });

  test('에러 발생 시 에러 메시지를 표시한다', async () => {
    render(
      <MockedProvider mocks={errorMocks} addTypename={false}>
        <UserList />
      </MockedProvider>
    );

    await waitFor(() => {
      expect(screen.getByText(/에러 발생/)).toBeInTheDocument();
    });
  });
});
📌 MockedProvider: Apollo Client가 제공하는 테스트용 Provider야. 실제 서버 없이도 GraphQL 요청을 모킹해서 테스트할 수 있어. addTypename={false}를 설정하면 __typename 필드를 자동으로 추가하지 않아서 Mock 데이터 작성이 편해져.

🌟 마무리: 언제 GraphQL + Apollo를 써야 할까?

✅ GraphQL + Apollo Client가 빛나는 상황

• 복잡한 데이터 관계가 있는 앱 (소셜 미디어, 이커머스 등)
• 여러 클라이언트(웹, 모바일)가 같은 API를 사용하는 경우
• 실시간 기능이 필요한 앱 (채팅, 알림, 라이브 피드)
• 프론트엔드 팀이 필요한 데이터를 자율적으로 결정해야 하는 경우
• 빠른 프로토타이핑과 반복 개발이 필요한 경우

⚠️ GraphQL이 과할 수 있는 상황 단순한 CRUD 앱, 소규모 프로젝트, 백엔드 팀이 GraphQL을 지원하지 않는 경우에는 REST API + React Query 조합이 더 간단하고 효율적일 수 있어. 도구는 상황에 맞게 선택하는 게 최고야!

재능넷처럼 다양한 재능과 데이터가 복잡하게 연결된 플랫폼을 개발할 때, GraphQL과 Apollo Client의 조합은 정말 강력한 선택이 될 수 있어. 재능 정보, 유저 프로필, 리뷰, 거래 내역 등 서로 연결된 데이터를 효율적으로 관리하는 데 GraphQL의 유연성이 빛을 발하거든! ✨


댓글 작성

이 글에 대한 여러분의 생각을 들려주세요

댓글 0
댓글을 불러오는 중입니다.

아직 댓글이 없습니다.