Apollo Client & GraphQL Code generator

Apollo Client란?

Apollo Client 공식문서

Apollo Client는 GraphQL client를 위한 라이브러리로, 클라이언트와 서버 간의 GraphQL 통신을 쉽게 구현할 수 있게 해준다. Apollo Client를 사용하면 클라이언트 애플리케이션에서 GraphQL Query & mutation을 작성하고, 이를 서버로 보내고, 반환된 데이터를 쉽게 관리할 수 있다. 이 라이브러리는 주로 React와 함께 사용되지만, Vue, Angular 등 다른 프론트엔드 프레임워크와도 통합이 가능하다.

Apollo Client의 주요 기능과 특징

1. GraphQL query와 mutation 지원

Apollo Client는 클라이언트 측에서 GraphQL 쿼리와 뮤테이션을 쉽게 수행할 수 있는 기능을 제공한다. 데이터를 가져오기 위한 query, 데이터를 수정하기 위한 mutation을 명령형 코드나 React 훅 등을 통해 작성할 수 있다.

2. 내장된 캐시 기능

Apollo Client는 데이터를 가져올 때 내부적으로 캐싱을 사용하여 불필요한 네트워크 요청을 줄여다. 이를 통해 성능을 최적화하고, 동일한 쿼리에 대해 캐시된 데이터를 재사용할 수 있다. 캐시 정책을 커스터마이즈하여 데이터를 가져오는 방식(cache-first, network-only 등)을 조절할 수 있다.

3. 리액트 훅 지원

Apollo Client는 React와 잘 통합되도록 useQuery, useMutation, useLazyQuery 등과 같은 훅을 제공하여, 선언적이고 직관적인 방식으로 GraphQL 요청을 처리할 수 있다. useQuery를 사용하여 데이터를 가져오고, useMutation으로 서버에 데이터를 변경하는 요청을 보낼 수 있다.

4. 에러 처리와 로딩 상태 관리

Apollo Client는 로딩 상태와 에러 상태를 쉽게 관리할 수 있는 기능을 내장하고 있습니다. loading, error, data 등의 속성을 통해 네트워크 요청의 상태를 추적할 수 있다.

5. 서버 간 데이터 페칭과 글로벌 상태 관리

Apollo Client는 GraphQL API를 사용하여 서버로부터 데이터를 가져오는 것뿐만 아니라, 클라이언트 측의 글로벌 상태 관리를 위한 도구로도 사용할 수 있다.

Apollo Client Setting

# graphql이 설치 안 되어 있으면 뒤에 graphql도 같이 설치
npm install @apollo/client

Apollo Client Config

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

const client = new ApolloClient({
	uri: process.env.NEXT_PUBLIC_BACK_GRAPHQL_URI,
	cache: new InMemoryCache(),
});

export default client;

설치가 완료되었으면, Apollo Client Instance를 생성해야 한다. 백엔드의 url과 함께 /graph를 넣어줘야 하고, cache 기능을 활성화하기 위해 cache 부분에 new InMemoryCache() 를 설정해줘야 한다.

Apollo Client advanced Setting

Authorization 헤더 추가

인증이 필요한 GraphQL 서버의 경우, 요청 시 헤더에 토큰을 포함해야 한다. 이를 위해 setContext를 사용하여 ApolloClient instance를 생성할 때 HttpLink와 함께 설정할 수 있다.

import { ApolloClient, InMemoryCache, HttpLink } from '@apollo/client';
import { setContext } from '@apollo/client/link/context';

const httpLink = new HttpLink({
  uri: process.env.NEXT_PUBLIC_BACK_GRAPHQL_URI,
});

const authLink = setContext((_, { headers }) => {
  const token = localStorage.getItem('auth-token');
  return {
    headers: {
      ...headers,
      authorization: token ? `Bearer ${token}` : "",
    }
  }
});

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

file Upload

apollo-upload-client는 Apollo Client에서 파일 업로드를 처리하기 위한 패키지이다. 주로 파일 업로드를 위해 만들어진 라이브러리로써, 일반적인 multipart/form-data 형식 요청으로 파일을 전송하며, GraphQL 서버는 이를 처리하여 업로드된 파일을 사용할 수 있다. 또한, 파일 업로드가 포함된 GraphQL 요청을 다를 수 있는 createUploadLink를 제공하며, mutation으로 다른 데이터와 함께 병합하여 파일을 전송할 수 있다.

import { ApolloClient, InMemoryCache, ApolloLink } from '@apollo/client';
import { createUploadLink } from 'apollo-upload-client';
import { setContext } from '@apollo/client/link/context';

// 업로드 링크 설정
const uploadLink = createUploadLink({
	uri: process.env.NEXT_PUBLIC_BACK_GRAPHQL_URI,
});

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

// Apollo Client 생성
const client = new ApolloClient({
  link: ApolloLink.from([authLink, uploadLink]),
  cache: new InMemoryCache(),
});

export default client;

InMemoryCache

