GraphQL API 서버 구축: Apollo Server와 TypeORM 연동 실습 가이드

Apollo Server와 TypeORM을 활용하여 GraphQL API 서버를 효율적으로 구축하는 실습 가이드입니다. 데이터베이스 연동부터 스키마 정의, 쿼리 및 뮤테이션 구현까지 전 과정을 다룹니다.

현대 웹 애플리케이션 개발에서 API는 핵심적인 요소로 자리 잡고 있습니다. 특히 프런트엔드와 백엔드 간의 효율적인 데이터 통신은 사용자 경험과 개발 생산성에 직접적인 영향을 미칩니다. 전통적인 REST API는 강력한 웹 표준을 기반으로 하지만, 데이터 과다 요청(over-fetching) 또는 부족 요청(under-fetching) 문제, 여러 엔드포인트 관리의 복잡성 등으로 인해 대규모 애플리케이션에서는 비효율성이 발생할 수 있습니다.

이러한 배경 속에서 GraphQL은 클라이언트가 필요한 데이터를 정확히 요청할 수 있도록 하여 이러한 문제들을 해결하는 강력한 대안으로 부상하였습니다. GraphQL 서버를 구축하는 데 있어 Apollo Server는 업계 표준으로 널리 사용되며, Node.js 환경에서 관계형 데이터베이스와의 연동을 위해 TypeORM은 객체 지향적인 방식으로 데이터 처리를 지원하는 효과적인 ORM(Object-Relational Mapping) 솔루션입니다. 본 가이드에서는 Apollo Server와 TypeORM을 연동하여 견고하고 확장 가능한 GraphQL API 서버를 구축하는 실습 과정을 상세하게 다룹니다.

📑 목차

• GraphQL과 REST API: 현대 API 아키텍처의 선택
• Apollo Server: GraphQL 서버 구축의 표준 프레임워크
• TypeORM: Node.js 환경의 강력한 ORM 솔루션
• Apollo Server와 TypeORM 연동 환경 설정
• 1. 프로젝트 초기화 및 필수 패키지 설치
• 2. TypeScript 설정 파일 (tsconfig.json)
• 3. 데이터베이스 설정 파일 (ormconfig.json)
• 4. 프로젝트 구조
• GraphQL 스키마 및 TypeORM 엔티티 정의
• 1. TypeORM 엔티티 정의 (src/entity/User.ts)
• 2. GraphQL Input Type 정의 (src/resolver/UserResolver.ts 내 또는 별도 파일)
• 리졸버 구현 및 데이터베이스 연동
• 1. TypeORM 데이터베이스 연결 설정 및 초기화
• 2. GraphQL 리졸버 작성 (src/resolver/UserResolver.ts)
• Apollo Server 실행 및 API 테스트
• 1. Apollo Server 설정 및 시작 (src/index.ts)
• 2. 서버 실행
• 3. API 테스트 (Apollo Sandbox)
• 결론

Image by Hans on Pixabay

GraphQL과 REST API: 현대 API 아키텍처의 선택

API 아키텍처를 선택하는 것은 애플리케이션의 성능, 확장성, 개발 용이성에 지대한 영향을 미칩니다. REST API는 자원(Resource) 기반의 접근 방식을 사용하여 직관적이며 캐싱, 무상태성 등 웹의 기본 원칙을 따릅니다. 그러나 클라이언트가 필요한 데이터가 여러 자원에 분산되어 있거나, 필요 없는 데이터를 함께 받아야 하는 경우가 빈번하게 발생합니다. 이는 네트워크 부하 증가와 클라이언트 측의 불필요한 데이터 처리 로직을 야기할 수 있습니다.

반면, GraphQL은 단일 엔드포인트에서 클라이언트가 원하는 데이터 구조를 직접 정의하여 요청할 수 있도록 합니다. 이를 통해 데이터 과다/부족 요청 문제를 효과적으로 해결하고, API 호출 횟수를 줄여 네트워크 효율성을 극대화할 수 있습니다. 또한, 강력한 타입 시스템을 기반으로 하여 API의 일관성과 안정성을 보장합니다. 다음 표는 GraphQL과 REST API의 주요 특징을 비교합니다.

