[Nest.js] Overview - Providers, Modules

프로바이더 (Providers)

 

Nest에서 프로바이더 (Provider)는 핵심 개념입니다. 서비스, 리포지터리, 팩토리, 헬퍼와 같은 기본 Nest 클래스 대부분은 프로바이더로 취급될 수 있습니다. 프로바이더의 핵심 아이디어는 의존성으로 주입될 수 있다는 점이며, 이를 통해 객체들 간에 다양한 관계를 형성할 수 있습니다. 이러한 객체들을 연결(wiring) 하는 작업은 대부분 Nest의 런타임 시스템이 자동으로 처리합니다.

 

이전 장에서는 간단한 CatsController를 만들었습니다. 컨트롤러는 HTTP 요청을 처리하고, 더 복잡한 작업은 프로바이더에게 위임하는 것이 좋습니다. 프로바이더는 NestJS 모듈에서 프로바이더로 선언된 일반 JavaScript 클래스입니다. 자세한 내용은 모듈 (Modules) 장을 참고하세요.

힌트
Nest는 객체 지향 방식으로 의존성을 설계하고 구성할 수 있도록 해주기 때문에, SOLID 원칙을 따르는 것을 강력히 권장합니다.

서비스

이제 간단한 CatsService를 만들어 보겠습니다. 이 서비스는 데이터의 저장 및 조회를 담당하며, CatsController에서 사용될 것입니다. 애플리케이션의 로직을 관리하는 역할을 하기 때문에, 프로바이더로 정의하기에 적합한 대상입니다.

import { Injectable } from '@nestjs/common';
import { Cat } from './interfaces/cat.interface';

@Injectable()
export class CatsService {
  private readonly cats: Cat[] = [];

  create(cat: Cat) {
    this.cats.push(cat);
  }

  findAll(): Cat[] {
    return this.cats;
  }
}

힌트
CLI를 사용하여 서비스를 생성하려면, 다음 명령어를 실행하면 됩니다: nest g service cats

 

CatsService는 하나의 속성과 두 개의 메서드를 가진 기본 클래스입니다. 여기서 핵심은 @Injectable() 데코레이터입니다. 이 데코레이터는 클래스에 메타데이터를 부여하여, Nest의 IoC 컨테이너가 이 클래스를 의존성 주입이 가능한 관리 대상으로 인식하도록 합니다.

 

또한 이 예제는 Cat이라는 인터페이스를 사용하며, 이는 다음과 같은 형태일 가능성이 높습니다:

export interface Cat {
  name: string;
  age: number;
  breed: string;
}

 

이제 고양이 정보를 조회할 수 있는 서비스 클래스가 준비되었으니, 이를 CatsController 안에서 사용해 보겠습니다:

import { Controller, Get, Post, Body } from '@nestjs/common';
import { CreateCatDto } from './dto/create-cat.dto';
import { CatsService } from './cats.service';
import { Cat } from './interfaces/cat.interface';

@Controller('cats')
export class CatsController {
  constructor(private catsService: CatsService) {}

  @Post()
  async create(@Body() createCatDto: CreateCatDto) {
    this.catsService.create(createCatDto);
  }

  @Get()
  async findAll(): Promise<Cat[]> {
    return this.catsService.findAll();
  }
}

 

CatsService는 클래스 생성자를 통해 주입됩니다. 여기서 주목할 점은 private 키워드의 사용입니다. 이 축약형 문법을 사용하면 catsService 멤버를 한 줄에서 선언과 초기화를 동시에 할 수 있어 코드를 간결하게 만들 수 있습니다.

의존성 주입

Nest는 의존성 주입 (Dependency Injection, DI)이라는 강력한 설계 패턴을 중심으로 구축되어 있습니다. 이 개념에 대해서는 Angular 공식 문서의 훌륭한 글을 참고해 보는 것을 적극 추천합니다.

 

Nest에서는 TypeScript의 기능 덕분에 의존성 관리가 매우 간단합니다. 의존성은 타입 기반으로 자동 해결되기 때문입니다. 아래 예제에서는, Nest가 catsService 타입 정보를 바탕으로 CatsService의 인스턴스를 생성하거나 (싱글톤일 경우 이미 생성된 인스턴스를 재사용), 이를 컨트롤러의 생성자에 주입해 줍니다. 또는 지정된 프로퍼티에 할당해 줍니다:

constructor(private catsService: CatsService) {}

스코프

프로바이더는 일반적으로 애플리케이션의 생명주기와 일치하는 수명 (scope)을 가집니다. 애플리케이션이 부트스트랩될 때, 모든 의존성이 해결되어야 하며, 이는 곧 모든 프로바이더가 인스턴스화된다는 뜻입니다. 마찬가지로 애플리케이션이 종료되면 모든 프로바이더도 소멸됩니다. 하지만, 프로바이더를 요청 단위 (request-scoped)로 설정하는 것도 가능합니다. 이 경우 프로바이더의 수명은 애플리케이션 전체가 아닌 특정 요청에 한정됩니다. 이러한 기법에 대한 자세한 내용은 Injection Scopes 장에서 확인할 수 있습니다.

커스텀 프로바이더

Nest에는 제어의 역전 (Inversion of Control, IoC) 컨테이너가 내장되어 있어, 프로바이더 간의 관계를 관리합니다. 이 기능은 의존성 주입의 기반이 되며, 지금까지 설명한 것보다 훨씬 강력한 기능을 제공합니다.

 

Nest에서는 다양한 방식으로 프로바이더를 정의할 수 있습니다. 예를 들어 단순 값 (value), 클래스 (class), 비동기/동기 팩토리 (async/sync factory)로 정의할 수 있습니다. 프로바이더 정의 방식에 대한 더 많은 예제는 Dependency Injection 장에서 확인할 수 있습니다.

선택적 프로바이더

때때로 모든 의존성이 반드시 해결되어야 하는 것은 아닙니다. 예를 들어, 클래스가 설정 객체에 의존하지만 해당 설정이 제공되지 않는 경우 기본값을 사용하도록 하고 싶을 수 있습니다. 이러한 경우 해당 의존성은 선택적 (optional)으로 간주되며, 설정 프로바이더가 없더라도 오류가 발생해서는 안 됩니다.

 

이러한 의존성을 선택적으로 표시하려면 생성자 시그니처에서 @Optional() 데코레이터를 사용하면 됩니다.

import { Injectable, Optional, Inject } from '@nestjs/common';

@Injectable()
export class HttpService<T> {
  constructor(@Optional() @Inject('HTTP_OPTIONS') private httpClient: T) {}
}

 

위 예제에서는 커스텀 프로바이더를 사용하고 있기 때문에 HTTP_OPTIONS라는 커스텀 토큰을 포함시킨 것입니다. 이전 예제들에서는 생성자 기반 주입 방식을 보여주었으며, 이 방식에서는 의존성을 생성자에 클래스 타입으로 명시하여 주입받습니다.

 

커스텀 프로바이더와 해당 토큰이 어떻게 작동하는지에 대한 자세한 내용은 Custom Providers 장을 참고하세요.

속성 기반 주입

지금까지 사용한 방식은 생성자 기반 주입 (Constructor-based Injection)이라고 하며, 프로바이더를 생성자 메서드를 통해 주입하는 방식입니다. 하지만 특정 상황에서는 속성 기반 주입 (Property-based Injection)이 유용할 수 있습니다.

 

예를 들어, 상위 클래스가 하나 이상의 프로바이더에 의존할 때, 하위 클래스에서 이를 super()를 통해 모두 전달하는 것은 번거로울 수 있습니다. 이런 경우에는 @Inject() 데코레이터를 속성 수준에서 직접 사용하여 이를 피할 수 있습니다.

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

@Injectable()
export class HttpService<T> {
  @Inject('HTTP_OPTIONS')
  private readonly httpClient: T;
}

경고
클래스가 다른 클래스를 상속하지 않는 경우에는 일반적으로 생성자 기반 주입을 사용하는 것이 더 좋습니다. 생성자를 통해 어떤 의존성이 필요한지 명확히 드러나므로, @Inject로 속성에 주입하는 방식보다 가독성 및 코드 이해도 측면에서 우수합니다.

프로바이더 등록

CatsService라는 프로바이더와 이를 사용하는 CatsController라는 소비자를 정의했으므로, 이제 Nest에 이 서비스를 등록해야 합니다. 그래야 Nest가 의존성을 해결하고 주입할 수 있습니다. 이를 위해 app.module.ts 파일을 열어 @Module() 데코레이터 안의 providers 배열에 CatsService를 추가합니다.

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

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

 