1. 데이터 저장 및 관리

GraphQL 요청을 통해 서버에서 받아온 데이터를 메모리에 저장하고, 필요한 경우 해당 데이터를 재사용한다.
데이터는 각 필드의 식별자를 기준으로 저장되며, 동일한 ID를 가진 데이터가 여러 쿼리에서 반환되면, 중복 저장을 방지하고 메모리 효율성을 높인다.

2. 캐시 정책 설정

Apollo Client 캐싱 전략을 통해 데이터를 관리할 수 있다. 예를 들어, cache-first, network-only, cache-and-network 등 다양한 정책을 사용하여 데이터를 어떻게 가져올지 제어한다. 이러한 캐시 정책을 통해 성능을 최적화하고, 네트워크 요청을 최소화할 수 있다.

3. 데이터 병합 및 갱신

InMemoryCache는 기존의 데이터를 새로 받아온 데이터와 병합하거나 갱신할 수 있다. 예를 들어, 페이지네이션된 데이터를 가져올 때, 기존 데이터에 새로운 데이터를 추가하는 병합 작업을 할 수 있다. 이를 위해 typePolicies와 merge 함수를 사용해 캐싱 동작을 커스터마이즈할 수 있다.

4. 쿼리 결과 캐싱

쿼리 결과를 캐시에 저장하고, 동일한 쿼리가 발생하면 캐시에서 즉시 결과를 반환한다. 이 과정에서 네트워크 요청을 생략하여 성능을 향상시킨다. 쿼리별로 캐시된 데이터를 기반으로 partial results를 반환하거나, 네트워크 요청을 통해 최신 데이터를 가져올 수 있다.

layout.tsx

// src/app/layout.tsx
"use client"

import { ApolloProvider } from '@apollo/client';
import './globals.css'
import { Inter } from 'next/font/google'

const inter = Inter({ subsets: ['latin'] })

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="ko">
      <body className={inter.className}>
        <ApolloProvider client={client}>
          {children}
        </ApolloProvider>
      </body>
    </html>
  )
}

이런식으로 root 파일에 설정하면 apollo client을 사용할 수 있다. Next 13버전 이상을 사용한다면 반드시 최상단에 use client를 붙여야한다. apollo client 같은 경우 말 그대로 client이기 때문이다.

GraphQL Code Generator

GraphQL Code Generator란 GraphQL schema query mutation 등을 기반으로 타입 안전한 코드를 자동으로 생성하는 도구다. 이 도구는 GraphQL API를 사용하는 프로젝트에서 Typescript, React Hooks, Apollo Client 등의 환경에서 안전하게 GraphQL을 활용할 수 있도록 지원한다. 내가 생각하기엔 GraphQL Code Generator의 가장 큰 장점은 Schema / Query / Mutation / Fragment를 기반으로 타입스크립트 타입을 자동 생성하는 것이다. 이는 API 변경에 따라 생길 수 있는 오류를 컴파일 시점에 쉽게 잡을 수 있다. 또한 GraphQL documents(query, mutation, fragment)를 작성하면, 해당 문서를 기반으로 타입 정의와 관련된 코드를 자동으로 생성한다. React용 Apollo Hooks, GraphQL 요청 함수 등 다양한 형태의 코드를 생성할 수 있다. 또한 다양한 풀러그인이 지원하여 developer가 필요한 코드 형태로 생성할 수 있다.

GraphQL Code Generator Setting

npm install @graphql-codegen/cli @graphql-codegen/typescript @graphql-codegen/typescript-operations @graphql-codegen/typescript-react-apollo@graphql-codegen/typescript-react-apollo

GraphQL Code Generator Config

GraphQL codegen 공식문서
다음은 공식 문서에서 나오는 GraphQL Code Generator config이다

import { CodegenConfig } from '@graphql-codegen/cli'
 
const config: CodegenConfig = {
  schema: 'http://localhost:4000/graphql',
  documents: ['src/**/*.tsx'],
  generates: {
    './src/gql/': {
      preset: 'client'
    }
  }
}
 
export default config

GraphQL Code Generator는 Config를 통해서 code generator를 생성한다. code generator 설명이 부족한 거 같아서 간단하게 code generator에 대해서 설명을 하겠다. code generator는 소프트웨어 개발에서 특정한 규칙이나 템플릿에 따라 자동으로 코드를 생성하는 도구이다. 이를 통해 반복적인 코딩 작업을 줄이고 일관성 있는 코드를 빠르게 생성하는 데 유용하게 사용된다.

Config Setting

• Schema - GraphQL의 타입을 정의하는 Schema는 schema의 path나 URL을 지정한다.
  schema는 GraphQL API의 스키마 정의를 나타낸다. 이는 server에서 제공하는 data, type, query, mutation 등을 정의한 것이다. schema는 코드 생성에 있어서 타입 정보를 제공하는 기본 자료로 사용된다. GraphQL Code Generator는 이 schema를 기반으로 type, query muation input / output type 생성한다.

