기술과 산업/언어 및 프레임워크

NestJS 마스터 시리즈 3화. 모듈 시스템 이해하기 – 구조는 결국 모듈에서 시작된다

B컷개발자 2025. 4. 26. 18:00
728x90

“Nest를 Nest답게 만드는 것, 바로 모듈이다”

 

NestJS의 핵심 철학인 모듈 시스템을 실무 관점에서 해부합니다. 기능 단위 설계, 의존성 주입, 루트 모듈 구성부터 feature 모듈 분리 전략까지 실전 예제로 설명합니다.

 


 

🧱 NestJS의 구조적 사고는 ‘모듈’에서 시작된다

 

NestJS는 Express와 다르게 처음부터 모듈 단위 설계를 강제합니다.

이는 규모가 커질수록 코드 정돈, 의존성 관리, 테스트, 협업 모든 측면에서 이점을 가집니다.

 

“Nest에서 모듈은 단순한 폴더가 아니라, 독립된 기능 단위의 ‘컨텍스트(Context)’다.”

 


 

🔍 모듈이란?

 

모듈은 NestJS 애플리케이션을 구성하는 기본 단위입니다.

@Module() 데코레이터를 사용하며, 내부에 다음 네 가지 항목을 가질 수 있습니다:

@Module({
  imports: [],         // 다른 모듈 가져오기
  controllers: [],     // 요청 처리 컨트롤러
  providers: [],       // 서비스 등 의존성 주입 객체
  exports: []          // 외부 모듈에 제공할 객체
})

 

 


 

✨ 루트 모듈 vs 기능 모듈

 

 

📌 루트 모듈 (AppModule)

 

NestJS 앱을 부트스트랩하는 메인 모듈로, 최상위 엔트리포인트입니다.

main.ts에서 이 모듈을 불러와 애플리케이션을 실행합니다.

 

 

📦 기능 모듈 (Feature Modules)

 

기능별, 도메인별로 나누는 서브 모듈입니다. 예: UserModule, AuthModule, ProductModule 등.

 

이 모듈들을 AppModule에 연결해 전체 앱을 구성합니다.

 


 

🛠 실전 예제 – 

UserModule

 만들기

 

 

1. 명령어로 자동 생성

nest generate module users
nest generate controller users
nest generate service users

 

2. 파일 구조

src/
  └── users/
      ├── users.controller.ts
      ├── users.service.ts
      ├── users.module.ts

 

3. 

users.module.ts

@Module({
  controllers: [UsersController],
  providers: [UsersService],
  exports: [UsersService],  // 필요시 외부에 공개
})
export class UsersModule {}

 

4. 

app.module.ts

에서 import

import { Module } from '@nestjs/common';
import { UsersModule } from './users/users.module';

@Module({
  imports: [UsersModule],
})
export class AppModule {}

이제 UsersControllerUsersService는 AppModule 전체에서 사용할 수 있습니다.

 


 

🧩 모듈 분리 전략 – 실무에서 이렇게 씁니다

분리 기준예시설명

도메인 기준 User, Product, Order DDD 스타일 구성에 적합
기능 기준 Auth, FileUpload, Notification 공통 기능성 컴포넌트 관리에 적합
외부 연동 기준 DatabaseModule, RedisModule 설정 및 외부 서비스 모듈화
보통 도메인 중심 + 기능 기반을 혼합한 하이브리드 전략이 실무에서 많이 쓰입니다.

 


 

💡 마무리 인사이트

 

NestJS의 모듈은 단순한 폴더 구조가 아니라 프로젝트의 설계 철학을 결정짓는 핵심 단위입니다.

 

  • 모듈이 잘 나눠지면 서비스가 잘 유지됩니다.
  • 모듈이 뒤엉키면 유지보수보다 리팩터링이 먼저 걱정됩니다.

 

NestJS를 제대로 활용하고 싶다면, 컨트롤러나 서비스보다 먼저 모듈을 설계하는 습관을 들이세요.

 


 

📎 다음 회차 예고

 

👉 4화. 컨트롤러와 라우팅 – REST API를 구조화하는 방법

 

GET, POST만 알면 되는 게 아닙니다. 컨트롤러 구조 설계가 서비스 품질을 좌우합니다.

 

728x90