첫 번째 NestJS 애플리케이션 만들기

앞 글에서 만들고 실행해 본 Hello World! 애플리케이션은 NestJS의 가장 기본적인 모습입니다. 이 글에서는 그 애플리케이션의 구조를 자세히 살펴보고, Hello World!가 브라우저에 나타나기까지 NestJS가 요청을 어떻게 처리하는지 따라갑니다.

그림은 두 단계로 나뉩니다. 요청 전의 부트스트랩 단계에서는 main.ts가 AppModule을 Nest에 넘기고, DI 컨테이너가 기본 범위의 프로바이더를 만들어 컨트롤러에 주입합니다. 요청마다 실행되는 단계에서는 브라우저의 GET /가 AppController의 경로와 맞고, 이미 주입된 AppService가 돌려준 'Hello World!' 문자열이 JSON으로 바뀌지 않고 그대로 응답됩니다. AppModule은 조립 정보일 뿐, 요청이 매번 거치는 단계가 아닙니다.

프로젝트의 기본 구조

nest new로 프로젝트를 만들면 다음과 같은 디렉터리와 파일이 생깁니다. 모든 파일을 다 보기보다, 지금 이해해야 할 핵심 파일을 중심으로 살펴봅니다.

이 표는 네 핵심 파일이 무엇을 맡고, Hello World! 응답에 어떻게 기여하며, 어떤 변경이 생길 때 고치게 되는지를 비교합니다. main.ts는 애플리케이션을 시작하고 HTTP 리스너를 열며, AppModule은 컨트롤러와 프로바이더를 등록하고, AppController는 HTTP 경로와 응답을, AppService는 HTTP와 분리된 로직을 맡습니다. 맨 아래 줄은 @Injectable()이 컨테이너가 관리할 수 있다는 메타데이터일 뿐, 실제로 주입되려면 그 프로바이더가 현재 모듈의 범위에서 보여야 한다는 점을 짚습니다.

src/는 애플리케이션의 소스 코드가 모두 들어가는 디렉터리입니다. main.ts는 애플리케이션의 진입점(entry point)으로, 여기서 NestJS 애플리케이션 인스턴스를 만들고 시작합니다. app.module.ts는 애플리케이션의 최상위 모듈인 루트 모듈(root module)이고, app.controller.ts는 GET / 요청을 받아 Hello World!를 돌려주는 AppController를, app.service.ts는 컨트롤러가 호출하는 프로바이더인 AppService를 정의합니다.

프로젝트 루트의 package.json은 프로젝트의 메타데이터, 의존성 목록, 실행 스크립트를 정의하고, tsconfig.json은 TypeScript 컴파일러 옵션을 정합니다. NestJS 12의 새 프로젝트는 린터로 oxlint를 쓰므로 .oxlintrc.json이 생기고, CommonJS 구성은 Jest를 쓰므로 jest.config.ts도 함께 생깁니다.

첫 요청이 처리되는 흐름

포트를 바꾸지 않았다면 http://localhost:3000에 접속했을 때 Hello World!가 나옵니다. 이 응답이 만들어지기까지의 흐름을 다섯 단계로 따라가 봅니다.

main.ts 실행

npm run start:dev는 Nest CLI를 감시 모드로 실행하고, Nest는 진입점인 main.ts를 기준으로 애플리케이션을 부트스트랩합니다. CLI가 CommonJS 구성으로 만든 main.ts의 핵심은 다음과 같습니다.

import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';

async function bootstrap() {
  // NestJS 애플리케이션 인스턴스를 만듭니다. AppModule이 루트 모듈입니다.
  const app = await NestFactory.create(AppModule);
  // PORT 환경 변수가 없으면 3000번 포트에서 요청을 기다립니다.
  await app.listen(process.env.PORT ?? 3000);
}
void bootstrap(); // 애플리케이션을 시작합니다.

NestFactory.create(AppModule)는 넘겨받은 AppModule 클래스와 그 @Module() 메타데이터를 부트스트랩의 입력으로 씁니다. app.listen(...)은 받은 포트에서 HTTP 요청을 기다립니다. 마지막 줄의 void는 반환된 Promise를 일부러 기다리지 않는다는 표시입니다. ESM 구성을 골랐다면 import에 .js 확장자가 붙고 await bootstrap();으로 시작하는 등 표기가 다르므로, 실제 프로젝트의 main.ts와 실행 로그에 표시된 주소를 기준으로 확인합니다.

AppModule 초기화

main.ts가 AppModule을 넘겼으므로, NestJS는 이 클래스의 @Module() 메타데이터를 읽어 애플리케이션 그래프를 만듭니다. 아래 코드에서는 imports, controllers, providers 세 배열을 보면 됩니다. 이 예제의 imports는 비어 있으므로, 그래프는 다른 모듈 없이 이 모듈에 등록한 두 클래스만으로 만들어집니다.

import { Module } from '@nestjs/common';
import { AppController } from './app.controller';
import { AppService } from './app.service';