• Document - GraphQL query, mutation, fragment를 포함하는 file path를 지정한다.
  Documents는 실제로 사용할 GraphQL query, mutation, fragment가 포함된 파일들이다. Code Generator는 이 documents 파일들을 분석하여 각 query mutation에 맞는 타입을 생성하고, 자동으로 해당 GraphQL 연산에 맞는 React 훅(useQuery, useMutation 등) 등을 만들어준다.

• generates - 파일을 생성할 경로와 옵션들을 정의한다. 이 속성 아래에 여러 경로를 설정할 수 있다. 각 경로 아래에 plugins, preset, presetConfig 등의 세부 설정을 포함한다.
  - plugins(client에서 주로 사용하는 plugins)
  1. typescript : GraphQL schema를 기반으로 typescript type을 생성한다. 각 schema type에 맞는 interface, type을 자동으로 만들어준다. 가장 기본적인 플러그인 중 하나로, 다른 플러그인과 함께 사용됩니다.
  2. typescript-operations : GraphQL query, mutation, subscript input과 output type을 typescript로 생성한다. 위 schema 기준으로 typescript를 만든다. documents에서 정의된 실제 GraphQL 연산에 대한 타입 정보를 제공한다.
  3. typescript-react-apollo : Apollo Client와 통합되어 React 훅(useQuery, useMutation, useSubscription 등)을 생성한다. 자동으로 생성된 훅을 사용하여 GraphQL query와 mutation을 쉽게 사용할 수 있다. document를 기준으로 react hook을 자동으로 생성해준다. config에서 withHooks( GraphQL 쿼리, 뮤테이션, 서브스크립션을 위한 React 훅을 생성) 옵션을 통해 훅을 활성화할 수 있으며, withComponent(생성된 컴포넌트는 클래스형 또는 함수형 컴포넌트로 GraphQL 요청을 수행하며, 렌더링에 필요한 props를 전달하여 데이터를 처리), withHOC(withComponent의 상위호환 Component를 HOC 형태로 만들어 데이터 로딩 로직을 컴포넌트 외부로 추상화할 수 있음.) 등의 옵션도 설정 가능하다. 최근 trend로 withHooks를 true만 사용한다.

• preset (자주 쓰이는 것만)

