NestJS Application — 애플리케이션 시작점

NestJS 서버는 main.ts 단 하나의 파일에서 시작된다. 이 파일이 Bootstrap 함수를 호출하고, HTTP 서버가 포트를 열기까지의 흐름을 이해하면 Global 설정이 어디서 적용되는지 자연스럽게 보인다.

Bootstrap 흐름

main.ts
  └─ NestFactory.create(AppModule)
       └─ INestApplication 인스턴스 생성
            ├─ Global Middleware 등록
            ├─ Global Pipe 등록
            ├─ Global Filter 등록
            ├─ Global Guard 등록
            └─ app.listen(3000)
                 └─ HTTP 서버 시작

NestFactory.create는 내부적으로 IoC 컨테이너를 초기화하고 AppModule에 선언된 모든 Provider를 등록한다. 반환값은 INestApplication 인터페이스를 구현한 인스턴스다.

IoC(Inversion of Control): 객체 생성과 의존성 주입을 프레임워크가 담당하는 패턴.

main.ts 기본 구조

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

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  await app.listen(3000);
}

bootstrap();

bootstrap은 일반 async 함수다. await app.listen(3000)이 resolve되면 서버가 요청을 받을 준비가 된 것이다.

Global 설정 등록

app.listen 호출 전에 Global 설정을 등록해야 한다. 순서가 바뀌면 이미 열린 서버에는 적용되지 않는다.

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  // Global Pipe — 요청 데이터 유효성 검사
  app.useGlobalPipes(new ValidationPipe({ whitelist: true }));

  // Global Filter — 예외를 HTTP 응답으로 변환
  app.useGlobalFilters(new HttpExceptionFilter());

  // Global Guard — 인증/인가 전역 적용
  app.useGlobalGuards(new AuthGuard());

  // Global Prefix — 모든 라우트에 /api 접두사
  app.setGlobalPrefix('api');

  await app.listen(3000);
}

ValidationPipe: class-validator 데코레이터를 기반으로 DTO를 자동 검증하는 내장 Pipe.

Global 등록 방식 비교

main.ts에서 등록하면 간단하지만 Provider를 주입받을 수 없다. 의존성이 필요한 경우 APP_PIPE, APP_FILTER, APP_GUARD 토큰으로 Module에 등록한다.

// app.module.ts
import { APP_GUARD } from '@nestjs/core';

@Module({
  providers: [
    {
      provide: APP_GUARD,
      useClass: RolesGuard, // DI로 다른 Provider 주입 가능
    },
  ],
})
export class AppModule {}

CORS와 종료 훅

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  app.enableCors({ origin: 'https://example.com' });

  // 프로세스 종료 시 graceful shutdown
  app.enableShutdownHooks();

  await app.listen(process.env.PORT ?? 3000);
}

enableShutdownHooks 를 활성화하면 OnModuleDestroy 라이프사이클 훅이 정상적으로 호출된다. 데이터베이스 연결 종료나 진행 중인 요청 처리를 마무리할 때 필요하다.

Graceful Shutdown: 새 요청 수신을 중단하고 기존 요청을 모두 처리한 뒤 서버를 종료하는 방식.