특징	GraphQL	REST API
데이터 요청 방식	클라이언트가 필요한 필드를 직접 지정하여 요청 (단일 엔드포인트)	서버가 정의한 고정된 자원(Resource) 구조를 요청 (다중 엔드포인트)
데이터 과다/부족 요청	클라이언트가 원하는 데이터만 받아 해결 (Over-fetching/Under-fetching 방지)	발생 가능성 높음
네트워크 효율성	높음 (단일 요청으로 복잡한 데이터 취득)	중간 (여러 요청 필요 시 효율 저하)
스키마 및 타입	강력한 타입 시스템과 스키마 정의 언어(SDL)	스키마 없음 (문서화에 의존)
버전 관리	스키마 진화로 유연하게 처리	URL 버저닝 (예: /v1, /v2)

GraphQL은 특히 복잡한 데이터 관계를 가진 애플리케이션이나 다양한 클라이언트(웹, 모바일)에서 유연하게 데이터를 처리해야 하는 경우에 큰 이점을 제공합니다. 이러한 장점들을 바탕으로 GraphQL은 현대 API 개발의 핵심 기술로 자리매김하고 있습니다.

Apollo Server: GraphQL 서버 구축의 표준 프레임워크

Apollo Server는 Node.js 환경에서 GraphQL API를 쉽게 구축하고 관리할 수 있도록 지원하는 오픈소스 GraphQL 서버 라이브러리입니다. GraphQL 스키마를 정의하고, 해당 스키마에 따라 데이터를 가져오는 리졸버(resolver) 함수를 구현하는 과정을 간소화하여 개발 생산성을 크게 향상시킵니다.

Apollo Server의 주요 특징은 다음과 같습니다:

• 스키마 기반 개발: GraphQL Schema Definition Language (SDL)를 사용하여 API의 데이터 구조와 사용 가능한 연산을 명확하게 정의할 수 있습니다. 이는 프런트엔드와 백엔드 간의 계약 역할을 하여 개발의 일관성을 유지합니다.
• 강력한 리졸버 시스템: 스키마에 정의된 각 필드에 대한 데이터를 실제로 가져오는 로직을 리졸버 함수로 구현합니다. 데이터베이스, REST API, 외부 서비스 등 다양한 데이터 소스와 연동할 수 있는 유연성을 제공합니다.
• 개발자 도구: Apollo Sandbox(이전 Apollo Playground)와 같은 내장된 웹 UI를 제공하여 스키마 탐색, 쿼리 테스트, 에러 디버깅을 손쉽게 수행할 수 있습니다. 이는 개발 및 테스트 과정의 효율성을 크게 높입니다.
• 확장성 및 플러그인: 캐싱, 인증, 로깅, 에러 핸들링 등 다양한 기능을 플러그인 형태로 확장할 수 있습니다. 이를 통해 애플리케이션의 특정 요구사항에 맞춰 서버를 최적화하고 관리할 수 있습니다.
• 타입스크립트 지원: 타입스크립트와 함께 사용될 때 강력한 타입 추론과 개발 시점의 오류 방지 기능을 제공하여 대규모 프로젝트의 안정성을 향상시킵니다.

Apollo Server는 단순한 GraphQL 서버 구현을 넘어, 엔터프라이즈급 애플리케이션에서 요구되는 다양한 기능과 안정성을 제공합니다. 따라서 GraphQL 서버 개발을 위한 사실상의 표준 프레임워크로 평가받고 있습니다.

TypeORM: Node.js 환경의 강력한 ORM 솔루션

TypeORM은 Node.js 및 TypeScript 환경을 위한 객체-관계 매핑(ORM) 라이브러리입니다. 데이터베이스의 테이블을 클래스(엔티티)로 매핑하여 SQL 쿼리 없이 객체 지향적인 방식으로 데이터베이스를 조작할 수 있도록 지원합니다. 이는 개발자가 데이터베이스 스키마와 직접 상호작용하는 대신, 익숙한 프로그래밍 언어의 객체를 다루는 것처럼 데이터를 처리할 수 있게 하여 개발 생산성을 크게 높입니다.

TypeORM의 핵심 기능은 다음과 같습니다:

