GraphQL vs REST API : 2025년 기준으로 다시 생각해보기

Node.js로 백엔드 서버를 개발하려고 검색하다 보면 Express와 함께 자주 등장하는 이름이 있다. 바로 **NestJS**다.

Express가 필요한 기능을 자유롭게 조합하는 미니멀한 프레임워크라면, NestJS는 애플리케이션을 어떤 구조로 작성해야 하는지 비교적 명확한 기준을 제시한다. 프로젝트 규모가 커지고 참여하는 개발자가 많아질수록 이러한 구조는 코드의 일관성과 유지보수성을 높이는 데 도움이 된다.

NestJS는 객체지향 프로그래밍, 함수형 프로그래밍, 반응형 프로그래밍의 요소를 활용한다. 내부 HTTP 서버로는 기본적으로 Express를 사용하며, 필요에 따라 Fastify로 변경할 수도 있다.

# NestJS는 왜 등장했을까?

Node.js는 JavaScript로 빠르게 서버를 개발할 수 있다는 장점이 있다. Express를 이용하면 몇 줄의 코드만으로 웹 서버를 실행할 수 있다.

```javascript
const express = require('express');
const app = express();

app.get('/hello', (req, res) => {
  res.send('Hello World');
});

app.listen(3000);
```

하지만 Express는 프로젝트 구조를 거의 강제하지 않는다. 개발자는 폴더 구조, 비즈니스 로직 분리, 의존성 관리, 예외 처리, 인증 방식 등을 직접 결정해야 한다.

작은 프로젝트에서는 이러한 자유로움이 장점이다. 반면 프로젝트가 커지면 개발자마다 서로 다른 방식으로 코드를 작성해 구조가 일관되지 않거나, 라우터와 비즈니스 로직이 강하게 결합되는 문제가 발생할 수 있다.

NestJS는 이 문제를 해결하기 위해 다음과 같은 구조를 기본으로 제공한다.

- 역할에 따라 코드를 나누는 Module, Controller, Provider
- 클래스 간 의존성을 관리하는 의존성 주입
- 데코레이터를 활용한 선언적인 라우팅
- 인증, 검증, 로깅, 예외 처리를 위한 공통 실행 계층
- 테스트하기 쉬운 애플리케이션 구조

쉽게 말하면 Express의 유연함 위에 대규모 애플리케이션을 위한 설계 규칙과 개발 도구를 더한 프레임워크라고 볼 수 있다.

# NestJS의 주요 특징

### TypeScript 중심의 개발

NestJS는 JavaScript로도 사용할 수 있지만 TypeScript를 중심으로 설계됐다.

TypeScript를 사용하면 함수의 입력과 출력, 객체의 형태, 클래스 간 관계를 코드에 명시할 수 있다. 컴파일 단계에서 일부 오류를 발견할 수 있고, IDE의 자동 완성과 리팩터링 지원도 더 잘 활용할 수 있다.

백엔드 프로젝트는 데이터베이스 모델, API 요청과 응답, 서비스 간 인터페이스처럼 데이터 구조를 다룰 일이 많다. 따라서 타입을 명확히 정의하는 것이 장기적인 유지보수에 큰 도움이 된다.

### 데코레이터 기반 구조

NestJS 코드에서는 `@Controller()`, `@Get()`, `@Injectable()` 같은 표현을 자주 볼 수 있다. 이를 데코레이터라고 한다.

데코레이터는 클래스나 메서드에 역할과 부가 정보를 선언한다.

```typescript
@Controller('users')
export class UsersController {
  @Get()
  findAll() {
    return '사용자 목록';
  }
}
```

위 코드에서 `@Controller('users')`는 이 클래스가 `/users` 경로의 요청을 처리한다는 뜻이다. `@Get()`은 해당 메서드가 HTTP Method인 GET 요청을 담당한다는 의미다.

