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

GraphQL과 Apollo Client를
활용한 데이터 페칭
1. GraphQL이 뭔데? REST API랑 뭐가 달라? 🤔
자, 친구야! 개발하다 보면 이런 경험 한 번쯤 있지 않아? 🙋
백엔드한테 "유저 이름이랑 프로필 사진만 주세요~" 했더니, 돌아오는 응답은 유저의 생년월일, 주소, 전화번호, 가입일, 마지막 로그인 시간, 친구 목록까지 한 트럭이 날아오는 거야. 😅
이게 바로 REST API의 고질적인 문제인 Over-fetching이야.
반대로 이런 경우도 있어. 게시글 목록 페이지를 만드는데, 게시글 정보 API 하나로는 작성자 이름을 못 가져와서 유저 API를 또 따로 호출해야 하는 상황. 이게 Under-fetching이고, 이 때문에 API를 여러 번 호출하는 N+1 문제가 생기지.
GraphQL은 2012년 Facebook(현 Meta)이 내부적으로 개발하고, 2015년에 오픈소스로 공개한 API를 위한 쿼리 언어야. 단순히 데이터를 가져오는 방법이 아니라, 클라이언트가 원하는 데이터의 구조를 직접 정의해서 요청하는 완전히 새로운 패러다임이지.
하나의 엔드포인트(
/graphql)에서 모든 요청을 처리하며, 요청 형태에 따라 응답이 달라져.
여러 엔드포인트
고정된 응답 구조
Over/Under-fetching
버전 관리 필요 (v1, v2...)
문서 별도 작성 필요
단일 엔드포인트
유연한 응답 구조
정확한 데이터 요청
버전 관리 불필요
자동 문서화 (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!
}
!는 "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
}
}
3. Apollo Client 소개 및 설치 🛸
GraphQL 쿼리를 직접 fetch로 날릴 수도 있지만, 그러면 캐싱, 에러 처리, 로딩 상태 관리, 실시간 구독 등을 전부 직접 구현해야 해. 그게 얼마나 고통스러운 일인지는... 해본 사람만 알지 😂
Apollo Client는 GraphQL을 위한 가장 인기 있는 클라이언트 라이브러리야. React, Vue, Angular, 심지어 바닐라 JS에서도 쓸 수 있어. 특히 React와의 조합이 최강이지!
✅ 자동 캐싱: 같은 데이터를 두 번 요청하지 않아도 돼
✅ 로딩/에러 상태 자동 관리: 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 버전 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;
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;
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으로 구현해보자!
📡 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;
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는 데이터를 정규화해서 저장해. 같은 객체가 여러 쿼리에서 반환되더라도 캐시에는 하나만 저장되고, 모든 참조가 그 하나를 가리키는 방식이야.
__typename + id 조합으로 캐시 키를 만들어.예:
User:1, Post:42 이런 식으로 저장돼.그래서 어떤 쿼리에서 User:1을 업데이트하면, 그 유저를 참조하는 모든 컴포넌트가 자동으로 업데이트돼! 🎯
📊 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: 서버가 요청을 처리했지만 비즈니스 로직 에러 발생
(예: 권한 없음, 데이터 없음, 유효성 검사 실패)
→ 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: GraphQL 전용, 강력한 캐시 정규화, Subscription 내장, 번들 크기 큼
React Query: REST/GraphQL 모두 지원, 간단한 API, 가벼움, Subscription 미지원
→ GraphQL을 주로 쓴다면 Apollo Client
→ REST API 위주이거나 간단한 GraphQL이라면 React Query + graphql-request
⚡ 성능 최적화 팁
@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>
);
}
🧪 테스트 작성하기
// 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();
});
});
});
addTypename={false}를 설정하면 __typename 필드를 자동으로 추가하지 않아서 Mock 데이터 작성이 편해져.
🌟 마무리: 언제 GraphQL + Apollo를 써야 할까?
• 복잡한 데이터 관계가 있는 앱 (소셜 미디어, 이커머스 등)
• 여러 클라이언트(웹, 모바일)가 같은 API를 사용하는 경우
• 실시간 기능이 필요한 앱 (채팅, 알림, 라이브 피드)
• 프론트엔드 팀이 필요한 데이터를 자율적으로 결정해야 하는 경우
• 빠른 프로토타이핑과 반복 개발이 필요한 경우
재능넷처럼 다양한 재능과 데이터가 복잡하게 연결된 플랫폼을 개발할 때, GraphQL과 Apollo Client의 조합은 정말 강력한 선택이 될 수 있어. 재능 정보, 유저 프로필, 리뷰, 거래 내역 등 서로 연결된 데이터를 효율적으로 관리하는 데 GraphQL의 유연성이 빛을 발하거든! ✨
관련 키워드
댓글 작성
이 글에 대한 여러분의 생각을 들려주세요
로그인이 필요합니다
댓글을 작성하려면 먼저 로그인해주세요.
댓글 0
지식인의 숲 - 지적 재산권 보호 고지
지적 재산권 보호 고지
- 저작권 및 소유권: 본 컨텐츠는 재능넷의 독점 AI 기술로 생성되었으며, 대한민국 저작권법 및 국제 저작권 협약에 의해 보호됩니다.
- AI 생성 컨텐츠의 법적 지위: 본 AI 생성 컨텐츠는 재능넷의 지적 창작물로 인정되며, 관련 법규에 따라 저작권 보호를 받습니다.
- 사용 제한: 재능넷의 명시적 서면 동의 없이 본 컨텐츠를 복제, 수정, 배포, 또는 상업적으로 활용하는 행위는 엄격히 금지됩니다.
- 데이터 수집 금지: 본 컨텐츠에 대한 무단 스크래핑, 크롤링, 및 자동화된 데이터 수집은 법적 제재의 대상이 됩니다.
- AI 학습 제한: 재능넷의 AI 생성 컨텐츠를 타 AI 모델 학습에 무단 사용하는 행위는 금지되며, 이는 지적 재산권 침해로 간주됩니다.
아직 댓글이 없습니다.