• 엔티티 기반 개발: 데이터베이스의 각 테이블을 TypeScript 클래스로 정의하고, `@Entity`, `@Column`, `@PrimaryGeneratedColumn` 등의 데코레이터를 사용하여 테이블과 컬럼의 속성을 매핑합니다. 이는 코드의 가독성을 높이고 유지보수를 용이하게 합니다.
• 다양한 데이터베이스 지원: PostgreSQL, MySQL, MariaDB, SQLite, Microsoft SQL Server, Oracle 등 주요 관계형 데이터베이스를 광범위하게 지원합니다. 이를 통해 프로젝트 요구사항에 맞는 데이터베이스를 유연하게 선택할 수 있습니다.
• 관계형 데이터 매핑: 일대일(One-to-One), 일대다(One-to-Many), 다대다(Many-to-Many) 등 복잡한 테이블 관계를 데코레이터를 사용하여 쉽게 정의하고 관리할 수 있습니다. 관계형 데이터를 객체 그래프 형태로 쉽게 탐색하고 조작할 수 있습니다.
• 리포지토리 패턴: 데이터베이스 작업(조회, 저장, 업데이트, 삭제)을 위한 리포지토리(Repository)를 제공하여 비즈니스 로직과 데이터 접근 로직을 분리하고 코드를 체계적으로 구성할 수 있습니다.
• 마이그레이션 도구: 데이터베이스 스키마 변경 이력을 관리하고 적용할 수 있는 마이그레이션 기능을 제공하여 팀 개발 환경에서 스키마 변경을 안전하게 관리할 수 있습니다.
• 타입스크립트 우선 설계: TypeORM은 타입스크립트를 염두에 두고 설계되었기 때문에, 강력한 타입 추론과 자동 완성 기능을 제공하여 개발 시점의 오류를 줄이고 개발 경험을 향상시킵니다.

GraphQL API 서버는 데이터베이스로부터 데이터를 조회하고 저장하는 작업이 빈번하게 발생합니다. TypeORM은 이러한 데이터베이스 연동 과정을 객체 지향적으로 추상화하여, 리졸버에서 비즈니스 로직에 집중할 수 있도록 돕습니다. 특히 타입스크립트 환경에서 Apollo Server와 TypeORM을 함께 사용하면, 엔드-투-엔드 타입 안전성을 확보하여 견고하고 유지보수하기 쉬운 API 서버를 구축할 수 있습니다.

Apollo Server와 TypeORM 연동 환경 설정

본격적인 API 서버 구축에 앞서 필요한 개발 환경을 설정하고 프로젝트를 초기화합니다. Node.js와 npm(또는 yarn)이 설치되어 있어야 합니다.

1. 프로젝트 초기화 및 필수 패키지 설치

새로운 디렉토리를 생성하고 프로젝트를 초기화합니다. TypeScript를 사용할 것이므로, TypeScript 관련 패키지와 TypeORM, Apollo Server, GraphQL 관련 패키지를 설치합니다. 데이터베이스는 PostgreSQL을 예시로 사용합니다.

mkdir graphql-typeorm-server
cd graphql-typeorm-server
npm init -y

npm install apollo-server graphql type-graphql typeorm reflect-metadata pg
npm install -D typescript ts-node @types/node

• apollo-server: GraphQL 서버의 핵심 라이브러리입니다.
• graphql: GraphQL 스키마 정의 및 쿼리 파싱을 위한 기본 라이브러리입니다.
• type-graphql: TypeScript 클래스와 데코레이터를 사용하여 GraphQL 스키마를 정의할 수 있게 해주는 라이브러리입니다. TypeORM 엔티티와 함께 사용하기에 매우 효과적입니다.
• typeorm: ORM 라이브러리입니다.
• reflect-metadata: 타입스크립트 데코레이터 메타데이터를 사용하기 위해 필요합니다. TypeORM과 TypeGraphQL 모두 이 기능을 활용합니다.
• pg: PostgreSQL 데이터베이스 드라이버입니다. 사용하는 데이터베이스에 따라 `mysql`, `sqlite3` 등으로 변경될 수 있습니다.
• typescript, ts-node, @types/node: TypeScript 개발 환경을 위한 패키지입니다.

2. TypeScript 설정 파일 (tsconfig.json)