1. client 단일 파일로 모든 type 정의와 hook을 생성한다. 단일 파일이라고 하면 한 파일로 전부 설정값이 들어가는 게 아니라, 모든 생성된 파일이 하나의 directory에 모인다는 의미이다. 장단점이 존재하지만 한 파일내에 type / mutation / query를 정의하기 때문에 규모가 커지면 커질수록 가독성이 떨어질 수 있다.
2. near-operation-file 각 GraphQL 파일 옆에 타입을 생성한다. 이는 단점일 수 있는 게 각 graphql별로 type / mutation / query`를 정의하기 때문에 폴더가 더러워질 수 있지만, 하나당 하나의 파일을 정의하기 때문에 가독성 측면에선 유용할 수 있다.

• config - 위에서 봤던 withHooks / withComponent / withHOC 설정도 config에서 설정한다. 추가적으로 scalars 를 보면

export type Scalars = {
  ID: { input: string; output: string; }
  String: { input: string; output: string; }
  Boolean: { input: boolean; output: boolean; }
  Int: { input: number; output: number; }
  Float: { input: number; output: number; }
  DateTime: { input: any; output: any; }
};

GraphQL Codegen에서 scalars는 기본적으로 타입이 정의되지 않은 커스텀 스칼라 타입에 대해 any로 매핑된다. 이는 GraphQL 스키마에서 제공하는 기본 스칼라 타입(예: Int, Float, String, Boolean, ID) 외에 사용자 정의 스칼라 타입(예: DateTime, Upload)이 있을 때, 자동으로 매핑할 수 있는 타입이 없기 때문이다. 그래서 우리는 codegen config에서 따로 설정을 해줘야 한다.

config: {
  	withHooks: true,
    withComponent: false,
    withHOC: false,
    scalars: {
    	DateTime: 'Date',
	},
},
// scalars
export type Scalars = {
  ID: { input: string; output: string; }
  String: { input: string; output: string; }
  Boolean: { input: boolean; output: boolean; }
  Int: { input: number; output: number; }
  Float: { input: number; output: number; }
  DateTime: { input: Date; output: Date; }
};

• overwrite - overwrite 속성은 GraphQL Code Generator가 생성된 파일을 덮어쓸 지 여부를 결정한다.
  overwrite: true로 설정하면, 기존에 생성된 파일이 있어도 새로운 파일로 덮어쓴다. 즉, 매번 코드 생성 시 파일을 새로 갱신하는 역할을 한다.
  overwrite: false로 설정하면, 기존 파일이 있을 때 덮어쓰지 않고, 파일이 없는 경우에만 새로 생성한다. 일반적으로 overwrite: true로 설정하여 파일을 항상 최신 상태로 갱신하도록 설정하는 것이 일반적이다.

codegenConfig.ts

// codegenConfig.ts 

import type { CodegenConfig } from '@graphql-codegen/cli';
import dotenv from 'dotenv';

// 환경 변수 불러오기

dotenv.config();

const config: CodegenConfig = {
	overwrite: true,
	schema: process.env.NEXT_PUBLIC_BACK_GRAPHQL_URL,
	generates: {
		'./src/graphql/types.ts': {
			plugins: ['typescript'],
			config: {
				scalars: {
					DateTime: 'Date',
				},
			},
		},
		'./src/': {
			documents: ['src/graphql/queries/**/*.graphql', 'src/graphql/mutations/**/*.graphql'],
			preset: 'near-operation-file',
			presetConfig: {
				extension: '.generated.ts',
				baseTypesPath: 'types.ts',
			},
			plugins: ['typescript-operations', 'typescript-react-apollo'],
			config: {
				withHooks: true,
				withComponent: false,
				withHOC: false,
				scalars: {
					DateTime: 'Date',
				},
			},
		},
	},
};

export default config;

GraphQL Codegen Implement

기본적인 형식은 다음과 같다

npx graphql-codegen --config ./path/to/codegenConfig.ts

필자는 package.json에 script로 따로 설정했다.

"codegen": "graphql-codegen --config ./config/codegenConfig.ts"

시행착오

수많은 시행착오가 있었지만, 결론적으로 말하자면 preset - "client"를 사용하면 안된다.. 타입들이.. 중복된다고.. 선언했던 거 또 선언되서 이거 해결하려고 몇 시간 넘게 쓴 거 같다.. 그래서.. 결론적으로 near-operation-file를 사용하기로 했다.
근데 이것도 문제가 발생했다.

import type { CodegenConfig } from '@graphql-codegen/cli';
import dotenv from 'dotenv';
// 환경 변수 불러오는 방법
dotenv.config();

const config: CodegenConfig = {
	overwrite: true,
	schema: process.env.NEXT_PUBLIC_BACK_GRAPHQL_URL,
	generates: {
		'./src/types.ts': {
          // type 정의 파일
			plugins: ['typescript'],
			config: {
				scalars: {
					DateTime: 'Date',
				},
			},
		},
		'./src/': {
          // 나머지(query / mutation / 최종 custom hook setting)
			documents: ['src/graphql/queries/*.graphql', 'src/graphql/mutations/*.graphql'],
			preset: 'near-operation-file', // client로 설정하지 않고, near-opeartion-file로 설정
			presetConfig: {
				extension: '.generated.ts',
				baseTypesPath: 'types.ts',
			},
			plugins: ['typescript-operations', 'typescript-react-apollo'],
			config: {
				withHooks: true, // customhook 생성
				withComponent: false,
				withHOC: false,
				scalars: {
					DateTime: 'Date',
				},
			},
		},
	},
};



export default config;

최종 전에 CodegenConfig였다. 이렇게 해서 npm run codegen 를 실행했더니 다음과 같이 나왔다.

이게 mutation 폴더에 있었다.. 헉.. 너무 폴더가 더러워졌다는 생각이 들지 않는가? near-operation-file 말 그대로 graphql 선언한 곳 바로 옆에 generated.ts를 생성한다는 얘기다. 필자는 더럽다는 생각이 들면서도 한편으로는 이제 코드 에러가 뜨지 않는다!!! 라는 생각이 들었다.

다음은 최종 폴더 구조이다. 사실 맞는 지 안 맞는 지는 모르겠지만 현재 내 최선이라고 생각한다.

각 query & mutation 별로 directory를 만들었고 directory 내부로 들어가면 다음과 같다. (추후 페이지 별로 query와 mutation을 묶을 거 같긴 하다. )

파일 내에서도 가독성이 높아지면서 폴더구조도 깔끔해졌다.

GraphQL Codegen result

type.ts

'./src/types.ts': {
  // type 정의 파일
  plugins: ['typescript'],
    config: {
      scalars: {
        DateTime: 'Date',
      },
      },
    }

type.ts는 말그대로 GraphQL schema에 대한 모든 type을 정의한 것이다. 말로만 들으면 이해가 안 될수도 있으니 하나씩 차근차근 어떤 게 정의되었는 지 확인해보자.

Scalars

export type Scalars = {
  ID: { input: string; output: string; }
  String: { input: string; output: string; }
  Boolean: { input: boolean; output: boolean; }
  Int: { input: number; output: number; }
  Float: { input: number; output: number; }
  DateTime: { input: Date; output: Date; }
};

Scalars란, GraphQL Schema에서 사용되는 기본 데이터 타입을 말한다. GraphQL에서 사용하는 타입과 Typescript에서 사용하는 타입은 다르기 때문에, Scalars를 선언해야 Typescript에서 GraphQL 타입을 사용할 수 있다.

Schema

export type BoardSchema = {
  __typename?: 'BoardSchema';
  _id: Scalars['ID']['output'];
  author: Scalars['String']['output'];
  boardAddressOutput?: Maybe<BoardAddressOutput>;
  boardId: Scalars['Int']['output'];
  content: Scalars['String']['output'];
  createdAt: Scalars['DateTime']['output'];
  imageUrl?: Maybe<Array<Scalars['String']['output']>>;
  title: Scalars['String']['output'];
  updatedAt: Scalars['DateTime']['output'];
  youtubeUrl?: Maybe<Scalars['String']['output']>;
};

다음은 Schema 기반으로 생성된 Typescript이다.첫 번째 인자로 스칼라 타입의 이름을 사용하고, 두 번째 인자로 입력 타입 또는 출력 타입을 지정하여 타입을 결정한다.

Mutation & Query

// mutation
export type Mutation = {
  __typename?: 'Mutation';
  clearBoard: Scalars['Boolean']['output'];
  createBoard: BoardSchema;
  createBoardComment: BoardCommentResponseDto;
  deleteBoard: Scalars['Boolean']['output'];
  deleteBoardComment: Scalars['Boolean']['output'];
  isPasswordCorrect: Scalars['Boolean']['output'];
  updateBoard: BoardSchema;
  updateBoardComment: BoardCommentResponseDto;
};

// query
export type Query = {
  __typename?: 'Query';
  getBoard: BoardSchema;
  getBoardComment: Array<BoardCommentResponseDto>;
  getBoardReaction: BoardReactionSchema;
  getBoards: BoardPaginationResponse;
};

GraphQL의 Mutation Schema를 TypeScript 타입으로 변환한 것이며, 각 Mutation의 출력 타입을 지정해주는 역할을 한다.

Args

export type MutationCreateBoardArgs = {
  createBoardInput: CreateBoardInput;
};

다음은 mutation의 args의 타입을 정의한다. 이미 Schema에서 선언한 걸 그대로 사용하면 되니 큰 문제는 없다.

지금 flow를 보면 Scalar -> Schema -> Mutation & Query -> Args로 타입을 선언하고 있다. !!! 이는 Scalar를 먼저 선언해야 Schema를 선언할 수 있고, 이를 기반으로 mutation / query / args를 선언할 수 있기 때문이다.

graphql.ts

mutation CreateBoard($createBoardInput: CreateBoardInput!) {
    createBoard(createBoardInput: $createBoardInput) {
        author
        title
        content
        imageUrl
        youtubeUrl
        boardAddressOutput {
            zoneCode
            address
            detailAddress
        }
        createdAt
    }
}

아 맞다. 갑자기 생각난건데!!! Codegen을 사용하려면, 반드시 먼저 graphql을 선언해야한다. !!!! codegen은 document과 schema를 기반으로 타입과 실제 사용할 query와 mutation을 지정해주기 때문이다.!!

흔한 mutation graphql이다. 우리는 createBoardInput을 args로 받아야 하기 때문에, $createBoardInput 으로 args를 받아야한다. GraphQL에서의 $는 변수를 의미한다. args로 createBoardInput을 받고 끝나면 response로 자신이 원하는 데이터만!!!!! 받을 수 있다.

generated.ts

Mutation

/** @format */

import * as Apollo from '@apollo/client';
import * as Types from '../../../types';

import { gql } from '@apollo/client';

const defaultOptions = {} as const;
export type CreateBoardMutationVariables = Types.Exact<{
	createBoardInput: Types.CreateBoardInput;
}>;

export type CreateBoardMutation = {
	__typename?: 'Mutation';
	createBoard: {
		__typename?: 'BoardSchema';
		author: string;
		title: string;
		content: string;
		imageUrl?: Array<string> | null;
		youtubeUrl?: string | null;
		createdAt: Date;
		boardAddressOutput?: {
			__typename?: 'BoardAddressOutput';
			zoneCode: number;
			address: string;
			detailAddress: string;
		} | null;
	};
};

export const CreateBoardDocument = gql`
	mutation CreateBoard($createBoardInput: CreateBoardInput!) {
		createBoard(createBoardInput: $createBoardInput) {
			author
			title
			content
			imageUrl
			youtubeUrl
			boardAddressOutput {
				zoneCode
				address
				detailAddress
			}
			createdAt
		}
	}