이제 Nest는 CatsController 클래스의 의존성을 정상적으로 해결할 수 있게 됩니다.

 

현재까지의 디렉터리 구조는 다음과 같아야 합니다:

src/
├── cats/
│   ├── dto/
│   │   └── create-cat.dto.ts
│   ├── interfaces/
│   │   └── cat.interface.ts
│   ├── cats.controller.ts
│   └── cats.service.ts
├── app.module.ts
└── main.ts

수동 설치

지금까지 우리는 Nest가 의존성 해결의 대부분을 자동으로 처리하는 방식을 살펴봤습니다. 그러나 경우에 따라 Nest의 내장 의존성 주입 시스템을 벗어나, 직접 프로바이더 인스턴스를 가져오거나 동적으로 인스턴스를 생성해야 할 수도 있습니다. 아래에 두 가지 주요 기법을 간단히 소개합니다:

• 기존 인스턴스를 조회하거나 프로바이더를 동적으로 인스턴스화하려면 모듈 참조 (Module reference)를 사용할 수 있습니다.
• 애플리케이션 부트스트랩 시점에 프로바이더 (예: 설정 서비스 등)가 필요하다면, bootstrap() 함수 내에서 주입받는 방법을 사용할 수 있습니다. 이는 독립형 애플리케이션 구성 시 유용합니다. (자세한 내용은 Standalone applications 장 참고)

---

모듈 (Modules)

모듈 (Module)은 @Module() 데코레이터가 붙은 클래스입니다. 이 데코레이터는 Nest가 애플리케이션의 구조를 효율적으로 구성하고 관리하기 위해 사용하는 메타데이터를 제공합니다.

모든 Nest 애플리케이션은 최소 하나의 모듈, 즉 루트 모듈을 가지고 있으며, 이는 Nest가 애플리케이션 그래프를 구축하는 시작점 역할을 합니다. 이 그래프는 모듈과 프로바이더 간의 관계 및 의존성을 Nest가 내부적으로 해결하는 데 사용됩니다. 소규모 애플리케이션은 루트 모듈 하나만으로 충분할 수 있지만, 일반적으로는 그렇지 않습니다. Nest에서는 모듈 단위의 구성이 권장되며, 대부분의 애플리케이션은 여러 모듈을 가지고 있고, 각 모듈은 밀접하게 관련된 기능들을 캡슐화합니다.

 

@Module() 데코레이터는 하나의 객체를 인자로 받으며, 이 객체는 모듈을 구성하는 다양한 속성들을 정의합니다.

providers	이 모듈에서 Nest 인젝터에 의해 인스턴스화 될 프로바이더들 (그리고 최소한 이 모듈 내에서 공유될 수 있는 것들)
controllers	이 모듈에 정의된 컨트롤러 집합, Nest가 이들을 인스턴스화 해야 함
imports	이 모듈에서 필요한 프로바이더를 내보내는 (import) 외부 모듈들 목록
exports	이 모듈에서 다른 모듈들이 사용할 수 있도록 내보낼 (export) 프로바이더의 일부 - 프로바이더 자체 또는 해당 토큰 (provide 값) 만을 지정할 수 있음

 

모듈은 기본적으로 프로바이더를 캡슐화합니다. 즉, 현재 모듈의 일부이거나 다른 모듈에서 명시적으로 export 된 프로바이더만 주입할 수 있습니다. 모듈에서 export 된 프로바이더는 해당 모듈의 공개 인터페이스 (API) 역할을 하며, 다른 모듈이 이 모듈과 상호작용할 수 있도록 합니다.

기능 모듈 (Feature Modules)

예제에서 CatsController와 CatsService는 밀접한 관계를 가지며 동일한 도메인을 담당합니다. 따라서 이 둘을 하나의 기능 모듈 (feature module)로 묶는 것이 타당합니다. 기능 모듈은 특정 기능과 관련된 코드를 조직화하며, 명확한 경계와 더 나은 구조를 유지하는 데 도움이 됩니다. 이는 애플리케이션이나 팀 규모가 커질수록 더욱 중요해지며, SOLID 원칙과도 잘 부합합니다.

 

이제 CatsModule을 생성하여 컨트롤러와 서비스를 어떻게 묶는지 살펴보겠습니다.

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

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