TypeScript 컴파일러 설정을 정의합니다. reflect-metadata 데코레이터를 사용하기 위해 "emitDecoratorMetadata": true와 "experimentalDecorators": true를 반드시 활성화해야 합니다.

npx tsc --init

생성된 tsconfig.json 파일을 다음과 같이 수정합니다:

{
  "compilerOptions": {
    "target": "es2016",
    "module": "commonjs",
    "lib": ["es2017"],
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "emitDecoratorMetadata": true,
    "experimentalDecorators": true,
    "outDir": "./dist",
    "rootDir": "./src"
  },
  "include": ["src/**/*.ts"],
  "exclude": ["node_modules"]
}

3. 데이터베이스 설정 파일 (ormconfig.json)

TypeORM이 데이터베이스에 연결하기 위한 설정을 정의합니다. 프로젝트 루트에 ormconfig.json 파일을 생성합니다. 실제 환경에서는 환경 변수를 사용하는 것이 권장됩니다.

// ormconfig.json
[
  {
    "type": "postgres",
    "host": "localhost",
    "port": 5432,
    "username": "your_username",
    "password": "your_password",
    "database": "your_database_name",
    "synchronize": true,
    "logging": false,
    "entities": ["src/entity/**/*.ts"],
    "migrations": ["src/migration/**/*.ts"],
    "subscribers": ["src/subscriber/**/*.ts"]
  }
]

• type: 데이터베이스 종류를 지정합니다 (예: postgres, mysql).
• host, port, username, password, database: 데이터베이스 접속 정보입니다.
• synchronize: 개발 모드에서는 true로 설정하여 엔티티를 기반으로 데이터베이스 스키마를 자동으로 생성/업데이트할 수 있지만, 프로덕션 환경에서는 반드시 false로 설정하고 마이그레이션을 사용해야 합니다.
• logging: 쿼리 로그를 출력할지 여부입니다. 개발 시 유용합니다.
• entities: TypeORM 엔티티 파일의 경로를 지정합니다.

4. 프로젝트 구조

다음과 같은 기본적인 프로젝트 구조를 구성합니다.

graphql-typeorm-server/
├── src/
│   ├── entity/           # TypeORM 엔티티 정의
│   │   └── User.ts
│   ├── resolver/         # GraphQL 리졸버 정의
│   │   └── UserResolver.ts
│   ├── schema/           # GraphQL 스키마 정의 (TypeGraphQL 사용 시)
│   ├── index.ts          # 서버 시작 파일
│   └── util/             # 유틸리티 함수 등
├── ormconfig.json
├── package.json
├── tsconfig.json
└── README.md

Image by Pezibear on Pixabay

GraphQL 스키마 및 TypeORM 엔티티 정의

이제 데이터베이스 테이블에 해당하는 TypeORM 엔티티를 정의하고, 이 엔티티를 기반으로 GraphQL 스키마를 생성합니다. type-graphql을 사용하면 이 두 가지 작업을 타입스크립트 클래스 데코레이터 기반으로 통합하여 수행할 수 있습니다.

1. TypeORM 엔티티 정의 (src/entity/User.ts)

사용자 정보를 저장할 User 엔티티를 정의합니다. 각 필드는 데이터베이스 컬럼에 매핑됩니다.

// src/entity/User.ts
import { Entity, PrimaryGeneratedColumn, Column } from "typeorm";
import { ObjectType, Field, ID } from "type-graphql";

@Entity()
@ObjectType() // GraphQL Type으로도 사용될 것임을 명시
export class User {
  @Field(() => ID)
  @PrimaryGeneratedColumn()
  id!: number;

  @Field()
  @Column({ unique: true })
  email!: string;

  @Field()
  @Column()
  firstName!: string;

  @Field()
  @Column()
  lastName!: string;

  @Field()
  @Column({ default: true })
  isActive!: boolean;
}

• @Entity(): 이 클래스가 TypeORM 엔티티임을 나타냅니다.
• @ObjectType(): type-graphql에서 이 클래스가 GraphQL 타입으로 사용될 것임을 나타냅니다.
• @Field(): 해당 속성이 GraphQL 스키마의 필드로 노출될 것임을 나타냅니다. () => ID와 같이 타입을 명시할 수 있습니다.
• @PrimaryGeneratedColumn(): 기본 키(Primary Key)이며 자동으로 값이 생성됨을 나타냅니다.
• @Column(): 일반적인 데이터베이스 컬럼을 나타냅니다. unique: true, default: true 등 컬럼 옵션을 지정할 수 있습니다.