@Module({
  imports: [], // 다른 모듈을 가져올 때 사용합니다.
  controllers: [AppController], // 이 모듈에 속한 컨트롤러를 등록합니다.
  providers: [AppService], // 이 모듈에 속한 프로바이더를 등록합니다.
})
export class AppModule {}

controllers 배열에는 AppController가, providers 배열에는 AppService가 등록되어 있습니다. NestJS는 이 정보로 두 클래스의 의존 관계를 해석합니다. 범위를 따로 지정하지 않은 프로바이더는 애플리케이션의 수명 주기 동안 하나를 공유하는 싱글턴으로 만들어져 컨트롤러의 생성자에 주입됩니다.

AppController의 요청 처리

포트를 바꾸지 않았다면 브라우저는 http://localhost:3000으로 요청을 보냅니다. 요청이 애플리케이션에 도착하면, 애플리케이션은 등록된 컨트롤러 가운데 이 요청을 처리할 메서드를 찾습니다.

import { Controller, Get } from '@nestjs/common';
import { AppService } from './app.service';

@Controller() // 이 클래스가 컨트롤러임을 나타냅니다. 기본 경로는 '/' 입니다.
export class AppController {
  // AppService를 주입받습니다. NestJS가 자동으로 AppService 인스턴스를 제공합니다.
  constructor(private readonly appService: AppService) {}

  @Get() // HTTP GET 요청, 경로가 '/'일 때 이 메서드가 실행됩니다.
  getHello(): string {
    // AppService의 getHello() 메서드를 호출하여 결과값을 반환합니다.
    return this.appService.getHello();
  }
}

@Controller()에 경로 접두사가 없고 @Get()에도 경로가 없으므로, 이 메서드는 GET / 요청에 매핑됩니다. 생성자의 private readonly appService: AppService가 NestJS의 핵심 기능인 의존성 주입입니다. AppService가 AppModule의 providers에 기본 범위로 등록되어 있으므로, NestJS는 애플리케이션이 공유하는 인스턴스를 만들어 AppController에 넣어 줍니다. 그래서 컨트롤러가 new AppService()처럼 직접 인스턴스를 만들 필요가 없습니다.

AppService의 업무 처리

getHello()는 주입받은 appService의 getHello()를 호출합니다. 호출을 받는 AppService는 요청이나 응답 객체를 전혀 다루지 않고 문자열 하나만 돌려줍니다. 그래서 같은 메서드를 테스트나 다른 프로바이더에서 HTTP 없이 그대로 부를 수 있습니다.

import { Injectable } from '@nestjs/common';

@Injectable() // 이 클래스가 프로바이더임을 나타냅니다. (다른 곳에 주입될 수 있음)
export class AppService {
  getHello(): string {
    return 'Hello World!'; // 간단하게 "Hello World!" 문자열을 반환합니다.
  }
}

@Injectable()은 이 클래스를 NestJS의 의존성 주입 시스템이 관리할 수 있도록 메타데이터를 붙입니다. 실제로 주입되려면 이 프로바이더를 현재 모듈의 범위에 등록하거나 다른 모듈에서 가져와야 합니다. getHello()는 'Hello World!' 문자열을 돌려줍니다.

응답 반환

AppService.getHello()가 돌려준 문자열은 AppController.getHello()로 돌아옵니다. Nest의 표준 응답 처리에서 문자열 같은 원시 값은 JSON으로 직렬화하지 않고 값 그대로 HTTP 응답에 담아 브라우저로 보냅니다.

부트스트랩과 요청을 그림에서 나눈 이유도 여기에 있습니다. 이 예제처럼 기본 범위를 쓰는 프로바이더는 등록, 생성, 주입이 요청 전에 모두 끝나고, 실제 GET / 요청에서는 AppController가 이미 주입된 AppService를 씁니다.

더 깊이: 문자열 응답에 붙는 Content-Type

핸들러가 돌려준 값을 실제 HTTP 응답으로 쓰는 일은 HTTP 어댑터가 맡습니다. 기본값인 Express 어댑터의 reply() 소스를 보면, 값이 null이나 undefined면 본문 없이 응답을 끝내고, 객체나 배열이면 Express의 res.json()으로 보냅니다. 그 밖의 값은 String()으로 바꾼 뒤 res.send()에 넘깁니다. 그래서 숫자 42를 돌려줘도 문자열 42가 본문이 됩니다.

Express의 res.send()는 문자열을 받으면 Content-Type을 text/html로 정합니다. 즉 Hello World!는 JSON이 아니라 HTML 문서로 전달되고, 브라우저도 그렇게 해석합니다. 반면 Fastify는 Content-Type 없이 받은 문자열을 text/plain; charset=utf-8로 보내고, Nest의 Fastify 어댑터는 문자열을 그대로 Fastify에 넘깁니다. 1장 첫 글에서 소개한 NodeAdapter도 어댑터 문서에 따르면 문자열을 text/plain으로 보냅니다. 같은 핸들러라도 어댑터에 따라 응답 헤더가 달라질 수 있으므로, 클라이언트가 형식에 기대는 응답이라면 문자열 대신 객체를 돌려주어 JSON으로 고정하는 편이 안전합니다.