`;
export type CreateBoardMutationFn = Apollo.MutationFunction<
	CreateBoardMutation,
	CreateBoardMutationVariables
>;

/**
 * __useCreateBoardMutation__
 *
 * To run a mutation, you first call `useCreateBoardMutation` within a React component and pass it any options that fit your needs.
 * When your component renders, `useCreateBoardMutation` returns a tuple that includes:
 * - A mutate function that you can call at any time to execute the mutation
 * - An object with fields that represent the current status of the mutation's execution
 *
 * @param baseOptions options that will be passed into the mutation, supported options are listed on: https://www.apollographql.com/docs/react/api/react-hooks/#options-2;
 *
 * @example
 * const [createBoardMutation, { data, loading, error }] = useCreateBoardMutation({
 *   variables: {
 *      createBoardInput: // value for 'createBoardInput'
 *   },
 * });
 */
export function useCreateBoardMutation(
	baseOptions?: Apollo.MutationHookOptions<CreateBoardMutation, CreateBoardMutationVariables>,
) {
	const options = { ...defaultOptions, ...baseOptions };
	return Apollo.useMutation<CreateBoardMutation, CreateBoardMutationVariables>(
		CreateBoardDocument,
		options,
	);
}
export type CreateBoardMutationHookResult = ReturnType<typeof useCreateBoardMutation>;
export type CreateBoardMutationResult = Apollo.MutationResult<CreateBoardMutation>;
export type CreateBoardMutationOptions = Apollo.BaseMutationOptions<
	CreateBoardMutation,
	CreateBoardMutationVariables
>;

다음은 GraphQL Code generator가 생성해준 generated.ts이다. preset을 near-operation-file 으로 설정했기 때문에 graphql.ts가 존재하는 같은 directory에 생성되었다.

MutationVariables

export type CreateBoardMutationVariables = Types.Exact<{
	createBoardInput: Types.CreateBoardInput;
}>;

type.ts 선언한 타입들을 그대로 사용하면 된다. 우리가 graphql.ts에서 선언한 mutation에서 $createBoardInput에 대한 타입을 선언한 것이다.

CreateBoardMutation

export type CreateBoardMutation = {
	__typename?: 'Mutation';
	createBoard: {
		__typename?: 'BoardSchema';
		author: string;
		title: string;
		content: string;
		imageUrl?: Array<string> | null;
		youtubeUrl?: string | null;
		createdAt: Date;
		boardAddressOutput?: {
			__typename?: 'BoardAddressOutput';
			zoneCode: number;
			address: string;
			detailAddress: string;
		} | null;
	};
};

graphql.ts에서 선언한 mutation에서 output(response)로 들어오는 값의 타입을 선언한 것이다.

CreateBoardDocument

export const CreateBoardDocument = gql`
	mutation CreateBoard($createBoardInput: CreateBoardInput!) {
		createBoard(createBoardInput: $createBoardInput) {
			author
			title
			content
			imageUrl
			youtubeUrl
			boardAddressOutput {
				zoneCode
				address
				detailAddress
			}ㄷ
			createdAt
		}
	}
