🦅 NestJS 알아보기

백엔드 개발자로써, Spring Boot 를 주력으로 사용해왔던, "백과"의 Node 계열의 NestJS 찍먹하기.

🤔 NestJS?

Node.js 생태계는 자유롭습니다.

Express.js 같은 프레임워크는 정말 가볍고 빠르지만, 프로젝트 규모가 커질수록 "아키텍처의 부재"라는 문제에 직면하게 됩니다.

"Controller는 어디에 두지?"
"Service 로직은 어떻게 분리하지?"
"DI(의존성 주입)는 라이브러리를 써야 하나?"

개발자마다 폴더 구조가 다르고, 의존성 관리가 제각각이 되기 쉽죠. 팀 컨벤션을 정하는 데만 한세월이 걸립니다.

이때 등장한 구세주가 바로 NestJS입니다.

공식 문서가 말하는 NestJS

NestJS 공식 문서의 첫 문장은 다음과 같이 시작합니다.

Nest (NestJS) is a framework for building efficient, scalable Node.js server-side applications.
(Nest는 효율적이고 확장 가능한 Node.js 서버 측 애플리케이션을 구축하기 위한 프레임워크입니다.)

Spring Boot가 "Just Run"을 위해 많은 것을 설정해주는 것처럼, NestJS도 엔터프라이즈급 애플리케이션 개발에 필요한 도구들을 기본적으로 제공합니다.

💎 NestJS의 매력 (Spring 개발자 관점)

언어 (Language): 기본적으로 TypeScript를 지원합니다.
자바의 강력한 타입 시스템에 익숙한 우리에게, JavaScript의 동적 타이핑은 런타임 에러의 공포입니다.
NestJS는 TS 를 통해 타입 안정성을 보장해 줍니다. (물론 순수 JS로도 작성 가능합니다.)
구조 (Architecture): Spring의 MVC 패턴과 계층형 아키텍처를 그대로 가져왔습니다.
- @Controller → @Controller (데코레이터)
- @Service → @Injectable (Provider)
- @Module → @Configuration + @ComponentScan (유사 개념)
의존성 주입 (Dependency Injection): Node.js 생태계에서 드물게 DI 컨테이너를 내장하고 있습니다.
객체의 생명주기를 프레임워크가 관리하며, 결합도를 낮추는 SOLID 원칙을 지키기 매우 쉽습니다.
기반 기술 (Under the hood): 재미있는 점은 NestJS가 바닥부터 새로 만든 것이 아니라, 기존의 강력한 HTTP 서버 프레임워크인 Express (기본값) 위에서 동작한다는 점입니다.
필요하다면 퍼포먼스가 더 뛰어난 Fastify로 갈아끼울 수도 있습니다. 이는 Spring Boot가 내장 Tomcat이나 Jetty, Undertow를 추상화해서 사용하는 것과 비슷한 맥락입니다.

결론적으로 NestJS는 "Node.js의 자유로움 위에 Spring의 견고한 아키텍처를 얹은 프레임워크"라고 정의할 수 있습니다.

🛠️ NestJS 시작해보기

NestJS는 강력한 CLI (Command Line Interface)를 제공하여, 터미널에서 명령 한 줄로 프로젝트를 생성하고, 컨트롤러나 서비스를 추가할 수 있습니다.

이 모든 과정은 자바스크립트 런타임인 Node.js 위에서 돌아가며, 의존성 관리(라이브러리 다운로드)는 NPM (또는 Yarn, PNPM)이라는 패키지 매니저가 담당합니다.

자바의 Maven이나 Gradle과 같은 역할을 한다고 보시면 됩니다.

✅ 사전 설치 항목

IDE: IntelliJ, VSCode, Cursor, Antigravity 등 편한 것으로
Node.js: Node.js 공식 홈페이지에서 LTS 버전을 설치해주세요.

⌨️ NestJS 프로젝트 시작

환경이 준비되었다면, 이제 터미널(혹은 cmd)을 열고 NestJS을 시작 해보겠습니다.

NestJS CLI 설치

$ npm i -g @nestjs/cli

프로젝트 생성

설치가 완료되었다면 nest 명령어를 사용할 수 있습니다. nest new 명령어로 프로젝트를 생성합니다.

$ nest new ${프로젝트 명}
$ nest new nest-crud-app

패키지 매니저 선택

명령어를 실행하면 아래와 같이 어떤 패키지 매니저를 사용할지 물어봅니다.

? Which package manager would you love to use?
  npm
> yarn
  pnpm

특별한 선호가 없다면, npm 을 선택합니다.

spring 으로 치면, Maven vs Gradle 선택과 비슷한 느낌 입니다.

설치 완료 확인

