- 게시글 제목, 본문
- 작성자 닉네임, 프로필 이미지
- 댓글 목록
- 좋아요 여부, 좋아요 수
- 현재 로그인한 내 정보

- 화면이 늘어날 때마다 화면 전용 API를 새로 만들어야 한다.
- 어떤 화면은 응답 필드의 절반도 안 쓰는데 전체를 다 받는다.
- 화면 하나 그리려고 네트워크 요청을 서너 번씩 보낸다.
- "이 필드 하나만 추가해주세요" 같은 요청 때문에 프론트와 백엔드가 계속 API 스펙을 맞춰야 한다.

화면마다 API를 새로 만들지 않고,
클라이언트가 "이 화면엔 이 데이터가 필요해요"라고 직접 선언하게 하자.

REST API
  프론트엔드
  → axios / fetch / TanStack Query
  → /users/me, /posts, /comments 같은 REST API 호출
  → 응답 데이터 사용
 
GraphQL + Apollo
  프론트엔드
  → .gql 파일에 필요한 데이터 구조 작성
  → codegen으로 React Hook과 TypeScript 타입 자동 생성
  → Apollo Client가 GraphQL 서버에 요청
  → Apollo Cache에 응답 저장
  → React 컴포넌트에서 useXxxQuery(), useXxxMutation() 사용

GET    /users/me
GET    /posts?page=1
GET    /posts/123
GET    /posts/123/comments
POST   /posts/123/likes
DELETE /posts/123/likes

GET /posts/123
GET /posts/123/comments
GET /users/me
GET /posts/123/like-status

- 화면마다 필요한 데이터가 조금씩 달라진다.
- 기존 API 응답에 필요 없는 필드가 많아진다.
- 새로운 화면을 만들 때마다 백엔드 API 추가가 필요해진다.
- 여러 API를 조합하면 로딩, 에러, 캐시 관리가 복잡해진다.

query PostDetailPage($postId: ID!) {
  post(id: $postId) {
    id
    title
    content
    author {
      id
      nickname
    }
    likeInfo {
      likedByMe
      likeCount
    }
    comments {
      id
      content
      author {
        id
        nickname
      }
    }
  }
  currentUser {
    id
    nickname
  }
}

서버가 정해둔 스키마 안에서,
클라이언트가 필요한 필드만 선택해서 요청한다.

query PostCard($postId: ID!) {
  post(id: $postId) {
    id
    title
    author {
      nickname
    }
  }
}

query PostPage($postId: ID!) {
  post(id: $postId) {
    id
    title
    comments {
      id
      content
    }
  }
  currentUser {
    id
    nickname
  }
}

GraphQL Schema → .gql query/mutation → graphql-codegen → TypeScript 타입 + React Hook

GraphQL = API를 표현하는 언어이자 규격
Apollo Client = React 앱에서 GraphQL을 쉽게 쓰게 해주는 클라이언트 라이브러리

type Query {
  post(id: ID!): Post
  currentUser: User
}
 
type Mutation {
  createComment(input: CreateCommentInput!): Comment!
}
 
type Post {
  id: ID!
  title: String!
  content: String!
  author: User!
  comments: [Comment!]!
}

const { data, loading, error } = usePostDetailQuery({
  variables: { postId },
});

query CurrentUser {
  currentUser {
    id
    nickname
  }
}
 
mutation CreateComment($postId: ID!, $content: String!) {
  createComment(postId: $postId, content: $content) {
    id
    content
    createdAt
  }
}

query PostDetail($postId: ID!) {
  post(id: $postId) {
    id
    title
  }
}

usePostDetailQuery({ variables: { postId: '123' } });

fragment UserProfileFields on User {
  id
  nickname
  profileImageUrl
}
 
query CurrentUser {
  currentUser {
    ...UserProfileFields
  }
}
 
query PostDetail($postId: ID!) {
  post(id: $postId) {
    id
    title
    author {
      ...UserProfileFields
    }
  }
}

query ComparePosts {
  firstPost: post(id: "1") {
    id
  }
  secondPost: post(id: "2") {
    id
  }
}

query PostDetail($postId: ID!, $includeComments: Boolean!) {
  post(id: $postId) {
    id
    comments @include(if: $includeComments) {
      id
    }
  }
}