`;

graphql.ts에서 선언한 gql mutation을 변수화 시킨 것이다. 주로 Document는 GraphQL client에서 해당 mutation을 호출할 때 사용한다.

CreateBoardMutationFn

export type CreateBoardMutationFn = Apollo.MutationFunction<
	CreateBoardMutation,
	CreateBoardMutationVariables
>;

useMutation을 사용할 때 input type과 output type을 지정하는 역할을 한다. 사실.. generic으로 이미 input type과 output type을 확인하기 때문에 한 번 더 확인할 필요가 없다.

useMutation 예시

// variable이 정적 데이터인 경우 createBoard에서 variable을 선언하지 말고
// 애초에 useMutation을 선언할 때 정적 데이터 createBoardInput을 넣기
const [createBoard, { data, loading, error }] = useMutation<CreateBoardMutation, CreateBoardMutationVariables>(CreateBoardDocument, {
	variables: {
    	createBoardInput,
    },
})

useMutation의 첫 번째 제네릭은 output type을 의미하고, 두 번쨰 제네릭은 input type을 의미한다. 이로 인해 createBoardMutationFn이 필요없다. useMutation 인자로 gql 을 넣어야하지만, 우리는 king God Codegenerator가 알아서 변수화시켜주기 때문에, CreateBoardDocument를 불러오면 된다.

useCreateBoardMutation

code generator는 친절하게 예시도 적어준다(이렇게 쓰세요~) 당연히 config에 withHooks: true 속성을 넣어줘야한다.

/**
 * __useCreateBoardMutation__
 *
 * To run a mutation, you first call `useCreateBoardMutation` within a React component and pass it any options that fit your needs.
 * When your component renders, `useCreateBoardMutation` returns a tuple that includes:
 * - A mutate function that you can call at any time to execute the mutation
 * - An object with fields that represent the current status of the mutation's execution
 *
 * @param baseOptions options that will be passed into the mutation, supported options are listed on: https://www.apollographql.com/docs/react/api/react-hooks/#options-2;
 *
 * @example
 * const [createBoardMutation, { data, loading, error }] = useCreateBoardMutation({
 *   variables: {
 *      createBoardInput: // value for 'createBoardInput'
 *   },
 * });
 */

예시를 보면 baseOptions가 있는데, 아쉽게도 해당 링크로 들어가면,, Not Found 404가 발생한다. 그래서.. 필자가 하나씩 찾아봤다.

자주 쓰이는 거
variables - Mutation에서 사용할 변수를 설정한다.
onCompleted - Mutation이 성공적으로 완료된 후 실행되는 콜백 함수
onError - Mutation 중 에러가 발생했을 때 실행되는 콜백 함수
refetchQueries - Mutation이 성공적으로 실행된 후 다시 가져올 쿼리 목록을 지정합니다.
추가적인 옵션들
optimisticResponse - 낙관적 응답을 설정하여, 서버에서 응답이 오기 전에 캐시를 업데이트할 수 있다. 예를 들어, 데이터가 변경되었다는 가정 하에 UI를 미리 업데이트하여 더 나은 사용자 경험을 제공한다.
update - Mutation 결과를 캐시에 어떻게 반영할지 직접 제어할 수 있다. 캐시를 수동으로 업데이트하거나, 서버에서 반환된 데이터를 기반으로 캐시 데이터를 조작할 때 사용된다.
context - 요청과 함께 전송할 추가적인 컨텍스트 정보를 설정할 수 있다. 예를 들어, 헤더나 인증 토큰을 추가할 때 사용한다.
awaitRefetchQueries - refetchQueries를 사용한 후, 해당 쿼리가 다시 가져와질 때까지 기다릴지 여부를 설정한다. true로 설정하면 refetchQueries가 완료된 후에야 Mutation이 완료된다.
errorPolicy - 에러 정책을 설정하여, 에러가 발생했을 때 Mutation이 어떻게 동작할지를 결정한다. 예를 들어, none, ignore, all 중 하나를 선택할 수 있다.
fetchPolicy - 데이터 가져오기 정책을 설정합니다. 예를 들어, network-only, cache-first, no-cache 등을 설정하여 캐시와 네트워크 요청 간의 우선순위를 정할 수 있다.
notifyOnNetworkStatusChange - 네트워크 상태가 변경될 때마다 컴포넌트를 리렌더링할지 여부를 설정한다.
client - 특정 Apollo 클라이언트를 사용하여 Mutation을 실행할 수 있도록 설정한다. 기본적으로는 제공된 Apollo 클라이언트를 사용하지만, 여러 클라이언트가 있는 경우 특정 클라이언트를 지정할 수 있다

export function useCreateBoardMutation(
	baseOptions?: Apollo.MutationHookOptions<CreateBoardMutation, CreateBoardMutationVariables>,
) {
	const options = { ...defaultOptions, ...baseOptions };
	return Apollo.useMutation<CreateBoardMutation, CreateBoardMutationVariables>(
		CreateBoardDocument,
		options,
	);
}

그냥 아에 generated에서 mutation 관련 속성들을 전부 선언해버렸다.

useCreateBoardMuation이 얼마나 사기인지.. 설명해드릴께요..

// GraphQL Codegenerator를 사용하지 않았을 경우 
import { gql } from '@apollo/client';

// GraphQL Mutation 문서
export const CreateBoardDocument = gql`
	mutation CreateBoard($createBoardInput: CreateBoardInput!) {
		createBoard(createBoardInput: $createBoardInput) {
			author
			title
			content
			imageUrl
			youtubeUrl
			boardAddressOutput {
				zoneCode
				address
				detailAddress
			}
			createdAt
		}
	}