힌트
CLI를 사용하여 모듈을 생성하려면, 다음 명령어를 실행하면 됩니다: nest g module cats

 

위에서는 cats.module.ts 파일에서 CatsModule을 정의하고, 이 모듈과 관련된 모든 파일을 cats 디렉터리로 이동시켰습니다. 이제 마지막으로 해야 할 일은, 이 CatsModule을 루트 모듈 (AppModule)에 import 하는 것입니다. AppModule은 app.module.ts 파일에 정의되어 있습니다.

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

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

 

현재 디렉터리 구조는 다음과 같습니다:

src/
├── cats/
│   ├── dto/
│   │   └── create-cat.dto.ts
│   ├── interfaces/
│   │   └── cat.interface.ts
│   ├── cats.controller.ts
│   ├── cats.module.ts
│   └── cats.service.ts
├── app.module.ts
└── main.ts

공유 모듈

Nest에서는 모듈이 기본적으로 싱글톤 (singleton)으로 동작하므로, 여러 모듈 간에 동일한 프로바이더 인스턴스를 별다른 설정 없이 쉽게 공유할 수 있습니다.

모든 모듈은 자동적으로 공유 모듈 (shared module)입니다. 한 번 생성된 모든 모듈은 다른 어떤 모듈에서도 재사용할 수 있습니다. 예를 들어, CatsService 인스턴스를 여러 다른 모듈에서 공유하고자 한다면, 먼저 해당 프로바이더를 exports 배열에 추가하여 export 해야 합니다. 아래와 같이 설정합니다:

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

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

 

이제 CatsModule을 import 하는 어느 모듈에서든 CatsService에 접근할 수 있으며, 이 서비스는 다른 모든 모듈과 동일한 인스턴스를 공유하게 됩니다.

 

만약 CatsService를 필요한 각 모듈에 직접 등록한다면, 서비스는 작동하긴 하지만 모듈마다 별도의 인스턴스가 생성됩니다. 이렇게 되면 같은 서비스를 여러 번 생성하게 되어 메모리 사용량이 증가할 수 있으며, 내부 상태를 유지하는 서비스의 경우 상태 불일치와 같은 예기치 않은 동작이 발생할 수 있습니다.

 

CatsService를 CatsModule이라는 모듈 안에 캡슐화하고 exports를 통해 외부로 내보냄으로써, 이 모듈을 가져다 쓰는 모든 곳에서 동일한 인스턴스를 재사용하게 됩니다. 이 방식은 메모리 사용을 줄이고, 모듈 간 동작을 예측 가능하게 하며, 공유 상태나 리소스를 일관되게 관리할 수 있도록 도와줍니다.

 

이는 NestJS와 같은 프레임워크의 모듈화와 의존성 주입 (DI)이 제공하는 핵심 장점 중 하나로, 서비스들을 애플리케이션 전반에 걸쳐 효율적으로 공유할 수 있게 해 줍니다.

모듈 재 내보내기 (Module re-exporting)

앞서 본 것처럼, 모듈은 내부의 프로바이더를 export 할 수 있습니다. 더불어, import 한 다른 모듈을 다시 export 하여 외부로 전달할 수도 있습니다. 예를 들어 아래와 같이 CoreModule이 CommonModule을 import 하고 동시에 export 하면, CoreModule을 import 하는 다른 모듈들에서도 별도로 CommonModule을 import 하지 않아도 해당 기능을 사용할 수 있게 됩니다.

@Module({
  imports: [CommonModule],
  exports: [CommonModule],
})
export class CoreModule {}

의존성 주입

모듈 클래스에서도 프로바이더를 주입받을 수 있습니다 (예: 설정 값을 사용하기 위해).

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

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

 

하지만 모듈 클래스 자체는 순환 의존성 (circular dependency) 때문에 프로바이더로 주입될 수는 없습니다.

 

전역 모듈

어디에서든 동일한 모듈 집합을 반복적으로 import 해야 한다면, 이는 번거로울 수 있습니다. Angular와는 달리, Nest에서는 프로바이더가 전역 범위가 아닌 모듈 범위에 등록됩니다. 즉, Nest에서는 어떤 모듈의 프로바이더를 사용하려면, 먼저 해당 모듈을 import 해야 사용할 수 있습니다.

 