const resolvers = {
  Query: {
    currentUser: async (_, __, context) => {
      const userId = context.auth.userId;
      return userRepository.findById(userId);
    },
  },
};

currentUser 필드 요청 → resolver 실행 → 로그인한 userId 확인 → DB 조회 → 응답 반환

const resolvers = {
  Post: {
    isBookmarkedLocally: (post) => {
      return localStorage.getItem(`bookmark:${post.id}`) === 'true';
    },
  },
};

query PostCard($postId: ID!) {
  post(id: $postId) {
    id
    isBookmarkedLocally @client
  }
}

① 스키마 확보    →  ② 코드 생성(codegen)  →  ③ 런타임 클라이언트
  (rover)            (graphql-codegen)        (Apollo Client)

# 런타임: 실제 앱에서 쿼리 날리는 라이브러리
npm i @apollo/client graphql
 
# 빌드타임 도구 (devDependencies)
npm i -D @apollo/rover
npm i -D @graphql-codegen/cli @graphql-codegen/typescript \
        @graphql-codegen/typescript-operations \
        @graphql-codegen/typescript-react-apollo

APOLLO_KEY=service:그래프이름:xxxxx      # 인증 키
APOLLO_GRAPH_REF=그래프이름@current      # 어떤 그래프의 어떤 variant

rover graph fetch $APOLLO_GRAPH_REF --output src/graphql/scheme.graphql

// codegen.cjs
{
  schema: ['src/graphql/scheme.graphql'],        // rover가 받은 스키마 (입력)
  documents: ['src/**/*.{ts,tsx,graphql,gql}'],  // 내가 쓴 쿼리들 (입력)
  generates: {
    'src/graphql/typeGenerated.ts': { /* ... */ },  // 순수 타입 (출력)
    'src/graphql/gqlGenerated.ts': { /* ... */ },   // useXxxQuery 훅들 (출력)
  },
}

"gqlgen": "sh gqlgen.sh && TS_NODE_PROJECT=tsconfig.codegen.json graphql-codegen --config codegen.cjs"

1. ApolloClient 생성
2. HttpLink 생성
3. InMemoryCache 생성
4. ApolloProvider로 React 앱 감싸기

import { ApolloClient, InMemoryCache, HttpLink } from '@apollo/client';
 
export const apolloClient = new ApolloClient({
  link: new HttpLink({
    uri: `${API_BASE_URL}/graphql`,
    credentials: 'include',
  }),
  cache: new InMemoryCache(),
});

import { ApolloProvider } from '@apollo/client';
import { apolloClient } from './apolloClient';
 
export function App() {
  return (
    <ApolloProvider client={apolloClient}>
      <Router />
    </ApolloProvider>
  );
}

authLink → localeLink → errorLink → persistedQueryLink → httpLink

import { setContext } from '@apollo/client/link/context';
 
const authLink = setContext((_, { headers }) => {
  const accessToken = localStorage.getItem('accessToken');
  return {
    headers: {
      ...headers,
      authorization: accessToken ? `Bearer ${accessToken}` : '',
    },
  };
});

const localeLink = setContext((_, { headers }) => {
  const locale = getCurrentLocaleFromPathname();
  return {
    headers: { ...headers, 'x-translation-lang': locale },
  };
});

import { onError } from '@apollo/client/link/error';
 
const errorLink = onError(({ graphQLErrors, operation, forward }) => {
  const unauthenticated = graphQLErrors?.some(
    (error) => error.extensions?.code === 'UNAUTHENTICATED',
  );
  if (!unauthenticated) return;
 
  return refreshToken().then((newAccessToken) => {
    operation.setContext(({ headers = {} }) => ({
      headers: { ...headers, authorization: `Bearer ${newAccessToken}` },
    }));
    return forward(operation);
  });
});

요청 A, B, C가 동시에 401 발생
  → A만 refresh token 요청 실행, B/C는 대기
  → 토큰 갱신 완료 → A, B, C 모두 새 토큰으로 재요청

import { ApolloLink, HttpLink } from '@apollo/client';
 