`;

// CreateBoardMutationVariables 타입 정의
export type CreateBoardMutationVariables = {
	createBoardInput: {
		author: string;
		title: string;
		content: string;
		password: string;
		imageUrl?: string[];
		youtubeUrl?: string;
	};
};

// CreateBoardMutation 응답 타입 정의
export type CreateBoardMutation = {
	createBoard: {
		author: string;
		title: string;
		content: string;
		imageUrl?: string[] | null;
		youtubeUrl?: string | null;
		createdAt: string;
		boardAddressOutput?: {
			zoneCode: number;
			address: string;
			detailAddress: string;
		} | null;
	};
};

const [createBoard, { data, loading, error }] = useMutation<CreateBoardMutation, CreateBoardMutationVariables>(CreateBoardDocument);


// useCreateBoardMuation를 사용하지 않았을 때
// codegenerator를 사용했지만 여전히 코드 길이가 길다
// 위와 다른 점은 createBoardMutation과 CreateBoardMutationVariables은 직접 선언할 필요가 없다.
// 하지만 `gql`은 무조건 선언해줘야한다. 
const [createBoard, { data, loading, error }] = useMutation<CreateBoardMutation, CreateBoardMutationVariables>(CreateBoardDocument, {
	variables: {
    	createBoardInput,
    },
})

// useCreateBoardMuation 사용했을 때
const [createBoard, { data, loading, error }] = useCreateBoardMuation({
	variables: {
    	createBoardInput,
    },
})

저렇게 긴 코드를.. generated Hook 하나로 딸각.. 할 수 있다. 저렇게 쓰려면 반드시 !! withHooks: true를 넣어야 한다.

나머지

// [mutationFunction, { data, loading, error }]
export type CreateBoardMutationHookResult = ReturnType<typeof useCreateBoardMutation>;
// { data, loading, error }
export type CreateBoardMutationResult = Apollo.MutationResult<CreateBoardMutation>;
// inputType & outputType / baseOptions 정의
export type CreateBoardMutationOptions = Apollo.BaseMutationOptions<
	CreateBoardMutation,
	CreateBoardMutationVariables
>;

Query

import * as Apollo from '@apollo/client';
import * as Types from '../../../types';

import { gql } from '@apollo/client';

const defaultOptions = {} as const;
export type GetBoardsQueryVariables = Types.Exact<{
	page?: Types.InputMaybe<Types.Scalars['Int']['input']>;
	take?: Types.InputMaybe<Types.Scalars['Int']['input']>;
}>;

export type GetBoardsQuery = {
	__typename?: 'Query';
	getBoards: {
		__typename?: 'BoardPaginationResponse';
		totalCount: number;
		result: Array<{
			__typename?: 'BoardSchema';
			author: string;
			title: string;
			boardId: number;
			createdAt: Date;
		}>;
	};
};

export const GetBoardsDocument = gql`
	query GetBoards($page: Int, $take: Int) {
		getBoards(page: $page, take: $take) {
			result {
				author
				title
				boardId
				createdAt
			}
			totalCount
		}
	}
