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

NestJS 개발 환경 구성이 완료되었습니다.

앞서 생성하고 실행해 본 Hello World! 애플리케이션은 NestJS의 가장 기본적인 형태를 보여줬습니다.

이번 절에서는 이 애플리케이션의 기본 구조를 자세히 살펴보고, Hello World! 메시지가 화면에 나타나는 과정, 즉 NestJS가 요청을 처리하는 흐름을 함께 파헤쳐 보겠습니다.

프로젝트 기본 구조 이해하기

NestJS CLI를 통해 nest new 명령어로 프로젝트를 생성하면 다음과 같은 디렉토리 및 파일 구조를 갖게 됩니다.

모든 파일을 다 살펴보기보다는 지금 당장 우리가 이해해야 할 핵심적인 파일들을 중심으로 살펴보겠습니다.

• src/ 디렉토리: NestJS 애플리케이션의 모든 소스 코드가 위치하는 핵심 디렉토리입니다. 우리가 작성할 대부분의 코드는 이 안에 들어있습니다.

  • main.ts: 애플리케이션의 진입점(Entry Point) 파일입니다. npm run start:dev는 Nest CLI를 watch 모드로 실행하고, Nest는 이 엔트리 파일을 기준으로 애플리케이션을 부트스트랩합니다. 여기서 NestJS 애플리케이션 인스턴스를 생성하고 시작합니다.
  • app.module.ts: 애플리케이션의 루트 모듈(Root Module)입니다. NestJS 애플리케이션의 최상위 모듈이며, 다른 모든 모듈의 기반이 됩니다. 앞서 1장 1절에서 설명했듯이, 모듈은 컨트롤러와 프로바이더를 묶어주는 역할을 합니다.
  • app.controller.ts: AppController를 정의하는 파일입니다. / 경로로 들어오는 HTTP GET 요청을 처리하고 Hello World! 문자열을 반환하는 로직을 담고 있습니다. 클라이언트의 요청을 받아들이는 역할을 합니다.
  • app.service.ts: AppService를 정의하는 파일입니다. AppService는 컨트롤러에서 호출하여 실제 비즈니스 로직(여기서는 Hello World! 문자열을 반환하는 간단한 로직)을 처리하는 프로바이더의 한 종류입니다.

• package.json: 프로젝트의 메타데이터와 의존성 패키지 목록, 실행 스크립트 등을 정의하는 파일입니다. npm install 명령어를 실행하면 여기에 명시된 패키지들이 설치됩니다.

• tsconfig.json: TypeScript 컴파일러 옵션을 설정하는 파일입니다. NestJS는 TypeScript 기반이므로, 이 파일이 중요하게 사용됩니다.

NestJS 애플리케이션의 실행 흐름 추적하기

이제 listener가 사용하는 포트를 바꾸지 않았을 때 http://localhost:3000으로 접속하면 Hello World!가 어떻게 출력되는지, NestJS 내부의 동작 흐름을 따라가 보겠습니다.

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);
}
bootstrap(); // bootstrap 함수를 호출하여 애플리케이션을 시작합니다.

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

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

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();
  }
}

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

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

앞의 다이어그램에서 부트스트랩과 요청을 나눈 이유도 여기에 있습니다. 이 예제처럼 기본 scope를 사용하는 provider는 DI 컨테이너의 등록·생성·주입이 요청 처리 전에 완료되고, 실제 GET / 요청에서는 AppController가 이미 주입된 AppService를 사용합니다.

응답을 바꾸며 요청 경로 확인하기

1. 실행 중인 첫 앱에서 AppService.getHello()의 반환 문자열만 'Hello Nest!'로 바꿉니다. 감시 모드의 재컴파일이 끝난 뒤 GET /를 다시 요청하면 새 문자열이 나와야 합니다. 컨트롤러는 같은 메서드를 호출하므로 수정할 필요가 없습니다.
2. 그다음 컨트롤러의 @Get()을 @Get('hello')로 바꿉니다. 전역 접두사가 없다는 전제에서 이제 GET /hello가 새 문자열을 반환합니다. 다른 루트 핸들러가 없다면 GET /는 404가 됩니다. 문자열은 그대로인데 요청 경로만 달라진 것입니다.
3. 다음 절의 기본 상태와 비교할 수 있도록 두 변경을 원래 코드로 되돌립니다.

getHello라는 메서드 이름이 URL을 정하지는 않습니다. 경로는 데코레이터가, 반환 값은 메서드가 결정합니다. 실제 실행 로그나 응답이 예상과 다르면 저장한 파일과 감시 재컴파일 결과를 먼저 확인하세요.

코드를 보지 않고 예상해 보기

전역 접두사가 없는 같은 앱에서 @Controller('welcome'), @Get('message')로 바꾸고 서비스는 원래 문자열을 반환한다고 가정합니다. 요청할 HTTP 메서드·경로와 예상 응답을 써 보세요. 이어 요청을 두 번 보낼 때 AppModule을 매번 새로 만드는지도 설명해 보세요.

이번 절에서는 NestJS가 모듈, 컨트롤러, 프로바이더를 이용해 요청을 받고 응답을 반환하는 흐름을 정리했습니다.

이후 기능도 이 기본 구조 위에서 라우팅, 의존성, 서비스 로직을 확장하는 방식으로 구성됩니다.

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

등록이 빠졌을 때는 실패 시점부터 구분하기

아래 비교는 기본 scope, 이 장의 클래스와 생성자, 정상적인 포트 설정을 사용하며 다른 모듈에서 AppService를 제공하지 않는 경우입니다. TypeScript의 import는 코드를 참조하게 하고, @Module()의 배열은 Nest가 관리할 대상을 등록합니다. 파일을 가져왔다는 사실만으로 provider나 HTTP handler가 등록되지는 않습니다.

첫 번째 실패는 “서비스가 등록되지 않아 controller를 조립하지 못함”, 두 번째 실패는 “요청과 일치하는 controller handler가 없음”입니다. 어느 파일의 코드를 열었는지보다 시작 로그와 실제 요청 method·path를 함께 확인하면 원인을 좁힐 수 있습니다.

조건을 바꿔 확인하기