const httpLink = new HttpLink({ uri: `${API_BASE_URL}/graphql` });
const link = ApolloLink.from([authLink, localeLink, errorLink, httpLink]);
 
export const apolloClient = new ApolloClient({ link, cache: new InMemoryCache() });

import { createPersistedQueryLink } from '@apollo/client/link/persisted-queries';
import { sha256 } from 'crypto-hash';
 
const persistedQueryLink = createPersistedQueryLink({ sha256 });

1. 클라이언트가 query 해시만 서버로 전송
2. 서버가 해시를 모르면 PersistedQueryNotFound 에러 반환
3. 클라이언트가 전체 query + 해시를 함께 재전송, 서버가 매핑을 저장
4. 이후 요청부터는 해시만 보내도 서버가 매핑된 query를 찾아 실행

fragment PostCard_post on Post {
  id
  title
  contentPreview
  author {
    id
    nickname
  }
  likeInfo {
    likedByMe
    likeCount
  }
}
 
query PostList($boardSlug: String!, $page: Int!) {
  board(slug: $boardSlug) {
    id
    name
    posts(page: $page) {
      ...PostCard_post
    }
  }
}

npm run gqlgen

import { usePostListQuery } from '@/graphql/gqlGenerated';
 
export function PostListPage() {
  const { data, loading, error } = usePostListQuery({
    variables: { boardSlug: 'free-board', page: 1 },
  });
 
  if (loading) return <div>로딩 중...</div>;
  if (error) return <div>에러가 발생했습니다.</div>;
 
  return (
    <ul>
      {data?.board?.posts.map((post) => (
        <li key={post.id}>{post.title}</li>
      ))}
    </ul>
  );
}

const { data, loading, error } = usePostDetailQuery({
  variables: { postId: '123' },
});

const { data } = useUserPostsQuery({
  variables: { userId: user?.id, page: 1 },
  skip: !user?.id,
});

import { useCreateCommentMutation } from '@/graphql/gqlGenerated';
 
export function CommentForm({ postId }: { postId: string }) {
  const [createComment, { loading }] = useCreateCommentMutation();
 
  const handleSubmit = async (content: string) => {
    await createComment({ variables: { postId, input: { content } } });
  };
 
  return (
    <button disabled={loading} onClick={() => handleSubmit('댓글 내용')}>
      댓글 작성
    </button>
  );
}

await createComment({
  variables: { postId, input: { content } },
  refetchQueries: ['PostComments'],
});

await createComment({
  variables: { postId, input: { content } },
  update: (cache, { data }) => {
    const newComment = data?.createComment;
    if (!newComment) return;
 
    cache.modify({
      id: cache.identify({ __typename: 'Post', id: postId }),
      fields: {
        comments(existingComments = []) {
          const newRef = cache.writeFragment({
            data: newComment,
            fragment: gql`
              fragment NewComment on Comment {
                id
                content
                author {
                  id
                  nickname
                }
              }
            `,
          });
          return [...existingComments, newRef];
        },
      },
    });
  },
});

await likePost({
  variables: { postId },
  optimisticResponse: {
    likePost: {
      __typename: 'PostLikeInfo',
      postId,
      likedByMe: true,
      likeCount: currentLikeCount + 1,
    },
  },
});

{
  "post": {
    "__typename": "Post",
    "id": "1",
    "title": "GraphQL 시작하기",
    "author": { "__typename": "User", "id": "10", "nickname": "eunwoo" }
  }
}

Post:1    { id: 1, title: ..., author: User:10 }
User:10   { id: 10, nickname: eunwoo }

GraphQL 캐싱 여부를 결정하는 요소
- InMemoryCache 사용 여부
- fetchPolicy (cache-first / network-only / no-cache 등)
- query와 variables가 동일한지
- 객체의 id, __typename 기반 정규화 정책

const cache = new InMemoryCache({
  typePolicies: {
    Query: {
      fields: {
        posts: {
          keyArgs: false,
          merge(existing = [], incoming) {
            return [...existing, ...incoming];
          },
        },
      },
    },
  },
});

서버에서 query 실행 → Apollo Cache 추출 → HTML props에 포함
  → 클라이언트 Apollo Cache에 restore → useXxxQuery()가 캐시에서 바로 읽음