실행한 경로에 프로젝트 명으로 새로운 폴더가 생성되고 내부에 코드가 작성 되어 있음을 확인할 수 있습니다.

🔍 일딴 실행 해보기

다양한 파일들이 생성되었습니다.

eslint.config.mjs, .prettierrc, tsconfig.json, src/main.ts...

모두 알아보기 전에 그냥 한번 실행해보겟습니다.

실행 명령어는, 터미널에 npm run start:dev를 적으시면 됩니다.

이때 반드시, 프로젝트의 루트 경로에서 실행하시기 바랍니다.

$ npm run start:dev

[오후 3:39:58] Starting compilation in watch mode...

[오후 3:40:02] Found 0 errors. Watching for file changes.

[Nest] 23940  - 2026. 02. 15. 오후 3:40:03     LOG [NestFactory] Starting Nest application...
[Nest] 23940  - 2026. 02. 15. 오후 3:40:03     LOG [InstanceLoader] AppModule dependencies initialized +9ms
[Nest] 23940  - 2026. 02. 15. 오후 3:40:03     LOG [RoutesResolver] AppController {/}: +3ms
[Nest] 23940  - 2026. 02. 15. 오후 3:40:03     LOG [RouterExplorer] Mapped {/, GET} route +3ms      
[Nest] 23940  - 2026. 02. 15. 오후 3:40:03     LOG [NestApplication] Nest application successfully started +1ms

명령어는, package.json 의 scripts 항목에서 확인할 수 있습니다.

nest create 를 통해 실행하면 기본적인 Hello World! 를 반환하는 API 를 하나 생성해줍니다.

http://localhost:3000/ 에 접속해 반환값을 확인 해 봅니다.

정상적으로 API 가 생성된 것을 확인할 수 있습니다.

🔍 API 작성해보기 - App 분석(Hello World는 어디서 왔나?)

이제 본격적으로, 우리가 원하는 기능을 만들기 전에 "도대체 왜 localhost:3000에 접속했을 때 Hello World!가 떴는지" 확인해보겠습니다.

기본 생성된 코드를 분석하면 NestJS의 동작 원리가 보입니다.

🏗️ NestJS 의 전체 구조

앞서 언급했듯이, NestJS는 Spring의 MVC 패턴과 계층형 아키텍처를 그대로 가져왔습니다.

Main (main.ts): 프로젝트의 진입점 (SpringApplication.run()과 유사)
Controller (*.controller.ts): 요청을 접수받는 역할 (@RestController)
Service (*.service.ts): 비즈니스 로직을 처리 (@Service)
Repository: DB와 통신하여 데이터를 처리 (@Repository)

이 레이어들이 동일하게 존재하며, 서로 의존성 주입(DI)을 통해 연결됩니다.

DI 란?
Dependency Injection 으로, 의존성을 외부에서 주입하는 패턴입니다.
이로 인해, 테스트의 복잡성 하향, 재사용 성 등이 증가되게 됩니다. (관련 글)

🎮 Controller 분석

컨트롤러는 Request를 받아 Response를 클라이언트에게 반환하는 역할을 합니다.

자동으로 생성된 src/app.controller.ts 파일을 열어보겠습니다.

src/app.controller.ts

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

@Controller()
export class AppController {
  constructor(private readonly appService: AppService) {}

  @Get()
  getHello(): string {
    return this.appService.getHello();
  }
}

1. @Controller()

Spring: @RestController 또는 @Controller
NestJS: 클래스를 컨트롤러로 정의합니다.
- 괄호 안에 경로(Path)를 지정할 수 있습니다.
- 예를 들어 @Controller('users')라고 적으면, 이 클래스의 모든 핸들러는 /users로 시작하는 URL을 처리합니다. 비어있으면 루트(/) 경로입니다.

2. constructor(private readonly appService: AppService)

Spring: 생성자 주입 (@Autowired 생략 가능)
NestJS: 이 부분이 핵심입니다.
- TypeScript의 문법을 활용하여, 생성자의 파라미터에 접근 제한자(private)를 붙이면 자동으로 멤버 변수로 선언되고 주입됩니다.
- 즉, Spring에서 private final AppService appService;를 선언하고 생성자에서 this.appService = appService;를 하는 과정을 단 한 줄로 줄인 것입니다.

3. @Get()

Spring: @GetMapping
NestJS: HTTP GET 요청을 처리합니다.
괄호 안에 상세 경로를 적을 수 있습니다.
- @Get(): GET / 요청 처리
- @Get('profile'): GET /profile 요청 처리

즉, http://localhost:3000/으로 요청이 들어오면 -> @Controller()가 받아서 -> @Get()이 붙은 getHello() 메서드를 실행하고 -> AppService의 로직을 수행한 뒤 결과를 리턴하는 구조입니다.