라우팅 정보와 클래스의 역할이 코드에 드러나기 때문에 전체 구조를 비교적 쉽게 파악할 수 있다.

### 의존성 주입

의존성 주입(Dependency Injection)은 NestJS의 핵심 개념이다. (이 의존성 주입은 Spring Framework에서도 쓰이는 개념으로 기본적으로 알아두는게 좋다)

어떤 클래스가 필요한 객체를 직접 생성하지 않고, 외부에서 전달받아 사용하는 방식이다.

```typescript
@Injectable()
export class UsersService {
  findAll() {
    return ['Kim', 'Lee', 'Park'];
  }
}

@Controller('users')
export class UsersController {
  constructor(private readonly usersService: UsersService) {}

  @Get()
  findAll() {
    return this.usersService.findAll();
  }
}
```

`UsersController`는 `UsersService`를 직접 `new`로 생성하지 않는다. NestJS의 의존성 주입 컨테이너가 필요한 인스턴스를 만들어 생성자(constructor)에 전달한다.

이 구조를 사용하면 클래스 간 결합이 줄어든다. 테스트할 때 실제 서비스 대신 가짜 객체를 주입하기도 쉬워진다.

# NestJS의 핵심 구성 요소

### 1. Module

Module은 관련된 기능을 하나의 단위로 묶는다.

예를 들어 사용자 기능에는 사용자 Controller, Service, Repository가 필요할 수 있다. 이를 `UsersModule`에 모아 관리할 수 있다.

```typescript
import { Module } from '@nestjs/common';
import { UsersController } from './users.controller';
import { UsersService } from './users.service';

@Module({
  controllers: [UsersController],
  providers: [UsersService],
  exports: [UsersService],
})
export class UsersModule {}
```

`@Module()`에는 주로 다음 항목이 들어간다.

- `imports`: 현재 모듈에서 사용할 다른 모듈
- `controllers`: 요청을 처리할 Controller
- `providers`: 사용할 Service나 Repository 등의 Provider
- `exports`: 다른 모듈에 공개할 Provider

모든 NestJS 애플리케이션에는 시작점이 되는 루트 모듈이 있으며, 일반적으로 `AppModule`이라는 이름을 사용한다.

### 2. Controller

Controller는 클라이언트의 요청을 받고 응답을 반환한다.

```typescript
import { Controller, Get, Param, Post, Body } from '@nestjs/common';

@Controller('users')
export class UsersController {
  @Get()
  findAll() {
    return '모든 사용자를 조회합니다.';
  }

  @Get(':id')
  findOne(@Param('id') id: string) {
    return `${id}번 사용자를 조회합니다.`;
  }

  @Post()
  create(@Body() body: CreateUserDto) {
    return body;
  }
}
```

Controller에서는 다음과 같은 데코레이터를 자주 사용한다.

- `@Get()`, `@Post()`, `@Patch()`, `@Delete()`: HTTP 메서드 지정
- `@Param()`: URL 경로의 매개변수 추출
- `@Query()`: 쿼리스트링 추출
- `@Body()`: 요청 본문 추출
- `@Headers()`: 요청 헤더 추출

Controller에는 요청과 응답을 연결하는 코드만 두고, 복잡한 비즈니스 로직은 Service로 분리하는 것이 일반적이다.

### 3. Provider와 Service

Provider는 NestJS의 의존성 주입 컨테이너가 관리하는 객체다. Service, Repository, Factory, Helper 등이 Provider가 될 수 있다.

그중 Service는 비즈니스 로직을 담당하는 가장 대표적인 Provider다.

```typescript
import { Injectable, NotFoundException } from '@nestjs/common';

@Injectable()
export class UsersService {
  private readonly users = [
    { id: 1, name: 'Kim' },
    { id: 2, name: 'Lee' },
  ];

  findOne(id: number) {
    const user = this.users.find((item) => item.id === id);

    if (!user) {
      throw new NotFoundException('사용자를 찾을 수 없습니다.');
    }

    return user;
  }
}
```