헬퍼, 데이터베이스 커넥션 등과 같이 애플리케이션 전역에서 기본적으로 사용되어야 하는 프로바이더 집합을 제공하고 싶다면, 해당 모듈에 @Global() 데코레이터를 붙여 전역 모듈 (Global Module)로 만들어야 합니다.

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

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

 

@Global() 데코레이터는 해당 모듈을 전역 범위 (Global scope)로 만듭니다. 전역 모듈은 일반적으로 루트 모듈이나 코어 모듈에서 단 한 번만 등록되어야 합니다. 위 예시에서처럼 CatsService가 전역 모듈로 제공되면, 이를 사용하려는 다른 모듈들은 CatsModule을 imports 배열에 명시할 필요 없이 바로 주입받아 사용할 수 있습니다.

 

힌트
모든 것을 전역으로 만드는 것은 바람직한 설계 방식이 아닙니다. 전역 모듈은 보일러플레이트를 줄이는 데 도움이 될 수는 있지만, 일반적으로는 imports 배열을 통해 명시적으로 모듈의 API를 공유하는 방식이 구조적이고 유지보수에 유리합니다. 이 방식은 필요한 구성요소에만 공유하도록 하며, 애플리케이션 내의 불필요한 결합도를 방지하는 데 도움이 됩니다.

 

동적 모듈

Nest의 동적 모듈 (Dynamic Module)은 런타임에 모듈을 구성할 수 있도록 해줍니다. 이는 특정 옵션이나 설정에 따라 유연하고 사용자 정의 가능한 모듈을 생성해야 할 때 특히 유용합니다. 아래는 동적 모듈이 작동하는 방식에 대한 간단한 개요입니다.

import { Module, DynamicModule } from '@nestjs/common';
import { createDatabaseProviders } from './database.providers';
import { Connection } from './connection.provider';

@Module({
  providers: [Connection],
  exports: [Connection],
})
export class DatabaseModule {
  static forRoot(entities = [], options?): DynamicModule {
    const providers = createDatabaseProviders(options, entities);
    return {
      module: DatabaseModule,
      providers: providers,
      exports: providers,
    };
  }
}

힌트
forRoot() 메서드는 동적 모듈을 동기적으로 또는 비동기 (Promise 기반)로 반환할 수 있습니다.

 

이 모듈은 기본적으로 @Module() 데코레이터의 메타데이터에 정의된 Connection 프로바이더를 제공합니다. 하지만 forRoot() 메서드에 전달된 entities와 options 객체에 따라, 리포지터리와 같은 추가적인 프로바이더 집합도 함께 노출합니다. 동적 모듈이 반환하는 속성들은 기본 모듈의 메타데이터를 덮어쓰지 않고 확장합니다. 이 방식 덕분에, 정적으로 선언된 Connection 프로바이더와 동적으로 생성된 리포지터리 프로바이더들을 모두 해당 모듈에서 export 할 수 있습니다.

 

전역 범위에서 동적 모듈을 등록하고 싶다면, 반환 객체의 global 속성을 true로 설정하세요.

{
  global: true,
  module: DatabaseModule,
  providers: providers,
  exports: providers,
}

주의
앞서 언급했듯이, 모든 것을 전역으로 만드는 것은 바람직한 설계 방식이 아닙니다.

 

DatabaseModule은 다음과 같은 방식으로 import 및 설정할 수 있습니다:

import { Module } from '@nestjs/common';
import { DatabaseModule } from './database/database.module';
import { User } from './users/entities/user.entity';

@Module({
  imports: [DatabaseModule.forRoot([User])],
})
export class AppModule {}

 

동적 모듈을 다시 re-export (재내보내기) 하려면, exports 배열에서 forRoot() 메서드를 호출하지 않고 모듈 자체만 나열하면 됩니다.

import { Module } from '@nestjs/common';
import { DatabaseModule } from './database/database.module';
import { User } from './users/entities/user.entity';

@Module({
  imports: [DatabaseModule.forRoot([User])],
  exports: [DatabaseModule],
})
export class AppModule {}

 

이 주제는 Dynamic Modules 장에서 더 자세히 다루고 있으며, 작동하는 예제도 함께 포함되어 있습니다.

힌트
이 장에서는 ConfigurableModuleBuilder를 사용하여 높은 수준의 사용자 정의가 가능한 동적 모듈을 구축하는 방법도 배울 수 있습니다.

 

Reference

• Nest.js | Providers
• Nest.js | Modules