2. GraphQL Input Type 정의 (src/resolver/UserResolver.ts 내 또는 별도 파일)

데이터 생성 및 업데이트 시 클라이언트로부터 받을 입력 데이터를 위한 GraphQL Input Type을 정의합니다. 이는 엔티티와 별도로 정의되어야 합니다.

// src/resolver/UserResolver.ts (User 엔티티와 함께 정의)
import { InputType, Field } from "type-graphql";

@InputType()
export class CreateUserInput {
  @Field()
  email!: string;

  @Field()
  firstName!: string;

  @Field()
  lastName!: string;
}

@InputType()
export class UpdateUserInput {
  @Field(() => String, { nullable: true })
  firstName?: string;

  @Field(() => String, { nullable: true })
  lastName?: string;

  @Field(() => Boolean, { nullable: true })
  isActive?: boolean;
}

• @InputType(): 이 클래스가 GraphQL Input Type으로 사용될 것임을 나타냅니다.
• @Field(() => String, { nullable: true }): 해당 필드가 선택적이며 null 값을 허용함을 나타냅니다.

리졸버 구현 및 데이터베이스 연동

이제 TypeORM을 사용하여 데이터베이스에 연결하고, GraphQL 쿼리 및 뮤테이션 요청을 처리할 리졸버를 구현합니다.

1. TypeORM 데이터베이스 연결 설정 및 초기화

TypeORM은 AppDataSource를 통해 데이터베이스 연결을 관리합니다. src/index.ts 파일에 데이터베이스 초기화 로직을 추가합니다.

// src/index.ts (데이터베이스 초기화 부분)
import "reflect-metadata"; // 반드시 최상단에 import 해야 합니다.
import { DataSource } from "typeorm";
import { User } from "./entity/User";

export const AppDataSource = new DataSource({
  type: "postgres",
  host: "localhost",
  port: 5432,
  username: "your_username",
  password: "your_password",
  database: "your_database_name",
  synchronize: true, // 개발용: 엔티티 기반으로 스키마 자동 생성 (운영 환경에서는 false)
  logging: false,
  entities: [User], // 정의한 엔티티를 포함
  migrations: [],
  subscribers: [],
});

// 데이터베이스 연결
AppDataSource.initialize()
  .then(() => {
    console.log("Data Source has been initialized!");
  })
  .catch((err) => {
    console.error("Error during Data Source initialization:", err);
  });

2. GraphQL 리졸버 작성 (src/resolver/UserResolver.ts)

type-graphql의 @Resolver, @Query, @Mutation 데코레이터를 사용하여 리졸버를 작성합니다. 리졸버 내부에서는 AppDataSource를 통해 TypeORM 리포지토리에 접근하여 데이터베이스 작업을 수행합니다.

// src/resolver/UserResolver.ts
import { Resolver, Query, Mutation, Arg } from "type-graphql";
import { User } from "../entity/User";
import { AppDataSource } from "../index"; // 데이터베이스 연결 임포트
import { CreateUserInput, UpdateUserInput } from "./UserResolver.inputs"; // Input Type

@Resolver(User)
export class UserResolver {
  // 모든 사용자 조회
  @Query(() => [User])
  async users(): Promise<User[]> {
    const userRepository = AppDataSource.getRepository(User);
    return userRepository.find();
  }

  // 특정 사용자 ID로 조회
  @Query(() => User, { nullable: true })
  async user(@Arg("id") id: number): Promise {
    const userRepository = AppDataSource.getRepository(User);
    return userRepository.findOneBy({ id });
  }

  // 사용자 생성
  @Mutation(() => User)
  async createUser(@Arg("input") input: CreateUserInput): Promise {
    const userRepository = AppDataSource.getRepository(User);
    const newUser = userRepository.create(input); // 새로운 User 엔티티 생성
    await userRepository.save(newUser); // 데이터베이스에 저장
    return newUser;
  }