`@Injectable()`을 붙인 클래스는 다른 클래스에 주입될 수 있다. 데이터 조회나 정책 판단 같은 핵심 로직을 Controller에서 분리하면 같은 기능을 여러 곳에서 재사용하기 쉬워진다.

### 4. DTO

DTO(Data Transfer Object)는 계층 사이에서 전달되는 데이터의 형태를 정의하는 객체다.

```typescript
export class CreateUserDto {
  name!: string;
  email!: string;
}
```

DTO를 사용하면 Controller가 어떤 데이터를 받는지 명확해지고, API 문서 생성이나 입력값 검증에도 활용할 수 있다.

`class-validator`와 NestJS의 `ValidationPipe`를 함께 사용하면 요청 데이터를 검증할 수 있다.

```typescript
import { IsEmail, IsString, MinLength } from 'class-validator';

export class CreateUserDto {
  @IsString()
  @MinLength(2)
  name!: string;

  @IsEmail()
  email!: string;
}
```

```typescript
app.useGlobalPipes(
  new ValidationPipe({
    whitelist: true,
    transform: true,
  }),
);
```

이렇게 설정하면 정의되지 않은 필드를 제거하고, 잘못된 입력에는 자동으로 오류 응답을 반환할 수 있다.

# 요청은 어떤 과정을 거칠까?

NestJS는 요청과 응답 사이에 여러 실행 계층을 둘 수 있다.

전체 흐름을 단순화하면 다음과 같다.

```text
클라이언트 요청
→ Middleware
→ Guard
→ Interceptor
→ Pipe
→ Controller
→ Service
→ Interceptor
→ 클라이언트 응답
```

각 구성 요소의 역할은 다음과 같다.

### Middleware

요청이 본격적으로 처리되기 전에 공통 작업을 수행한다. 요청 로그, 쿠키 처리, 헤더 설정 등에 사용할 수 있다.

### Guard

요청을 계속 처리해도 되는지 판단한다. 로그인 여부나 사용자 권한을 검사하는 인증·인가 로직에 주로 사용된다.

### Pipe

Controller에 값이 전달되기 전에 입력을 검증하거나 변환한다. 문자열로 들어온 ID를 숫자로 바꾸거나 DTO의 유효성을 검사하는 것이 대표적이다.

### Interceptor

Controller 실행 전후의 흐름을 감싼다. 응답 형식을 통일하거나, 실행 시간을 측정하거나, 캐시를 적용할 때 사용할 수 있다.

### Exception Filter

애플리케이션에서 발생한 예외를 잡아 적절한 HTTP 응답으로 변환한다. 서비스 전체에서 일관된 오류 응답 형식을 만들 때 유용하다.

각 기능의 책임이 분리되어 있기 때문에 인증이나 로깅 같은 코드를 모든 Controller에 반복해서 작성하지 않아도 된다.

# NestJS 프로젝트 시작하기

Nest CLI를 설치하면 기본 프로젝트를 빠르게 만들 수 있다.

```bash
npm install -g @nestjs/cli
nest new my-api
cd my-api
npm run start:dev
```

개발 서버가 실행되면 기본적으로 `http://localhost:3000`에서 애플리케이션을 확인할 수 있다.

생성된 프로젝트의 대표적인 파일은 다음과 같다.

```text
src/
├── app.controller.ts
├── app.controller.spec.ts
├── app.module.ts
├── app.service.ts
└── main.ts
```

- `main.ts`: 애플리케이션을 생성하고 서버를 실행하는 진입점
- `app.module.ts`: 루트 모듈
- `app.controller.ts`: 기본 요청을 처리하는 Controller
- `app.service.ts`: 기본 비즈니스 로직을 담는 Service
- `app.controller.spec.ts`: Controller 테스트 파일

CLI를 이용하면 필요한 구성 요소도 생성할 수 있다.

