[GraphQL] GraphQL code generator 란 / GraphQL과 타입스크립트

Graph QL 과 타입스크립트

 

GraphQL은 웹 클라이언트가 데이터를 질의하는데에 최적화된 일종의 인터페이스이자 쿼리 언어입니다.

쿼리 언어이므로 결국 데이터를 주고받는 것이 필수적이고, 그에 따라 내부적으로 input 과 output의 데이터의 타입을 정의하게 되죠.

 

하지만 쿼리 언어이기 때문에, 결국 어플리케이션 단에서 사용하는 언어에 따라, 추가적으로 데이터 타입이나 인터페이스 작업이 필요하다는 번거로움이 있습니다. 이러한 부분을 해결해주는 것이  Graph QL code generator 입니다.

 

GraphQL code generator?

 

 Graph QL code generator 은

*.graphql 의 파일에 존재하는 스키마와 쿼리를 바탕으로, 다양한 언어에 맞게 타입, 혹은 코드 자체를 생성해줍니다. 

 

cli 를 실행시킬 때 이용하는 플러그인을 통해 다양한 언어들로 호환시킬수 있는데요, Java, 닷넷, flow, reason Typescript 를 비롯한 React, Vue는 물론이고 apollo, react-query 와 같이 데이터 fetching 클라이언트에 맞는 코드까지 생성시킬 수 있습니다. 

 

말로만 들으면 바로 이해가 안될 수 있으니, graphql 의 파일이 아래처럼 작성이 되었다고 해봅시다.

 

schema.graphql

scalar Date

schema {
  query: Query
}

type Query {
  me: User!
  user(id: ID!): User
  allUsers: [User]
  search(term: String!): [SearchResult!]!
}

enum Role {
  USER, a
  ADMIN,
}

interface Node {
  id: ID!
}

union SearchResult = User 

type User implements Node {
  id: ID!
  username: String!
  email: String!
  role: Role!
}

 

결국 어플리케이션 (Typescript) 단에서는 위 타입들을 그대로 이용할 수 없고, 따로 타입으 선언해서 사용해야 하죠.

그런 불편함을 해결해줄 수 있는 것이 graphQL code generator 입니다.

 

type.ts (위 파일에 대한 graphQL code generate 결과)

export type Maybe<T> = T | null;
export type Exact<T extends { [key: string]: unknown }> = { [K in keyof T]: T[K] };
export type MakeOptional<T, K extends keyof T> = Omit<T, K> & { [SubKey in K]?: Maybe<T[SubKey]> };
export type MakeMaybe<T, K extends keyof T> = Omit<T, K> & { [SubKey in K]: Maybe<T[SubKey]> };
/** All built-in and custom scalars, mapped to their actual values */
export type Scalars = {
  ID: string;
  String: string;
  Boolean: boolean;
  Int: number;
  Float: number;
  Date: any;
};

export type Query = {
  __typename?: 'Query';
  me: User;
  user?: Maybe<User>;
  allUsers?: Maybe<Array<Maybe<User>>>;
  search: Array<SearchResult>;
};


export type QueryUserArgs = {
  id: Scalars['ID'];
};


export type QuerySearchArgs = {
  term: Scalars['String'];
};

export enum Role {
  User = 'USER',
  A = 'a',
  Admin = 'ADMIN'
}

export type Node = {
  id: Scalars['ID'];
};

export type SearchResult = User;

export type User = Node & {
  __typename?: 'User';
  id: Scalars['ID'];
  username: Scalars['String'];
  email: Scalars['String'];
  role: Role;
};

이렇게 깔끔하게 그래프QL 스키마에 따라 타입스크립트에서 사용할 수 있는 타입들이 생성됩니다.

 

위 예시는 그래프ql 코드 제네레이터 메인페이지에서 제공하는 예시입니다. 

아래 링크에 접속하면, 웹 상에서 타입을 직접 변환해볼 수도 있습니다.

 

https://www.graphql-code-generator.com/