`;

/**
 * __useGetBoardsQuery__
 *
 * To run a query within a React component, call `useGetBoardsQuery` and pass it any options that fit your needs.
 * When your component renders, `useGetBoardsQuery` returns an object from Apollo Client that contains loading, error, and data properties
 * you can use to render your UI.
 *
 * @param baseOptions options that will be passed into the query, supported options are listed on: https://www.apollographql.com/docs/react/api/react-hooks/#options;
 *
 * @example
 * const { data, loading, error } = useGetBoardsQuery({
 *   variables: {
 *      page: // value for 'page'
 *      take: // value for 'take'
 *   },
 * });
 */
export function useGetBoardsQuery(
	baseOptions?: Apollo.QueryHookOptions<GetBoardsQuery, GetBoardsQueryVariables>,
) {
	const options = { ...defaultOptions, ...baseOptions };
	return Apollo.useQuery<GetBoardsQuery, GetBoardsQueryVariables>(GetBoardsDocument, options);
}
export function useGetBoardsLazyQuery(
	baseOptions?: Apollo.LazyQueryHookOptions<GetBoardsQuery, GetBoardsQueryVariables>,
) {
	const options = { ...defaultOptions, ...baseOptions };
	return Apollo.useLazyQuery<GetBoardsQuery, GetBoardsQueryVariables>(GetBoardsDocument, options);
}
export function useGetBoardsSuspenseQuery(
	baseOptions?:
		| Apollo.SkipToken
		| Apollo.SuspenseQueryHookOptions<GetBoardsQuery, GetBoardsQueryVariables>,
) {
	const options =
		baseOptions === Apollo.skipToken ? baseOptions : { ...defaultOptions, ...baseOptions };
	return Apollo.useSuspenseQuery<GetBoardsQuery, GetBoardsQueryVariables>(
		GetBoardsDocument,
		options,
	);
}
export type GetBoardsQueryHookResult = ReturnType<typeof useGetBoardsQuery>;
export type GetBoardsLazyQueryHookResult = ReturnType<typeof useGetBoardsLazyQuery>;
export type GetBoardsSuspenseQueryHookResult = ReturnType<typeof useGetBoardsSuspenseQuery>;
export type GetBoardsQueryResult = Apollo.QueryResult<GetBoardsQuery, GetBoardsQueryVariables>;

친절하게도 여기에도 useGetBoardsQuery를 어떻게 사용해야하는 지 설명해준다.
mutation과 다르게 query는 useGetBoardsLazyQuery & useGetBoardsSuspenseQuery를 지원한다.

useGetBoardsLazyQuery

query를 페이지 들어갈 때 실행되는 게 아닌 필요할 때 명시적으로 호출하여 데이터를 가져오는 Lazy Query입니다. 트리거 시점에 유연하게 쿼리를 실행하고 싶을 때 유용하다. 예를 들어서, 버튼 클릭 시 query를 실행하거나, 특정 조건이 충족되었을 때 query를 실행할 때 사용한다.

useGetBoardsSuspenseQuery

Suspense Query는 React의 Suspense를 활용하여 데이터 패칭의 비동기 상태를 관리하는 방법입니다. useGetBoardsSuspenseQuery는 React의 Suspense 컴포넌트와 함께 사용되어, 데이터가 로딩 중일 때 자동으로 로딩 상태를 관리해준다. Suspense와 함께 로딩 중일 때 대체 UI를 정의할 수 있다.

마찬가지로 가독성 측면에서 훨씬 뛰어나다는 사실을 알 수 있다.

const { data, loading, error } = useQuery<GetBoardsQuery, GetBoardsQueryVariables>(GetBoardsDocument, {
   variables: {
      page,
      take,
  },
});

const { data, loading, error } = useGetBoardsQuery({
   variables: {
      page,
      take,
  },
});