```bash
nest generate module users
nest generate controller users
nest generate service users
```

축약형인 `nest g module users`, `nest g controller users`, `nest g service users`도 사용할 수 있다.

# Express와 NestJS의 차이

Express와 NestJS는 완전히 경쟁하는 기술이라기보다 추상화 수준이 다르다. NestJS는 기본적으로 Express를 HTTP 플랫폼으로 사용한다.

| 구분 | Express | NestJS |
|---|---|---|
| 성격 | 미니멀한 웹 프레임워크 | 구조화된 애플리케이션 프레임워크 |
| 기본 언어 | JavaScript | TypeScript 중심 |
| 프로젝트 구조 | 개발자가 직접 결정 | Module 중심의 구조 제공 |
| 의존성 주입 | 직접 구성 | 기본 제공 |
| 학습 난이도 | 비교적 낮음 | 개념이 많아 초기 학습 필요 |
| 자유도 | 높음 | 일정한 규칙과 패턴을 따름 |
| 적합한 환경 | 작은 API, 빠른 프로토타입 | 중대형 서비스, 협업 프로젝트 |

작은 서버나 간단한 API라면 Express가 더 빠르고 가벼울 수 있다. 여러 도메인과 개발자가 참여하는 장기 프로젝트라면 NestJS의 구조가 더 큰 장점이 된다.

# NestJS로 만들 수 있는 것

NestJS는 일반적인 REST API 외에도 다양한 서버 애플리케이션을 지원한다.

- REST API 서버
- GraphQL 서버
- WebSocket 기반 실시간 서비스
- 마이크로서비스
- gRPC 서비스
- 메시지 큐 기반 비동기 처리
- 예약 작업과 배치 프로그램
- 서버 렌더링 애플리케이션

데이터베이스 역시 특정 기술에 종속되지 않는다. TypeORM, Prisma, Mongoose, Sequelize, MikroORM 등을 프로젝트 요구사항에 맞게 연결할 수 있다.

Swagger/OpenAPI 연동을 사용하면 Controller와 DTO의 정보를 이용해 API 문서를 생성할 수도 있다. 인증에는 Passport, 설정 관리에는 `@nestjs/config`, 스케줄 작업에는 `@nestjs/schedule` 같은 공식 패키지를 활용할 수 있다.

# NestJS의 장점

### 일관된 프로젝트 구조

Module, Controller, Service의 역할이 명확해 여러 개발자가 함께 작업해도 코드 구조를 예측하기 쉽다.

### 높은 유지보수성과 확장성

기능을 모듈 단위로 분리할 수 있어 프로젝트가 커져도 책임의 경계를 관리하기 좋다.

### 테스트하기 좋은 구조

의존성 주입을 기본으로 사용하기 때문에 실제 데이터베이스나 외부 API 대신 테스트용 객체를 주입하기 쉽다.

### 풍부한 기능

입력 검증, 인증, 캐싱, 로깅, WebSocket, GraphQL, 마이크로서비스 등 서버 개발에 필요한 기능을 공식 문서와 패키지에서 폭넓게 다룬다.

### Express 생태계 활용

기본 플랫폼이 Express이므로 기존 Express 미들웨어와 Node.js 패키지의 상당 부분을 활용할 수 있다. 성능이나 요구사항에 따라 Fastify 어댑터를 선택할 수도 있다.

# 단점과 주의할 점

NestJS는 처음 배울 때 알아야 할 개념이 많다. Module, Provider, Guard, Pipe, Interceptor, 의존성 주입의 관계를 이해하기 전까지는 간단한 기능도 복잡하게 느껴질 수 있다.

데코레이터와 프레임워크의 자동 처리에 익숙하지 않으면 코드가 실제로 어떤 순서로 실행되는지 파악하기 어려울 수도 있다. 문제가 발생했을 때는 요청 생명주기와 의존성 주입 컨테이너의 동작을 이해해야 한다.