GraphQL Code Generator | GraphQL Code Generator

 

위 공식문서를 보면 가독성도 좋고, 친절하게 서술이 되어있습니다.

아래 내용들도 위 문서를 바탕으로 간단하게 정리를 한 것일 뿐이므로, 

실제로 어플리케이션에 사용을 하려고 하시는 분께서는 공식문서를 읽는 것을 더 추천드립니다!

 

 

설치

graphql-codegen 은 일반적인 자바스크립트 모듈 형태로 cli 설치가 가능합니다.

 

npm 을 이용한 설치

$ npm i --save @graphql-codegen/cli

yarn 을 이용한 설치

$ yarn add -D @graphql-codegen/cli

저는 타입스크립트를 사용하는 입장이면 타입스크립트 플러그인 또한 설치해주어야 합니다.

$ yarn add -D @graphql-codegen/typescript

 

config 설정

 

graph-codegen 은 config 파일을 작성해, output의 형태나 위치 등을 조절이 가능합니다. 실행이 가능합니다.

config파일은 codegen.yaml 혹은 codegen.json 로 작성하며, 아래와 같이 실행합니다.

$ yarn graphql-codegen --config ./path/to/config.yml

마찬가지로 yarn 과 npx 모두 가능합니다.

$ npx graphql-codegen --config ./path/to/config.yml

 

 

혹은 graphql-codegen cli 를 실행할 때 config를 조절해줄 수도 있습니다.

• --config (-c) - config 파일 
• --watch (-w) - Overrides the watch config to true. You can also specify a glob expression to create a custom watch list.
• --silent (-s) - Overrides the silent config to true.
• --errors-only (-e) - Overrides the errorsOnly config to true.
• --require (-r) - Specifies require.extensions before loading the .yml file.
• --overwrite (-o) - Overrides the overwrite config to true.

 

 

신기했던 점으로는, naming convention 또한 조절이 가능하더군요

• https://www.graphql-code-generator.com/docs/getting-started/naming-convention

 

plugin 설정

 

 

가장 중요한 부분은 plugin 입니다. 

그래프ql code generator에는 다양한 플러그인이 존재하며, 플러그인을 통해 다양한 엔드포인트로 사용이 가능합니다.

 

 

예를들어, 타입스크립트와 그래프ql을 사용중이라면

• typescript
• typescript-operations
• typescript-resolvers 

와 같은 플러그인을 사용하면 되겠죠.

 

 

예시 (codegen.yml)

generates:
path/to/file.ts:
 plugins:
   - typescript
   - tpyescript-operations
   - typescript-resolvers

 

플러그인별로 하나하나 자세하게 설명을 해주고 있으니, 사용할 플러그인에 맞는 공식문서를 직접 참고하시는 것을 추천드립니다.

코드젠 플러그인

All Plugins | GraphQL Code Generator

 

 

마치며

 요즘은 정말, 새로운 기술이 끊임없이 나오는 만큼, 기술을 쉽게 이용하는 툴들도 정말 많이 나오는 것 같습니다..

한 가지 기술을 깊게 파는것도 중요하지만, 그걸 좀 더 쉽게 사용할 방법이나 도와주는 툴이 없는지를 잘 리서치해보는 것도 실력이겠구나 를 느꼈습니다. codegen 같은 툴을 모르고 일일이 그래프ql 데이터를 타이핑하는 걸 상상해보십쇼, 얼마나 시간 낭비였겠습니까 😇 ㅠ

 

사실 codegen 이라는 것이 대단한 기술도 아니고, 익히기가 어려운 것도 아닌데, 사용하고 안하고 생산성의 차이는 생각보다 굉장히 큰 것 같습니다. 그만큼 이런 기술이 있는지 여부를 알고 모르고 차이가 크다는 것이죠 ㅎㅎ

다양한 weekly 소식지들을 구독하고 새로운 소식들을 빠르게 접하는 습관을 들입시다! 

삽질하지 맙시다!!!  😭 ⛏️