  // 사용자 정보 업데이트
  @Mutation(() => User, { nullable: true })
  async updateUser(
    @Arg("id") id: number,
    @Arg("input") input: UpdateUserInput
  ): Promise {
    const userRepository = AppDataSource.getRepository(User);
    const userToUpdate = await userRepository.findOneBy({ id });

    if (!userToUpdate) {
      return null;
    }

    // 입력된 필드만 업데이트
    Object.assign(userToUpdate, input);
    await userRepository.save(userToUpdate);
    return userToUpdate;
  }

  // 사용자 삭제
  @Mutation(() => Boolean)
  async deleteUser(@Arg("id") id: number): Promise {
    const userRepository = AppDataSource.getRepository(User);
    const result = await userRepository.delete(id);
    // affected 행이 1 이상이면 성공
    return result.affected !== undefined && result.affected > 0;
  }
}

• @Resolver(User): 이 클래스가 User 타입에 대한 리졸버임을 명시합니다.
• @Query(): GraphQL 쿼리를 정의합니다. () => [User]는 반환 타입이 User 객체 배열임을 의미합니다.
• @Mutation(): GraphQL 뮤테이션을 정의합니다.
• @Arg("id") id: number: 클라이언트로부터 id라는 인자를 받아 number 타입으로 사용함을 나타냅니다.
• AppDataSource.getRepository(User): User 엔티티에 대한 TypeORM 리포지토리를 가져옵니다. 이 리포지토리를 통해 find(), findOneBy(), create(), save(), delete() 등의 메서드를 사용하여 데이터베이스 작업을 수행합니다.

Image by WikiImages on Pixabay

Apollo Server 실행 및 API 테스트

이제 TypeORM으로 데이터베이스 연결과 엔티티 및 리졸버 정의를 마쳤으므로, Apollo Server를 설정하고 실행하여 GraphQL API를 사용할 준비를 합니다.

1. Apollo Server 설정 및 시작 (src/index.ts)

type-graphql의 buildSchema 함수를 사용하여 정의한 리졸버들로부터 GraphQL 스키마를 동적으로 생성하고, 이 스키마를 Apollo Server에 전달하여 서버를 시작합니다.

// src/index.ts (전체 코드)
import "reflect-metadata";
import { DataSource } from "typeorm";
import { ApolloServer } from "apollo-server";
import { buildSchema } from "type-graphql";
import { User } from "./entity/User";
import { UserResolver } from "./resolver/UserResolver";

export const AppDataSource = new DataSource({
  type: "postgres",
  host: "localhost",
  port: 5432,
  username: "your_username",
  password: "your_password",
  database: "your_database_name",
  synchronize: true, // 개발용: 엔티티 기반으로 스키마 자동 생성 (운영 환경에서는 false)
  logging: false,
  entities: [User],
  migrations: [],
  subscribers: [],
});

async function bootstrap() {
  // TypeORM 데이터베이스 연결
  await AppDataSource.initialize()
    .then(() => {
      console.log("Data Source has been initialized!");
    })
    .catch((err) => {
      console.error("Error during Data Source initialization:", err);
      process.exit(1); // 에러 발생 시 프로세스 종료
    });

  // TypeGraphQL 스키마 빌드
  const schema = await buildSchema({
    resolvers: [UserResolver], // 정의한 리졸버들을 배열로 전달
    validate: false, // 프로덕션 환경에서는 유효성 검사 활성화 고려
  });

  // Apollo Server 인스턴스 생성
  const server = new ApolloServer({
    schema,
    context: ({ req, res }) => ({ req, res, AppDataSource }), // 리졸버에서 데이터소스에 접근 가능하도록 context에 추가
  });

  // 서버 시작
  const { url } = await server.listen(4000);
  console.log(`🚀 Server ready at ${url}`);
}

bootstrap();

• buildSchema({ resolvers: [UserResolver] }): type-graphql이 UserResolver 클래스를 스캔하여 GraphQL 스키마(Type, Query, Mutation 등)를 자동으로 생성합니다.
• new ApolloServer({ schema }): 생성된 GraphQL 스키마를 Apollo Server에 전달합니다.
• context: ({ req, res }) => ({ req, res, AppDataSource }): 리졸버 함수에서 요청(req), 응답(res) 객체와 함께 AppDataSource에 접근할 수 있도록 컨텍스트 객체를 설정합니다. 이를 통해 리졸버에서 데이터베이스 리포지토리에 손쉽게 접근할 수 있습니다.
• server.listen(4000): Apollo Server를 4000번 포트에서 시작합니다.