등록이 빠졌을 때의 실패 시점

TypeScript의 import는 코드를 참조할 수 있게 할 뿐이고, @Module()의 배열은 Nest가 관리할 대상을 등록합니다. 파일을 가져왔다는 사실만으로 프로바이더나 HTTP 핸들러가 등록되지는 않습니다. 다음은 기본 범위, 이 글의 클래스와 생성자, 정상적인 포트 설정에서 다른 모듈이 AppService를 제공하지 않을 때 AppModule을 바꾼 결과입니다.

둘째 줄은 서비스가 등록되지 않아 컨트롤러를 조립하지 못한 실패이고, 셋째와 넷째 줄은 요청과 맞는 컨트롤러 핸들러가 없는 실패입니다. 어느 파일을 열었는지보다, 시작 로그와 실제 요청의 메서드·경로를 함께 보면 원인을 빨리 좁힐 수 있습니다.

더 깊이: 부트스트랩이 실패하면 프로세스는 어떻게 끝날까

둘째 줄처럼 애플리케이션을 만드는 도중에 오류가 나면, Nest는 오류를 로그로 남긴 뒤 프로세스를 종료 코드 1로 끝냅니다. 소스 코드에서는 NestFactory가 모듈 탐색과 인스턴스 생성을 ExceptionsZone 안에서 실행하고, 오류가 나면 기본 정리 함수가 process.exit(1)을 호출합니다. 그래서 main.ts의 bootstrap() 호출에 catch를 붙여도 이 오류를 받을 기회가 없습니다. 0이 아닌 종료 코드는 실패를 뜻하므로, Docker의 on-failure 재시작 정책 같은 실행 환경은 이 종료를 실패로 다룹니다.

오류를 직접 처리하고 싶다면 공식 시작 문서가 설명하는 abortOnError 옵션을 끕니다. NestFactory.create(AppModule, { abortOnError: false })로 만들면 종료하는 대신 오류를 다시 던지므로, create가 돌려준 Promise가 거부되고 호출한 쪽에서 오류를 받아 정리 작업이나 다른 형식의 보고를 할 수 있습니다. 이때도 Nest는 오류를 다시 던지기 전에 ExceptionHandler 로거로 기록하지만 프로세스를 끝내지는 않으므로, 거부된 Promise를 받아 종료 코드를 정하는 일은 호출한 코드가 직접 해야 합니다.

정리

• main.ts가 NestFactory.create(AppModule)로 애플리케이션을 만들고 listen으로 요청을 기다립니다.
• AppModule의 controllers와 providers가 Nest가 관리할 대상을 등록하며, 기본 범위의 프로바이더는 요청 전에 만들어져 주입됩니다.
• URL은 @Controller()의 접두사와 @Get()의 경로가 합쳐 정하고, 메서드 이름은 URL과 관계가 없습니다.
• 서비스가 등록되지 않으면 부트스트랩에서 실패하고, 컨트롤러가 등록되지 않거나 메서드·경로가 맞지 않으면 요청에서 404가 납니다.

연습 문제

1. 응답과 경로를 하나씩 바꾸기

실행 중인 첫 앱에서 AppService.getHello()의 반환 문자열만 'Hello Nest!'로 바꾸면 GET /의 응답은 어떻게 되나요? 이어서 컨트롤러의 @Get()을 @Get('hello')로 바꾸면 어느 요청이 새 문자열을 받고, GET /는 어떻게 되나요? 전역 접두사는 없습니다.

2. 접두사와 핸들러 경로

전역 접두사가 없는 같은 앱에서 @Controller('welcome')과 @Get('message')로 바꾸고, 서비스는 원래 문자열을 돌려준다고 합니다. 요청할 HTTP 메서드와 경로, 예상 응답을 쓰세요. 요청을 두 번 보내면 AppModule이 매번 새로 만들어지나요?

3. import는 있는데 providers가 비어 있으면

AppController가 생성자로 AppService를 요구합니다. 두 파일의 import와 @Injectable()은 그대로 두고 providers: []로 바꾸었으며, 다른 모듈도 AppService를 제공하지 않습니다. 첫 GET 요청에서야 서비스 오류가 나나요?

4. 컨트롤러 등록과 메서드 이름

providers: [AppService]는 그대로 두고 controllers: []로 바꾸었습니다. 다른 컨트롤러와 미들웨어는 없고 리스너는 정상적으로 열렸습니다. AppService에 getHello()가 있으니 GET /에 응답할까요? 별도로, 컨트롤러를 다시 등록하고 컨트롤러와 서비스의 메서드 이름만 welcome()으로 바꾸면 GET /, GET /welcome, POST / 가운데 어느 요청이 이 핸들러를 고르나요?

다음 글 모듈, 컨트롤러, 서비스의 기본 개념에서는 같은 요청 흐름을 사용자 목록 예제로 넓혀, 세 구성 요소가 맡는 일을 구분합니다. 의존성 주입과 IoC 컨테이너는 2장에서 더 깊이 다룹니다.