// 서버
const apolloClient = createApolloClient({ cookies, locale });
const { data } = await apolloClient.query({
  query: PostDetailDocument,
  variables: { postId: params.postId },
});
const initialApolloState = apolloClient.extract();
 
// 클라이언트
const client = createApolloClient();
client.cache.restore(initialApolloState);

export function ApolloWrapper({ children, initialApolloState }) {
  const clientRef = useRef<ApolloClient<unknown> | null>(null);
  if (!clientRef.current) {
    clientRef.current = createApolloClient({ initialApolloState });
  }
  return <ApolloProvider client={clientRef.current}>{children}</ApolloProvider>;
}
 
export function withApollo(Component) {
  return function ApolloComponent(props) {
    return (
      <ApolloWrapper initialApolloState={props.initialApolloState}>
        <Component {...props} />
      </ApolloWrapper>
    );
  };
}

---
import ApolloPostListTab from '../components/ApolloPostListTab'
---
 
<ApolloPostListTab client:load initialApolloState={initialApolloState} />

서버   → 요청마다 새 Apollo Client 생성
브라우저 → 하나의 Apollo Client를 싱글턴으로 재사용

사용자 A 요청 → currentUser = A → Apollo Cache 저장
사용자 B 요청 → 같은 서버 Apollo Client 재사용 → currentUser = A가 남아 있을 위험

src/graphql/
├── schema.graphql
├── gqlGenerated.ts
├── typeGenerated.ts
└── gql/
    ├── user/
    │   ├── currentUser.gql
    │   └── userProfile.gql
    ├── post/
    │   ├── postList.gql
    │   ├── postDetail.gql
    │   └── mutation/
    │       ├── createPost.gql
    │       └── likePost.gql
    └── comment/
        ├── postComments.gql
        └── mutation/
            └── createComment.gql

1. 화면에 필요한 데이터 정하기 (id, title, author.nickname, likeCount, likedByMe ...)
2. .gql 파일 작성 (fragment + query)
3. npm run gqlgen 실행 → usePostListQuery 등 자동 생성
4. 필요하면 커스텀 훅으로 한 번 감싸기
5. 컴포넌트에서 사용

import { usePostListQuery } from '@/graphql/gqlGenerated';
 
export function useBoardPosts(boardSlug?: string) {
  return usePostListQuery({
    variables: { boardSlug: boardSlug ?? '', page: 1 },
    skip: !boardSlug,
    fetchPolicy: 'cache-and-network',
  });
}

export function BoardPage({ boardSlug }: { boardSlug: string }) {
  const { data, loading, error } = useBoardPosts(boardSlug);
 
  if (loading) return <div>로딩 중...</div>;
  if (error) return <div>게시글을 불러오지 못했습니다.</div>;
 
  return (
    <ul>
      {data?.board?.posts.map((post) => (
        <li key={post.id}>
          <strong>{post.title}</strong>
          <span>{post.author.nickname}</span>
        </li>
      ))}
    </ul>
  );
}

서버 스키마 변경 → gqlgen 실행 → TypeScript 에러 확인 → 깨진 query/타입 수정

개발자가 .gql 파일 작성
  ↓
npm run gqlgen 실행 (rover로 스키마 fetch → codegen 실행)
  ↓
gqlGenerated.ts에 useXxxQuery / useXxxMutation 생성
  ↓
React 컴포넌트에서 자동 생성 Hook 사용
  ↓
Apollo Client가 요청 처리 (Apollo Link 체인 통과)
  ↓
GraphQL 서버에 요청 → 서버 resolver가 실제 데이터 조회 → 응답 반환
  ↓
Apollo InMemoryCache에 저장
  ↓
React 컴포넌트가 data / loading / error로 화면 렌더링

GraphQL은 클라이언트가 필요한 데이터 구조를 선언하는 API 언어이고,
Apollo Client는 React에서 그 GraphQL 요청을 보내고 캐싱하고 상태로 연결해주는 도구다.

1. .gql 작성
2. gqlgen 실행 (스키마 fetch + codegen)
3. useXxxQuery / useXxxMutation 사용
4. Apollo Cache와 refetch 전략 관리