타입 안전한 API 사용을 위한 GraphQL Codegen의 모든 것
API 통신을 할 때 데이터의 형식과 타입이 올바른지 확인하는 것은 매우 중요해요. 그렇지 않으면 런타임 에러가 발생할 수 있고, 이는 개발 과정을 방해할 수 있습니다. 여기서 GraphQL Codegen이 큰 역할을 하죠. GraphQL Codegen을 통해 타입 안전한 API를 구축할 수 있다면, 그만큼 개발의 질이 향상될 것입니다. 이 글에서는 GraphQL Codegen을 사용해 타입 안전한 API를 만드는 방법을 자세히 알아보겠습니다.
GraphQL Codegen이란?
GraphQL Codegen은 GraphQL 스키마와 쿼리를 기반으로 타입 정의를 자동으로 생성해주는 도구에요. 이 도구를 통해 TypeScript, Java, Go, Rust 등 다양한 언어에서 사용할 수 있는 정의를 쉽게 만들 수 있습니다. 특히, TypeScript와 같은 언어와 결합했을 때 타입 안전성을 극대화할 수 있어요.
GraphQL Codegen의 주요 장점
- 자동화된 타입 생성: 수동으로 타입을 정의할 필요가 없어요. 쿼리나 스키마에 따라 자동으로 생성이 됩니다.
- 타입 안전성: 코드 작성 시 컴파일 타임에 오류를 잡을 수 있어요. 이를 통해 런타임 에러를 줄여줍니다.
- 유지보수 용이성: 스키마에 변화가 생겨도 코드가 자동으로 업데이트되므로 유지보수가 한결 쉬워요.
GraphQL Codegen 설정하기
GraphQL Codegen을 설정하는 과정은 매우 간단합니다. 다음과 같은 단계를 따르면 됩니다.
1. GraphQL Codegen 패키지 설치하기
터미널에서 다음 명령어를 입력하여 패키지를 설치합니다.
bash
npm install -D @graphql-codegen/cli @graphql-codegen/typescript
2. 설정 파일 만들기
프로젝트 루트에 codegen.yml 파일을 생성합니다. 이 파일에 GraphQL Codegen의 설정을 추가하세요.
yaml
schema: 'https://your-graphql-endpoint.com/graphql'
documents: 'src/**/*.graphql'
generates:
src/generated/graphql.ts:
plugins:
- 'typescript'
3. 코드 생성 실행하기
이제 명령어로 코드를 생성할 수 있어요.
bash
npx graphql-codegen
이 명령어를 실행하면, 설정한 경로에 TypeScript 타입 정의가 생성됩니다.
타입 안전성을 높이는 방법
타입 안전성을 더욱 높이기 위해서는 몇 가지 팁을 고려해볼 수 있어요.
타입스크립트 사용하기
TypeScript를 사용하면, 정적 타입 체크를 통해 코드의 신뢰성을 높일 수 있습니다. 예를 들어, User 타입을 정의하고 이를 사용하여 작업하죠.
const getUser = (user: User) => { console.log(user.name); };
GraphQL 스키마 설계 시 주의할 점
스키마를 설계할 때는 다음과 같은 사항들을 고려해야 합니다.
- 명확한 타입 정의: 각 필드에 대한 타입을 명확히 정의하세요. 예를 들어,
String!타입은null을 허용하지 않아요. - 불필요한 필드 제거: 스키마의 복잡성을 줄이기 위해 꼭 필요한 필드만 남기는 것이 좋아요.
| 특징 | 장점 | 단점 |
|---|---|---|
| 자동 타입 생성 | 코드량 감소 | 초기 설정 필요 |
| 타입 안전성 보장 | 런타임 에러 감소 | 복잡한 쿼리 처리 |
코드 예제
실제 GraphQL 쿼리를 사용하는 간단한 예제를 들어볼게요. 다음은 사용자 정보를 가져오는 쿼리입니다.
graphql
query GetUser($id: ID!) {
user(id: $id) {
id
name
email
}
}
이 쿼리를 TypeScript 코드에서 사용하면, 다음과 같은 방식으로 타입을 사용할 수 있어요.
const fetchUser = async (id: string): Promise => { const result = await fetch('https://your-graphql-endpoint.com/graphql', { method: 'POST', headers: { 'Content-Type': 'application/json', }, body: JSON.stringify({ query:
query GetUser($id: ID!) {
user(id: $id) {
id
name
email
}
}
, variables: { id }, }), });
const data: GetUserQuery = await result.json(); return data; };
위 코드를 통해 GraphQL 쿼리를 작성할 때, 타입 안전성을 보장 받을 수 있습니다.
결론
GraphQL Codegen을 활용하면, 자동으로 타입을 생성할 수 있어 타입 안전한 API를 구축할 수 있습니다. 이번 포스트를 통해 개발 과정에서 에러를 줄이고, 보다 신뢰할 수 있는 코드를 작성할 수 있기를 바랍니다. 지금 바로 GraphQL Codegen을 사용하여 프로젝트에 적용해 보세요!
자주 묻는 질문 Q&A
Q1: GraphQL Codegen이란 무엇인가요?
A1: GraphQL Codegen은 GraphQL 스키마와 쿼리를 기반으로 타입 정의를 자동으로 생성해주는 도구입니다.
Q2: GraphQL Codegen을 사용하면 어떤 장점이 있나요?
A2: 자동화된 타입 생성, 타입 안전성 보장, 유지보수 용이성 등 여러 장점이 있습니다.
Q3: 타입 안전성을 높이기 위한 방법은 무엇인가요?
A3: TypeScript 사용, 명확한 타입 정의, 불필요한 필드 제거 등을 통해 타입 안전성을 높일 수 있습니다.