챕터 9: Nest.js로 GraphQL API 구축하기

Nest.js는 REST 뿐 아니라 GraphQL API 개발도 탁월하게 지원합니다. GraphQL은 정보의 과요청과 부족 현상을 줄이고, 클라이언트가 정확히 필요한 데이터를 요청할 수 있도록 돕는 혁신적인 API 기술입니다. Nest.js는 @nestjs/graphql 패키지와 Apollo Server를 통해, 효율적이고 확장성 높은 GraphQL 백엔드를 빠르게 구현할 수 있도록 설계되어 있습니다.

GraphQL 지원을 위한 환경 준비

먼저 프로젝트에 필수 패키지를 추가합니다. 터미널에서 다음 명령어를 실행하세요.

npm install @nestjs/graphql @nestjs/apollo graphql apollo-server-express

설치가 끝나면, 애플리케이션 모듈에 GraphQL 모듈을 설정합니다. 대부분의 경우 코드 퍼스트 방식(code-first approach)을 채택하며, 타입스크립트의 데코레이터를 적극적으로 활용해 스키마를 정의합니다.

코드 퍼스트 GraphQL 설정

import { Module } from '@nestjs/common';
import { GraphQLModule } from '@nestjs/graphql';
import { ApolloDriver, ApolloDriverConfig } from '@nestjs/apollo';

@Module({
  imports: [
    GraphQLModule.forRoot<ApolloDriverConfig>({
      driver: ApolloDriver,
      autoSchemaFile: true,
      playground: true,
    }),
  ],
})
export class AppModule {}

autoSchemaFile: true 설정을 통해 프로젝트 루트에 자동으로 GraphQL 스키마 파일이 생성됩니다. 이렇게 하면 스키마와 타입 정의가 코드와 완전히 일치하는 구조가 자연스럽게 만들어집니다.

리졸버와 타입 정의

GraphQL 요청을 처리하는 핵심은 리졸버(resolver)입니다. 각 쿼리와 뮤테이션 요청에 맞는 메서드를 데코레이터로 지정하고, DTO와 객체 타입을 이용해 명확한 데이터 구조를 설계합니다.

간단한 예로, 사용자 정보를 반환하는 쿼리를 작성해봅시다.

import { Resolver, Query, Args, Mutation } from '@nestjs/graphql';
import { User } from './user.model';
import { UserService } from './user.service';

@Resolver(() => User)
export class UserResolver {
  constructor(private userService: UserService) {}

  @Query(() => [User])
  getUsers() {
    return this.userService.findAll();
  }

  @Mutation(() => User)
  createUser(@Args('name') name: string) {
    return this.userService.create(name);
  }
}

여기서 @Query와 @Mutation 데코레이터는 각각 GraphQL 쿼리와 데이터 변경 작업을 맡습니다. @Args를 사용해 클라이언트가 전송한 인자를 손쉽게 받아 처리할 수 있습니다.

데이터베이스와의 연동

Nest.js에서 GraphQL과 ORM을 함께 활용하면, 데이터 조회/생성/수정/삭제 흐름이 심플해집니다. 예를 들어 TypeORM이나 Mongoose와 연동하여 실전 서비스에서도 바로 사용할 수 있습니다. 서비스 계층이 비즈니스 로직을 담당하고, 리졸버는 오직 데이터 입출력에만 집중하도록 구조를 유지하는 것이 좋습니다.

실무에서의 확장 전략

챗봇, 마이크로서비스, 대규모 어드민 서비스에 이르기까지, Nest.js 기반 GraphQL API는 타입 안정성, 코드 일관성, 그리고 뛰어난 확장성이 핵심 강점입니다. 인증/인가, 에러 핸들링, 성능 최적화 등 고급 논의도 쉽게 적용할 수 있습니다. Nest.js와 GraphQL이 만나면 현대적 백엔드 개발의 기준을 다시 쓰게 됩니다.

이처럼 Nest.js에서 GraphQL API를 구현하면, 속도와 안전성, 그리고 유연함을 모두 갖춘 현대적 서버의 토대를 쉽게 마련할 수 있습니다. 다음 장에서는 실제 사례와 고급 패턴을 바탕으로 실전 응용법을 이어서 살펴봅니다.