🧩 NestJS Module 완전 이해 – 구조적 백엔드 설계의 출발점

🧩 NestJS Module 완전 이해 – 구조적 백엔드 설계의 출발점

---

NestJS에서 **Module(모듈)**은 애플리케이션을 기능 단위로 구성하는 핵심 구조 단위입니다.
NestJS 공식 문서의 Modules를 기반으로 한글 번역과 함께, 실무에 필요한 구조 설계 방법까지 해설합니다.

NestJS에서 모든 것은 모듈로 시작되고, 모듈로 구성됩니다.
유지보수성과 확장성을 극대화하려면 모듈 설계부터 잘해야 합니다.

---

✅ NestJS에서 Module이란?

NestJS는 구조적 백엔드 설계를 지향하기 때문에, 각 기능별로 Controller, Service, DTO 등을 묶어 모듈로 분리합니다.

모든 Nest 애플리케이션은 **최소한 하나의 루트 모듈(AppModule)**을 포함해야 하며, 추가 기능은 **서브 모듈(SubModule)**로 분리할 수 있습니다.

---

1️⃣ 기본 Module 구조

import { Module } from '@nestjs/common';
import { CatsController } from './cats.controller';
import { CatsService } from './cats.service';

@Module({
  controllers: [CatsController],
  providers: [CatsService],
})
export class CatsModule {}

핵심 포인트:

• controllers: 라우팅을 처리하는 클래스
• providers: 서비스, 헬퍼, 유틸 등 주입 가능한 객체
• imports: 다른 모듈을 가져올 때
• exports: 외부에 노출할 provider/service

---

2️⃣ AppModule 구성 예시

반응형

import { Module } from '@nestjs/common';
import { CatsModule } from './cats/cats.module';

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

모든 기능은 AppModule에서 가져와서 조립합니다.
즉, AppModule은 프로젝트의 루트 조립공장 같은 역할을 합니다.

---

📦 CLI로 모듈 생성하기

nest g module cats

Nest CLI를 사용하면 자동으로 폴더와 파일이 정리된 상태로 생성됩니다.

src/
  cats/
    cats.module.ts ✅
    cats.controller.ts
    cats.service.ts

구조화된 모듈 단위 개발을 강제하므로 대규모 팀 프로젝트에서 강력한 유지보수 이점을 제공합니다.

---

📺 광고

이 구간은 모듈 개념이 완전히 정리되는 시점으로, 블로그에 애드센스 광고를 삽입하면 클릭률이 높습니다.

<ins class="adsbygoogle"
     style="display:block"
     data-ad-client="ca-pub-XXXX"
     data-ad-slot="YYYY"
     data-ad-format="auto"
     data-full-width-responsive="true"></ins>

---

3️⃣ 모듈 간 의존성 연결 – imports & exports

모듈은 자체적으로 격리되어 있지만, 다른 모듈과 연결해야 할 때는 imports와 exports를 사용합니다.

@Module({
  providers: [CatsService],
  exports: [CatsService],
})
export class CatsModule {}

@Module({
  imports: [CatsModule],
})
export class DogsModule {}

• CatsModule은 CatsService를 외부에 exports 하였고
• DogsModule은 CatsModule을 imports 하여 사용 가능

---

4️⃣ Global Module – 전역 모듈 만들기

모든 모듈에 동일한 서비스를 주입하고 싶다면 @Global() 데코레이터를 사용합니다.

@Global()
@Module({
  providers: [ConfigService],
  exports: [ConfigService],
})
export class ConfigModule {}

이렇게 하면 ConfigService를 모든 모듈에서 imports 없이도 바로 사용할 수 있습니다.

주의: 남용하면 모듈 간 의존성이 애매해져서 테스트와 유지보수에 어려움이 생깁니다.

---

5️⃣ Dynamic Module – 동적으로 구성되는 모듈

@Module({})
export class ConfigModule {
  static register(options: ConfigOptions): DynamicModule {
    return {
      module: ConfigModule,
      providers: [{ provide: 'CONFIG_OPTIONS', useValue: options }],
      exports: ['CONFIG_OPTIONS'],
    };
  }
}

register()를 통해 런타임에 모듈 설정 값을 외부에서 주입할 수 있는 유연한 구조를 제공합니다.

실무에서 DatabaseModule, CacheModule, MailModule 등을 구성할 때 자주 사용됩니다.

---

✅ 실무 설계 전략: 기능 단위로 모듈을 나누자

모듈명 포함 내용

UserModule	user.controller.ts, user.service.ts, user.repository.ts
AuthModule	로그인, 인증 관련 로직 및 Strategy
PostModule	게시물 작성/조회 서비스
CommonModule	재사용 가능한 유틸, DTO, 필터, 인터셉터 등

하나의 폴더에 모든 코드를 몰아넣는 설계는 장기적으로 큰 유지보수 비용을 초래합니다.

---

🧠 마무리 정리

개념 설명

@Module	모듈 정의 데코레이터
controllers	HTTP 요청을 처리
providers	서비스, 헬퍼 등을 정의
imports	다른 모듈을 연결
exports	외부 모듈에서 사용할 provider 공개
@Global()	전역에서 한 번만 설정하여 사용
register()	동적 구성 모듈 패턴

---

 

NestJS Module,NestJS 모듈 구조,NestJS imports exports,NestJS 글로벌 모듈,NestJS 설계,NestJS register,Dynamic Module,NestJS 구조화,Node.js 백엔드,서비스 분리 설계