2. 서버 실행

package.json에 스크립트를 추가하여 서버를 쉽게 실행할 수 있습니다.

// package.json
{
  // ...
  "scripts": {
    "start": "ts-node src/index.ts",
    "dev": "ts-node-dev --respawn src/index.ts" // 개발 시 파일 변경 자동 감지
  },
  // ...
}

이제 터미널에서 다음 명령어를 실행하여 서버를 시작합니다:

npm run start

서버가 성공적으로 시작되면 다음과 유사한 메시지를 확인할 수 있습니다:

Data Source has been initialized!
🚀 Server ready at http://localhost:4000/

3. API 테스트 (Apollo Sandbox)

웹 브라우저에서 http://localhost:4000/으로 접속하면 Apollo Sandbox(또는 Playground)가 자동으로 열립니다. 여기서 정의된 GraphQL 스키마를 탐색하고, 쿼리 및 뮤테이션을 직접 실행하여 API를 테스트할 수 있습니다.

사용자 생성 (Mutation)

mutation CreateUser {
  createUser(input: {
    email: "test1@example.com",
    firstName: "John",
    lastName: "Doe"
  }) {
    id
    email
    firstName
    lastName
    isActive
  }
}

모든 사용자 조회 (Query)

query GetAllUsers {
  users {
    id
    email
    firstName
    lastName
    isActive
  }
}

특정 사용자 조회 (Query)

query GetUserById {
  user(id: 1) { # 생성된 사용자의 ID를 입력
    id
    email
    firstName
    lastName
  }
}

사용자 업데이트 (Mutation)

mutation UpdateUser {
  updateUser(id: 1, input: {
    firstName: "Jane",
    isActive: false
  }) {
    id
    firstName
    isActive
  }
}

사용자 삭제 (Mutation)

mutation DeleteUser {
  deleteUser(id: 1)
}

이러한 테스트를 통해 TypeORM을 통한 데이터베이스 연동과 Apollo Server를 통한 GraphQL API의 정상적인 동작을 확인할 수 있습니다. 데이터베이스에 실제 데이터가 저장되고 조회되는지 확인해 보십시오.

결론

본 가이드에서는 Apollo Server와 TypeORM을 연동하여 GraphQL API 서버를 구축하는 전반적인 과정을 상세하게 다루었습니다. GraphQL의 유연한 데이터 요청 방식과 Apollo Server의 강력한 개발 도구, 그리고 TypeORM의 객체 지향적인 데이터베이스 접근 방식을 결합함으로써, 개발자는 효율적이고 견고하며 유지보수하기 쉬운 API 서버를 구축할 수 있습니다.

특히 TypeGraphQL을 활용하여 TypeORM 엔티티와 GraphQL 타입 및 리졸버를 TypeScript 데코레이터 기반으로 통합하는 접근 방식은 코드의 일관성을 높이고 개발 생산성을 극대화하는 데 기여합니다. 이러한 조합은 현대 웹 애플리케이션의 복잡한 데이터 요구사항을 충족시키면서도, 개발자들이 비즈니스 로직에 더 집중할 수 있도록 돕는 강력한 솔루션으로 판단됩니다.

이 실습 가이드를 통해 GraphQL API 서버 구축에 대한 이해를 높이고, 실제 프로젝트에 적용하는 데 필요한 기반 지식을 얻으셨기를 바랍니다. 추가적인 질문이나 의견이 있으시면 언제든지 댓글로 남겨주세요!

📌 함께 읽으면 좋은 글

• [튜토리얼] VS Code Dev Containers 활용: 일관된 개발 환경 구축 완벽 가이드
• [커리어 취업] 개발자 사이드 프로젝트 아이디어: 포트폴리오 강화와 실력 향상을 위한 실전 가이드
• [이슈 분석] 프로덕트 주도 성장 전략, 개발 조직 문화와 우선순위는 어떻게 변화해야 할까요?

이 글이 도움이 되셨다면 공감(♥)과 댓글로 응원해 주세요!
궁금한 점이나 다루었으면 하는 주제가 있다면 댓글로 남겨주세요.