GrahpQL Codegen으로 타입 안전성 높이기!

GraphQL이란?

Graphql은 SQL과 동일한 쿼리 언어로 페이스북에서 만들어졌다. SQL은 데이터베이스 시스템에 저장된 데이터를 효율적으로 가져오는 것이 목적이라면 Graphql은 웹 클라이언트가 데이터를 서버로 부터 효율적으로 가져오는 것을 목적으로 한다. SQL은 백앤드에서 작성하고 호출하는 반면에 GraphQL은 클라이언트에서 작성하고 호출한다.

GraphQL Codegen이란?

GraphQL Codegen은 GraphQL Code Generator를 의미한다.

Graphql Codegen은 GraphQL 스키마와 쿼리 정의를 기반으로 다양한 언어 및 프레임웨크에 맞는 코드를 자동으로 생성해주는 도구이다. 이를 통해 개발자는 타입 안정성을 높이고 반복적인 작업을 줄여 개발 속도를 향상시킬 수 있다.

GraphQL Codegen 장점

타입 안전성 보장

GraphQL과 타입스크립트를 함께 사용할 때, 특히 React와 Apollo Client와 같은 기술 스택인 경우에 타입 안정성을 유지하면서 효율적으로 개발하는 것은 상당히 어려울 수 있다.

GraphQL은 API에 대한 명세를 지정할 뿐 타입스크립트와는 전혀 상관이 없다. 따라서 타입스크립트를 사용한다면 API 응답 타입을 매번 수동으로 작성해서 연결고리를 만들어줘야 한다.

Graphql Codegen은 Graphql 스키마를 기반으로 타입을 자동으로 생성해주기 때문에 개발자가 응답 타입을 수동으로 작성할 필요가 없다. 따라서 API 스키마와 클라이언트 코드 간의 타입 불일치를 방지할 수 있다.

개발 생산성 향상

Graphql Codegen을 사용하면 Graphql 스키마나 쿼리가 변경될 때 자동으로 타입 정의를 업데이트하기 때문에 타입을 정의하는데 신경쓰지 않고 기능 구현에 집중할 수 있어 개발 효율성이 크게 증가한다.

GrahpQL Codegen 적용 방법

1. codegen 의존성 설치하기

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

• @graphql-codegen/cli: GrahpQL Codegen의 CLI를 제공하며 설정 파일을 읽는 역할을 수행한다.
• @graphql-codegen/typescript: Graphql 스키마를 기반으로 타입스크립트 타입을 생성한다.
• @graphql-codegen/typescript-operations: Graphql 쿼리를 기반으로 타입스크립트 타입을 생성한다.
• @graphql-codegen/typescript-react-apollo: Apollo Client를 사용할 때 React Hooks와 관련된 타입스크립트 타입을 생성한다.

2. codegen 설정 파일 작성

// codegen.yaml
overwrite: true
schema: http://your-graphql-server.com/graphql 
documents: ./src/**/*.graphql 				   
generates:
  ./src/generated/graphql.tsx:
    plugins:
      - 'typescript'
      - 'typescript-operations'
      - 'typescript-react-apollo'

• overwrite
  • 생성된 파일이 존재하는 경우 덮어쓸지 여부
• schema
  • GraphQL 서버 엔드포인트 주소
• documents
  • GraphQL 쿼리 파일 경로
• generates
  • 생성된 타입스크립트 타입 파일이 저장될 경로
  • GraphQL 스키마와 쿼리를 기반으로 타입스크립트 타입 파일을 경로에 생성
• plugins
  • 생성할 타입스크립트 타입 파일에 적용할 플러그인
  • 타입스크립트 타입 및 Apollo Client Hooks 생성

3. codegen 실행

아래의 명령어를 실행한다.

npx graphql-codegen

1. 설정 파일 읽기

codegen.yaml 설정 파일을 읽는다.

overwrite: true
schema: http://your-graphql-server.com/graphql 
documents: ./src/**/*.graphql 				   
generates:
  ./src/generated/graphql.tsx:
    plugins:
      - 'typescript'
      - 'typescript-operations'
      - 'typescript-react-apollo'

2. Graphql 스키마 가져오기

Graphql 서버로부터 스키마를 가져온다.

# graphql schema
type User {
  id: ID!
  name: String!
  email: String!
}

type Query {
  user(id: ID!): User
}

3. 타입스크립트 타입 생성

Graphql 스키마와 클라이언트에서 작성한GraphQL 쿼리로 타입스크립트 타입을 생성한다.

# graphql query
query GetUser($userId: ID!) {
  user(id: $userId) {
    id
    name
    email
  }
}

# typescript(스키마와 쿼리 기반으로 생성)
# GetUserQuery, GetUserQueryVariables
# 위 2가지 타입은 Apollo Client Plugin으로 인해 생성된 타입이다.
export type User = {
  id: string;
  name: string;
  email: string;
};

export type GetUserQueryVariables = {
  userId: string;
};

export type GetUserQuery = {
  user: User | null;
};

export const GetUserDocument = gql`
  query GetUser($userId: ID!) {
    user(id: $userId) {
      id
      name
      email
    }
  }
`;

4. 코드 적용

직접 수동으로 타입을 작성하지 않고 Graphql Codegen이 스키마와 쿼리를 기반으로 자동으로 생성해준 타입스크립트 타입을 활용해 아래와 같이 코드를 작성할 수 있다. 보다 간결하고 직관적이며 개발자가 기능 구현에 집중할 수 있도록 도와주는 아주 고마운 도구이다.

import React from 'react';
import { useQuery } from '@apollo/client';
import { GetUserQuery, GetUserQueryVariables, GetUserDocument } from './generated/graphql';

interface UserProps {
  userId: string;
}

const User = ({ userId }):UserProps => {

const { loading, error, data } = useQuery<GetUserQuery, GetUserQueryVariables>(
  GetUserDocument,
  {
    variables: { userId },
  }
);

  if (loading) return <p>Loading...</p>;
  if (error) return <p>Error: {error.message}</p>;

  const user = data?.user;
  
  return (
    <ul>
      <li>User Information</h2>
      <li>ID: {user?.id}</p>
      <li>Name: {user?.name}</p>
      <li>Email: {user?.email}</p>
    </ul>
  );
};

export default User;

정리

기획측 요구사항이 변경되면 서버측 API도 추가 또는 수정이 필요한 경우가 많아진다. 그때마다 클라이언트에서 API 응답 타입을 항상 수동으로 작성 또는 수정해야 하는 번거로움이 발생했다.

API 응답 타입을 자동으로 생성해주는 도구가 없는지 찾아본 결과 Graphql Codegen을 발견했고 클라이언트에서 사용하고 있는 Apollo Client와도 잘 호환되며 관련 Hook도 생성해주어 개발 생산성을 많이 높여주었다.

과거에는 클라이언트에서 API 응답 타입을 수동으로 정의해야 하는 번거로움이 있었다. 특히 복잡한 응답을 다룰 때는 타입을 작성하는 것이 더 까다롭고 휴먼 에러가 발생할 확률도 상당히 높았다.

GraphQL Codegen을 도입해 GraphQL 환경에서 스키마와 쿼리 기반으로 타입을 자동으로 생성하여 과거의 문제를 해결했으며 이에 따라 코드의 안정성을 높여주고 개발자가 기능 구현에 집중할 수 있었다.