또한 작은 프로젝트에서는 파일 수와 초기 설정이 과하게 느껴질 수 있다. 단순한 API 하나를 만들기 위해 Module, Controller, Service, DTO 파일이 필요하다면 Express나 Fastify를 직접 사용하는 편이 효율적일 수 있다.

구조를 제공한다는 장점이 지나친 계층 분리로 이어지지 않도록 주의해야 한다. 규모가 작은 기능까지 무조건 여러 계층으로 나누면 오히려 탐색하기 어려운 코드가 될 수 있다.

# 언제 NestJS를 사용하면 좋을까?

다음과 같은 상황이라면 NestJS가 좋은 선택이 될 수 있다.

- TypeScript로 백엔드 서비스를 개발하려는 경우
- 여러 개발자가 장기간 유지보수할 프로젝트
- 사용자, 주문, 결제처럼 도메인이 여러 개로 나뉘는 서비스
- 인증, 권한, 검증, 로깅 같은 공통 기능이 많은 프로젝트
- REST API에서 향후 GraphQL이나 마이크로서비스로 확장할 가능성이 있는 경우
- 의존성 주입과 객체지향적인 설계를 선호하는 팀
- 자동화된 단위 테스트와 통합 테스트가 중요한 서비스

반대로 단순한 서버리스 함수, 매우 작은 API, 짧은 프로토타입이라면 더 가벼운 프레임워크가 적합할 수 있다.

프레임워크 선택에서 중요한 것은 어떤 기술이 무조건 더 좋으냐가 아니다. 서비스 규모, 팀의 경험, 성능 요구사항, 운영 기간을 함께 고려할 수 있어야한다.

# 처음 공부할 때 추천하는 순서

NestJS의 모든 기능을 처음부터 공부할 필요는 없다. 다음 순서로 작은 CRUD API를 만들어 보는 것이 이해하기 쉽다.

```text
Module과 프로젝트 구조
→ Controller와 라우팅
→ Service와 의존성 주입
→ DTO와 입력값 검증
→ 데이터베이스 연결
→ 예외 처리
→ 인증과 Guard
→ Interceptor와 로깅
→ 테스트 및 API 문서화
```

게시글이나 강의의 코드를 그대로 외우기보다는 요청 하나가 Controller, Service, 데이터베이스를 어떻게 거쳐 응답으로 돌아오는지 추적하는 것이 중요하다.

# 마무리

NestJS는 현재 나도 개발에 주력으로 쓰고있는 프레임워크인 만큼 애정도가 상당히 깊다.

NestJS를 사용해 서버개발을 한다면 TypeScript, 데코레이터, 의존성 주입, 모듈 시스템을 이용해 확장 가능하고 테스트하기 쉬운 서버 애플리케이션을 만들 수 있다.

NestJS의 가장 큰 장점은 단순히 기능이 많다는 점이 아니다. 개발자가 늘어나고 서비스가 복잡해져도 코드의 역할과 위치를 예측할 수 있게 해준다는 데 있다. (뭐 물론 대부분의 프레임워크가 이럴려고 사용하는거긴 하지만...)

당연한 얘기지만 모든 프로젝트에 NestJS가 필요한 것은 아니다. 엔터프라이즈급으로 간다면 자바 공화국인 한국에서 밀고있는 전자정부 프레임워크의 기반이 되는 Spring Framework부터 여전히 한국의 여러 작은 중소기업에서 쓰고있는 PHP의 Laravel, CodeIgniter 등 이 외에도 여러 선택지는 많다.

만약 작은 서비스, 작은 API에서는 NestJS가 구조가 부담이 될 수 있고 초기 학습 비용도 존재한다. 하지만 여러 기능이 연결되는 중대형 백엔드 서비스를 TypeScript로 개발한다면 충분히 고려할 가치가 있다.

NestJS란? 개요부터 핵심 구조와 장단점까지

독자의 메모