🧠 Service 분석

컨트롤러가 "요청을 받는 창구"라면, 서비스는 "실제 비즈니스 로직을 수행하는 공장"입니다.

src/app.service.ts 코드를 보겠습니다.

src/app.service.ts

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

@Injectable()
export class AppService {
  getHello(): string {
    return 'Hello World!';
  }
}

코드는 매우 단순하지만, 핵심은 단 하나, 바로 @Injectable() 데코레이터입니다.

1. @Injectable()

Spring: @Service, @Component, @Repository
NestJS: 스프링에서는 클래스 위에 @Service를 붙이면 컴포넌트 스캔을 통해 Bean으로 등록됩니다.
- NestJS에서는 @Injectable()이 붙은 클래스를 Provider라고 부릅니다.
- 이 데코레이터가 있어야 NestJS의 IoC 컨테이너가 이 클래스를 관리하고, 다른 곳(예: Controller)에서 주입받을 수 있게 됩니다.
  참고: Spring처럼 @Service, @Repository 등으로 세분화되어 있지는 않고, 대부분의 비즈니스 로직 클래스는 @Injectable() 하나로 통용됩니다.

2. 비즈니스 로직 (getHello)

Spring: 서비스 메서드
NestJS: 일반적인 TypeScript 클래스 메서드입니다.
- 실제 프로젝트에서는 여기서 DB Repository를 호출하거나, 복잡한 연산을 수행하게 됩니다.
- 지금은 단순히 'Hello World!' 문자열을 리턴하고 있습니다.

전체 흐름 분석

Client가 GET / 요청을 보냄.
Controller (AppController)가 요청을 받음 (@Get()).
Controller는 생성자로 주입받은 Service (AppService)의 getHello()를 호출.
Service는 비즈니스 로직 수행 후 결과('Hello World!') 반환.
Controller가 최종적으로 Client에게 응답.

📦 Module 알아보기

스프링 개발자라면, 저희가 @Service, @Component 로 등록 한 친구들이, @SpringBootApplication 을 통해서, 하위 패키지를 모두 뒤져@ComponentScan)을 진행해서 Bean 으로 등록해주는 걸 알고 있을 것 입니다.

하지만, NestJS 는 컴포넌트 스캔과 같은 기능은 탑재되어 있지 않습니다.

필요한 controllers, providers 들을 일일이 수동으로 등록해줘야 합니다.

일반적인 Service, Repository 등을 모두 providers 라고 부릅니다.

src/app.module.ts

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

@Module({
  imports: [],
  controllers: [AppController],
  providers: [AppService],
})
export class AppModule {}

@Module() 데코레이터 분석

이것은 Spring의 @Configuration 클래스와 비슷하면서도, 역할이 조금 더 구체적입니다.

NestJS는 이 모듈 메타데이터를 이용해 애플리케이션의 구조를 파악합니다.

controllers:
- 이 모듈에서 사용할 컨트롤러들을 정의합니다.
- Spring처럼 패키지에 있다고 자동으로 인식되지 않습니다. 여기 등록하지 않은 컨트롤러는 실행되지 않습니다.

providers:
- Spring의 'Bean'에 해당하는 녀석들(Service, Repository, Factory 등)을 정의합니다.
- AppService에 @Injectable()을 붙였더라도, 이곳 providers 배열에 넣지 않으면 DI 컨테이너가 인식을 못 합니다.

imports:
- 다른 모듈을 가져옵니다.
- Spring에서는 프로젝트 전체가 하나의 거대한 Context라면, NestJS는 기능별(예: UserModule, BoardModule)로 모듈을 나누고, 루트 모듈(AppModule)에서 조립하는 레고 블록 같은 구조를 가집니다.

🤔 왜 이렇게 귀찮게 할까?
Spring 개발자 입장에서는 "그냥 스캔해주면 편할 텐데 왜?"라고 생각할 수 있습니다.
하지만 NestJS는 모듈 단위로 완벽하게 캡슐화하는 것을 지향합니다.
[NestJS 공식 문서 - Modules 중]
"Encapsulation. By default, providers are encapsulated."
(기본적으로 프로바이더는 캡슐화됩니다.)
즉, NestJS는 우리가 귀찮더라도 "누가 누구를 의존하는지"를 명확하게 그래프(Application Graph)로 그리기를 원합니다.
덕분에 프로젝트가 커져도 의존성 꼬임(Spaghetti Code)을 방지하고, 모듈 단위의 테스트와 재사용이 강력해지는 것이죠.
👉 NestJS Modules 공식 문서 바로가기