[Nest.js] Fundamentals - Dynamic modules, Injection scopes

동적 모듈 (Dynamic modules)

모듈 장에서는 Nest 모듈의 기본 개념과 동적 모듈에 대한 간단한 소개를 다룹니다. 이 장에서는 동적 모듈의 주제를 확장하여 설명합니다. 이 장을 마치면 동적 모듈이 무엇이며, 이를 어떻게 그리고 언제 사용해야 하는지를 잘 이해할 수 있게 됩니다.

소개

문서의 Overview 섹션에 있는 대부분의 애플리케이션 코드 예제는 일반적인, 즉 정적 모듈을 사용합니다. 모듈은 전체 애플리케이션의 모듈화 된 일부로써 함께 동작하는 프로바이더나 컨트롤러 같은 컴포넌트 그룹을 정의합니다. 모듈은 이러한 컴포넌트에 대한 실행 컨텍스트 (또는 스코프)를 제공합니다. 예를 들어, 모듈 안에 정의된 프로바이더는 해당 모듈의 다른 구성원에게는 export 없이도 접근할 수 있습니다. 반면, 어떤 프로바이더가 모듈 외부에서도 보이도록 하려면, 먼저 그것을 해당 모듈에서 export 한 후, 이를 사용하는 모듈에서 import 해야 합니다.

 

익숙한 예제를 통해 살펴보겠습니다.

 

먼저, UsersService를 제공하고 export 하는 UsersModule을 정의합니다. UsersModule은 UsersService의 호스트 모듈입니다.

import { Module } from '@nestjs/common';
import { UsersService } from './users.service';

@Module({
  providers: [UsersService],
  exports: [UsersService],
})
export class UsersModule {}

 

다음으로 AuthModule을 정의합니다. 이 모듈은 UsersModule을 import 하여, UsersModule에서 export 한 프로바이더들을 AuthModule 내에서 사용할 수 있게 합니다.

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

@Module({
  imports: [UsersModule],
  providers: [AuthService],
  exports: [AuthService],
})
export class AuthModule {}

 

이러한 구성 덕분에, 예를 들어 AuthModule에 속한 AuthService에서 UsersService를 주입할 수 있습니다.

@Injectable()
export class AuthService {
  constructor(private usersService: UsersService) {}
  /*
    this.usersService를 활용하는 구현부
  */
}

 

이를 "정적 모듈 바인딩 (static module binding)"이라고 부릅니다. Nest가 모듈들을 연결하는 데 필요한 모든 정보는 이미 호스트 모듈과 소비 모듈에 선언되어 있습니다. 이 과정에서 무슨 일이 일어나는지 하나씩 살펴보겠습니다. Nest는 다음과 같은 방식으로 UsersService를 AuthModule 내에서 사용할 수 있게 합니다:

1. UsersModule을 인스턴스화합니다. 이때 UsersModule이 사용하는 다른 모듈들도 전이적으로 import 되며, 모든 의존성도 전이적으로 해결됩니다 (자세한 내용은 Custom providers 참고).
2. AuthModule을 인스턴스화하고, UsersModule에서 export 한 프로바이더들을 AuthModule 내의 컴포넌트들이 사용할 수 있도록 만듭니다 (마치 AuthModule 내에서 직접 선언된 것처럼 동작합니다).
3. UsersService의 인스턴스를 AuthService에 주입합니다.

동적 모듈 사용 사례

정적 모듈 바인딩 방식에서는, 소비 모듈이 호스트 모듈의 프로바이더 구성 방식에 영향을 줄 수 있는 방법이 없습니다. 그런데 이것이 왜 중요할까요? 어떤 모듈이 일반적인 목적을 가지고 있고, 다양한 상황에 따라 다르게 동작해야 하는 경우를 생각해 봅시다. 이는 많은 시스템에서의 "플러그인" 개념과 유사한데, 일반적인 기능을 사용하기 전에 소비자가 특정 구성을 지정해줘야 한다는 점에서 그렇습니다.

 

Nest에서 대표적인 예는 구성 (configuration) 모듈입니다. 많은 애플리케이션에서 구성 정보를 외부화하기 위해 구성 모듈을 사용하는 것이 유용합니다. 이렇게 하면 서로 다른 배포 환경에서 설정을 쉽게 바꿀 수 있습니다. 예를 들어 개발자용 개발 DB, 스테이징/테스트 환경용 DB 등입니다. 구성 파라미터 관리를 구성 모듈에 위임하면, 애플리케이션의 소스 코드는 구성 세부사항과 분리되어 독립성을 유지할 수 있습니다.

 

하지만 문제는 구성 모듈 자체가 일반적(generic)인 구조이기 때문에, 이를 사용하는 모듈에서 구체적인 설정을 지정해줘야 한다는 점입니다. 이때 동적 모듈이 등장합니다. 동적 모듈 기능을 활용하면, 구성 모듈을 동적으로 만들어 소비 모듈이 해당 모듈을 import 할 때 어떤 방식으로 구성할지를 API를 통해 제어할 수 있습니다.

 

즉, 동적 모듈은 한 모듈을 다른 모듈에 import 하면서 그 import 시점에 해당 모듈의 속성과 동작을 커스터마이즈할 수 있는 API를 제공합니다. 이는 지금까지 봐온 정적 바인딩 방식과는 다른 접근 방식입니다.

Config 모듈 예제

이 섹션에서는 구성 챕터 (configuration chapter)에서 사용한 예제 코드의 기본 버전을 사용할 것입니다. 이 장의 마지막까지 완성된 버전은 작동하는 예제로 별도로 제공됩니다.

 

지금 우리가 구현하고자 하는 요구사항은 ConfigModule이 사용자 정의 옵션 객체 (options object)를 받아서 구성될 수 있도록 하는 것입니다. 현재의 기본 예제는 .env 파일의 위치를 프로젝트 루트 폴더에 고정해두고 있습니다. 하지만 우리는 이 위치를 유연하게 설정 가능하게 만들고자 합니다. 예를 들어, 여러 개의 .env 파일을 프로젝트 루트 하위의 config 폴더 (예: src와 같은 레벨)에 저장하고자 할 수 있습니다. 그리고 서로 다른 프로젝트마다 ConfigModule을 사용할 때 다른 폴더를 선택할 수 있도록 하고 싶습니다.

 

동적 모듈 (dynamic modules)은 import 하는 모듈에 매개변수를 전달해서 그 동작을 변경할 수 있는 기능을 제공합니다. 이제 이것이 어떻게 작동하는지 살펴보겠습니다.

 

먼저, 소비자 모듈의 입장에서 최종적으로 어떤 코드가 될지를 먼저 상상해 보고, 그 뒤에 내부 구현을 역으로 따라가는 것이 도움이 됩니다.

 

우선, 정적으로 ConfigModule을 import 하는 예제를 간단히 리뷰해 보겠습니다. (즉, 가져온 모듈의 동작을 제어할 수 없는 기존 방식입니다.) @Module() 데코레이터의 imports 배열을 잘 봐야 합니다:

@Module({
  imports: [DogsModule],
  controllers: [CatsController],
  providers: [CatsService],
  exports: [CatsService]
})

 

동적 모듈은 기존 정적 모듈과 동일한 인터페이스 형태의 객체를 반환해야 하며, 여기에 module이라는 속성 하나가 추가로 포함되어야 합니다. 이 module 속성은 모듈의 이름 역할을 하며, 아래 예제에서처럼 모듈 클래스 이름과 동일해야 합니다.

힌트
동적 모듈에서 옵션 객체의 모든 속성은 module을 제외하고 선택 사항 (optional)입니다.

 

그렇다면 register()라는 정적 (static) 메서드는 어떤 역할을 할까요? 이제 우리는 이 메서드가 DynamicModule 인터페이스를 따르는 객체를 반환하는 역할을 한다는 것을 알 수 있습니다. 이 메서드를 호출하면, 정적 방식에서 모듈 클래스 이름을 imports에 직접 나열하는 것과 유사하게, 해당 모듈을 imports 배열에 제공하게 됩니다. 즉, 동적 모듈 API는 단순히 모듈을 반환하는 것인데, @Module 데코레이터 안에서 속성을 고정해서 설정하는 대신, 프로그래밍 방식으로 설정값을 지정한다는 점만 다릅니다.

 

전체 개념을 완성하기 위해 몇 가지 세부사항을 더 알아둘 필요가 있습니다:

1. 이제 @Module() 데코레이터의 imports 속성에는 모듈 클래스 이름 (예: imports: [UsersModule]) 뿐만 아니라, 동적 모듈을 반환하는 함수 (예: imports: [ConfigModule.register(...)])도 전달할 수 있다는 사실을 명확히 알 수 있습니다.
2. 동적 모듈도 자체적으로 다른 모듈들을 import 할 수 있습니다. 이 예제에서는 그렇게 하진 않겠지만, 동적 모듈이 다른 모듈의 프로바이더에 의존하는 경우, imports 속성을 사용하여 해당 모듈들을 가져와야 합니다. 이는 정적 모듈에서 @Module() 데코레이터를 사용할 때 메타데이터를 선언하는 방식과 완전히 동일합니다.

이제 이러한 개념을 바탕으로, 우리가 만들고자 하는 동적 ConfigModule 선언이 어떤 모습이어야 할지 살펴볼 수 있게 되었습니다. 직접 구현해 봅시다.

import { DynamicModule, Module } from '@nestjs/common';
import { ConfigService } from './config.service';

@Module({})
export class ConfigModule {
  static register(): DynamicModule {
    return {
      module: ConfigModule,
      providers: [ConfigService],
      exports: [ConfigService],
    };
  }
}

 

이제 각 요소들이 어떻게 맞물려 동작하는지 분명해졌을 것입니다. ConfigModule.register(...)를 호출하면, 지금까지 @Module() 데코레이터를 통해 메타데이터로 제공하던 속성들과 본질적으로 동일한 속성들을 가진 DynamicModule 객체를 반환합니다.

힌트
DynamicModule은 @nestjs/common에서 임포트 할 수 있습니다.

 

하지만 현재 우리의 동적 모듈은 아직 그다지 흥미롭지 않습니다. 앞서 말했듯이 구성 가능하도록 만들겠다는 목적을 아직 구현하지 않았기 때문입니다. 이제 그 부분을 다뤄보겠습니다.

모듈 구성

ConfigModule의 동작을 커스터마이즈하는 가장 명확한 방법은, 앞서 예상했듯이 정적 register() 메서드에 옵션 객체 (options object)를 전달하는 것입니다. 다시 한번, 소비자 모듈의 imports 속성을 살펴보겠습니다:

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

@Module({
  imports: [ConfigModule.register({ folder: './config' })],
  controllers: [AppController],
  providers: [AppService],
})
export class AppModule {}

 

이제 옵션 객체를 동적 모듈에 전달하는 방법은 마련되었습니다. 그렇다면 이 옵션 객체를 ConfigModule 안에서 어떻게 사용할 수 있을까요? 잠시 생각해 봅시다. 우리는 ConfigModule이 결국 주입 가능한 서비스인 ConfigService를 제공하고 export 하는 호스트 역할을 한다는 걸 알고 있습니다. 그리고 실제로는 이 ConfigService가 전달된 옵션 객체를 읽어 들여, 자신의 동작을 커스터마이즈 해야 합니다. 일단 지금은, register() 메서드에서 전달된 옵션을 어떻게 ConfigService까지 전달할지는 아직 구현하지 않았다고 가정하고, 옵션 객체의 속성에 따라 동작을 변경하는 식으로 ConfigService를 일부 수정해 보겠습니다. (참고: 현재는 옵션 전달이 구현되지 않았으므로, 일단은 하드코딩된 옵션 값을 사용하는 방식으로 작성하고, 곧이어 이를 고쳐나갈 것입니다.)

import { Injectable } from '@nestjs/common';
import * as dotenv from 'dotenv';
import * as fs from 'fs';
import * as path from 'path';
import { EnvConfig } from './interfaces';

@Injectable()
export class ConfigService {
  private readonly envConfig: EnvConfig;

  constructor() {
    const options = { folder: './config' };

    const filePath = `${process.env.NODE_ENV || 'development'}.env`;
    const envFile = path.resolve(__dirname, '../../', options.folder, filePath);
    this.envConfig = dotenv.parse(fs.readFileSync(envFile));
  }

  get(key: string): string {
    return this.envConfig[key];
  }
}

 

이제 ConfigService는 options에서 지정한 폴더 경로를 사용해 .env 파일을 찾을 수 있게 되었습니다.

 

이제 남은 과제는, register() 단계에서 전달된 options 객체를 ConfigService에 주입하는 것입니다. 물론 이 작업은 "의존성 주입 (Dependency Injection)"을 통해 수행합니다. 이 점은 매우 중요하므로 확실히 이해해야 합니다. 지금 우리는 ConfigModule을 통해 ConfigService를 제공하고 있습니다. 그리고 이 ConfigService는 런타임에만 전달되는 options 객체를 필요로 합니다. 즉, 실행 시점에 options 객체를 먼저 Nest의 IoC 컨테이너에 바인딩하고, 그 후 Nest가 이 객체를 ConfigService에 주입하도록 만들어야 합니다. Custom Providers 장에서 배운 것처럼, Nest의 provider는 서비스뿐 아니라 단순한 값도 포함할 수 있으므로 이러한 방식으로 options 객체를 주입하는 데는 문제가 없습니다.

 

먼저 options 객체를 IoC 컨테이너에 바인딩하는 방법부터 살펴보겠습니다. 이 작업은 정적 register() 메서드 안에서 수행합니다. 우리는 현재 동적으로 모듈을 구성하고 있으며, 모듈의 주요 구성 요소 중 하나는 providers입니다. 따라서 해야 할 일은 options 객체를 provider로 정의하는 것입니다. 이렇게 하면 이후 단계에서 ConfigService 안에 options 객체를 주입할 수 있게 됩니다. 아래 코드에서 providers 배열을 주의 깊게 살펴보세요:

import { DynamicModule, Module } from '@nestjs/common';
import { ConfigService } from './config.service';

@Module({})
export class ConfigModule {
  static register(options: Record<string, any>): DynamicModule {
    return {
      module: ConfigModule,
      providers: [
        {
          provide: 'CONFIG_OPTIONS',
          useValue: options,
        },
        ConfigService,
      ],
      exports: [ConfigService],
    };
  }
}

 

이제 'CONFIG_OPTIONS' 프로바이더를 ConfigService에 주입함으로써 이 과정을 완전히 마무리할 수 있습니다. 클래스가 아닌 문자열 토큰으로 프로바이더를 정의한 경우에는, 여기에서 설명한 것처럼 반드시 @Inject() 데코레이터를 사용해야 한다는 점을 기억하세요.

import * as dotenv from 'dotenv';
import * as fs from 'fs';
import * as path from 'path';
import { Injectable, Inject } from '@nestjs/common';
import { EnvConfig } from './interfaces';

@Injectable()
export class ConfigService {
  private readonly envConfig: EnvConfig;

  constructor(@Inject('CONFIG_OPTIONS') private options: Record<string, any>) {
    const filePath = `${process.env.NODE_ENV || 'development'}.env`;
    const envFile = path.resolve(__dirname, '../../', options.folder, filePath);
    this.envConfig = dotenv.parse(fs.readFileSync(envFile));
  }

  get(key: string): string {
    return this.envConfig[key];
  }
}

 

마지막으로 한 가지 덧붙이자면, 위 예제에서는 단순화를 위해 문자열 기반의 주입 토큰 ('CONFIG_OPTIONS')을 사용했지만, 권장되는 방식은 이 토큰을 별도의 파일에서 상수(또는 Symbol)로 정의하고 import 해서 사용하는 것입니다. 예를 들면 다음과 같습니다:

export const CONFIG_OPTIONS = 'CONFIG_OPTIONS';

예제

이 장의 전체 코드 예제는 여기에서 확인할 수 있습니다.

커뮤니티 가이드라인

@nestjs/packages에서 forRoot, register, forFeature 같은 메서드들을 사용하는 예시를 보셨을 수도 있습니다. 이 메서드들이 정확히 어떤 차이를 가지는지 궁금할 수 있는데요, 엄격한 규칙이 있는 것은 아니지만, Nest의 공식 패키지들은 다음과 같은 관례적인 가이드라인을 따릅니다:

 

모듈을 생성할 때:

• register를 사용할 경우, 호출하는 모듈에서만 사용되는 특정 설정으로 동적 모듈을 구성하는 것을 기대합니다. 예를 들어, @nestjs/axios에서: HttpModule.register({ baseUrl: 'someUrl' }). 만약 다른 모듈에서 HttpModule.register({ baseUrl: 'somewhere else' })를 사용하면, 다른 설정을 갖게 됩니다. 원하는 만큼의 모듈에 대해 이 작업을 수행할 수 있습니다.
• forRoot를 사용할 경우, 하나의 설정으로 동적 모듈을 구성하고 이 설정을 여러 곳에서 재사용하는 것을 기대합니다 (때때로 이 설정은 추상화되어 있어서 인지하지 못한 채로 재사용되기도 합니다). 이 때문에 GraphQLModule.forRoot(), TypeOrmModule.forRoot()와 같은 방식이 사용됩니다.
• forFeature를 사용할 경우, 동적 모듈의 forRoot 설정을 기반으로 하되, 호출하는 모듈의 요구사항에 따라 일부 설정을 수정하려는 경우입니다 (예: 이 모듈이 어떤 레포지터리에 접근해야 하는지, 혹은 로거가 어떤 컨텍스트를 사용해야 하는지 등).

이 메서드들은 일반적으로 비동기 버전인 reigsterAsync, forRootAsync, forFeatureAsync 도 함께 제공하며, 이들은 설정을 Nest의 의존성 주입을 통해 처리한다는 점만 다릅니다.

구성 가능한 모듈 빌더 (Configurable module builder)

registerAsync, forRootAsync 등의 비동기 메서드를 노출하는 고도로 구성 가능한 동적 모듈을 수동으로 만드는 일은, 특히 초보자에게는 꽤 복잡할 수 있습니다. 이를 단순화하기 위해 Nest는 ConfigurableModuleBuilder 클래스를 제공합니다. 이 클래스는 몇 줄의 코드만으로 모듈의 "청사진 (blueprint)"을 구성할 수 있도록 도와줍니다.

 

예를 들어, 앞에서 사용한 ConfigModule 예제를 ConfigurableModuleBuilder를 사용하도록 변경해 봅시다. 시작하기에 앞서, 먼저 ConfigModule이 어떤 옵션을 받는지 나타내는 전용 인터페이스를 정의해야 합니다.

export interface ConfigModuleOptions {
  folder: string;
}

 

이제 준비가 되었으니, 기존의 config.module.ts 파일과 나란히 새로운 파일을 하나 만들고 이름을 config.module-definition.ts로 지정하세요. 이 파일에서는 ConfigurableModuleBuilder를 활용하여 ConfigModule의 정의를 구성할 것입니다.

import { ConfigurableModuleBuilder } from '@nestjs/common';
import { ConfigModuleOptions } from './interfaces/config-module-options.interface';

export const { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN } =
  new ConfigurableModuleBuilder<ConfigModuleOptions>().build();

 

이제 config.module.ts 파일을 열어, 자동 생성된 ConfigurableModuleClass를 활용하도록 구현을 수정해 봅시다.

import { Module } from '@nestjs/common';
import { ConfigService } from './config.service';
import { ConfigurableModuleClass } from './config.module-definition';

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

 

ConfigurableModuleClass를 확장함으로써, ConfigModule은 이제 기존의 register 메서드뿐만 아니라 registerAsync 메서드도 제공하게 됩니다. 이를 통해 소비자는 비동기 팩토리 등을 활용하여 해당 모듈을 비동기 방식으로 구성할 수 있게 됩니다.

@Module({
  imports: [
    ConfigModule.register({ folder: './config' }),
    // 또는 다음과 같이 비동기 방식으로도 구성할 수 있습니다:
    // ConfigModule.registerAsync({
    //   useFactory: () => {
    //     return {
    //       folder: './config',
    //     }
    //   },
    //   inject: [...추가 의존성 주입 대상들...]
    // }),
  ],
})
export class AppModule {}

 

registerAsync 메서드는 다음과 같은 객체를 인자로 받습니다:

{
  /**
   * 주입 토큰으로 사용될 클래스입니다. 이 클래스는 프로바이더로 인스턴스화되며,
   * 해당 인터페이스를 구현하고 있어야 합니다.
   */
  useClass?: Type<
    ConfigurableModuleOptionsFactory<ModuleOptions, FactoryClassMethodKey>
  >;

  /**
   * 모듈을 구성하기 위한 옵션 객체를 반환하는 팩토리 함수입니다.
   * 동기 또는 비동기(Promise) 방식으로 동작할 수 있습니다.
   */
  useFactory?: (...args: any[]) => Promise<ModuleOptions> | ModuleOptions;

  /**
   * 팩토리 함수에서 주입받을 의존성 목록입니다.
   */
  inject?: FactoryProvider['inject'];

  /**
   * 기존에 등록된 프로바이더를 주입 토큰으로 사용합니다.
   * 이 프로바이더는 지정된 인터페이스를 구현하고 있어야 합니다.
   */
  useExisting?: Type<
    ConfigurableModuleOptionsFactory<ModuleOptions, FactoryClassMethodKey>
  >;
}

 

다음은 위 속성들에 대한 하나하나의 설명입니다;

• useFactory - 설정 객체를 반환하는 함수입니다. 동기 또는 비동기 함수일 수 있습니다. 팩토리 함수에 의존성을 주입하려면 inject 속성을 사용하세요. 위 예제에서 이 방식을 사용했습니다.
• inject - 팩토리 함수에 주입될 의존성들의 배열입니다. 의존성의 순서는 팩토리 함수의 매개변수 순서와 일치해야 합니다.
• useClass - 프로바이더로 인스턴스화될 클래스입니다. 해당 클래스는 설정 객체를 반환하는 create() 메서드를 제공하는 인터페이스를 구현해야 합니다. 자세한 내용은 아래의 Custom method key 섹션을 참고하세요.
• useExisting - 이미 등록된 프로바이더를 사용하는 useClass의 변형입니다. Nest가 새 인스턴스를 생성하지 않고 기존에 등록된 프로바이더를 사용하도록 할 때 유용합니다. 이 클래스 역시 useClass에서 사용한 인터페이스를 구현해야 하며, 기본적으로 create() 메서드를 제공해야 합니다. (단, 기본 메서드 이름은 Custom method key 섹션에서 재정의할 수 있습니다.)

위 옵션들 (useFactory, useClass, useExisting) 중 하나만 선택해서 사용해야 하며, 이들은 서로 배타적입니다.

 

마지막으로, 지금까지 사용했던 'CONFIG_OPTIONS' 대신, 자동 생성된 모듈 옵션 프로바이더를 주입받도록 ConfigService 클래스를 업데이트해 봅시다.

@Injectable()
export class ConfigService {
  constructor(@Inject(MODULE_OPTIONS_TOKEN) private options: ConfigModuleOptions) { ... }
}

커스텀 메서드 키

ConfigurableModuleClass는 기본적으로 register 및 그 대응 메서드인 registerAsync를 제공합니다. 다른 메서드 이름을 사용하고 싶다면, ConfigurableModuleBuilder#setClassMethodName 메서드를 다음과 같이 사용하면 됩니다:

export const { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN } =
  new ConfigurableModuleBuilder<ConfigModuleOptions>().setClassMethodName('forRoot').build();

 

이 구성은 ConfigurableModuleBuilder에게 forRoot와 forRootAsync 메서드를 노출하는 클래스를 생성하라고 지시합니다. 예시는 다음과 같습니다:

@Module({
  imports: [
    ConfigModule.forRoot({ folder: './config' }), // <-- "register" 대신 "forRoot" 사용에 주의하세요
    // 또는 다음과 같이 사용할 수도 있습니다:
    // ConfigModule.forRootAsync({
    //   useFactory: () => {
    //     return {
    //       folder: './config',
    //     }
    //   },
    //   inject: [...any extra dependencies...]
    // }),
  ],
})
export class AppModule {}

커스텀 옵션 팩토리 클래스

registerAsync 메서드 (또는 설정에 따라 forRootAsync나 다른 이름)에서는, 소비자가 모듈 설정을 반환하는 provider 정의를 전달할 수 있도록 해 줍니다. 따라서 라이브러리 소비자는 설정 객체를 생성하는 데 사용할 클래스를 전달할 수도 있습니다.

@Module({
  imports: [
    ConfigModule.registerAsync({
      useClass: ConfigModuleOptionsFactory,
    }),
  ],
})
export class AppModule {}

 

이 클래스는 기본적으로 모듈 설정 객체를 반환하는 create() 메서드를 제공해야 합니다. 하지만 라이브러리가 다른 네이밍 규칙을 따르는 경우, ConfigurableModuleBuilder#setFactoryMethodName 메서드를 사용 (예: createConfigOptions와 같은 다른 메서드)하도록 변경할 수 있습니다.

export const { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN } =
  new ConfigurableModuleBuilder<ConfigModuleOptions>().setFactoryMethodName('createConfigOptions').build();

 

이제 ConfigModuleOptionsFactory 클래스는 create 메서드 대신 createConfigOptions 메서드를 제공해야 합니다.

@Module({
  imports: [
    ConfigModule.registerAsync({
      useClass: ConfigModuleOptionsFactory, // <-- 이 클래스는 "createConfigOptions" 메서드를 제공해야 합니다
    }),
  ],
})
export class AppModule {}

추가 옵션

모듈이 특정 동작 방식을 결정하기 위한 추가 옵션을 받아야 하는 특수한 경우들이 있습니다. 대표적인 예로는 isGlobal (또는 global) 플래그처럼, 모듈이 전역으로 등록되어야 하는지를 나타내는 옵션이 있습니다. 이러한 옵션들은 서비스나 프로바이더 (ConfigService 등)에 직접적으로 관련되지 않기 때문에, MODULE_OPTIONS_TOKEN 프로바이더에 포함되어서는 안 됩니다.

 

이런 경우에는 ConfigurableModuleBuilder#setExtras 메서드를 사용할 수 있습니다. 다음 예제를 참고하세요:

export const { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN } =
  new ConfigurableModuleBuilder<ConfigModuleOptions>()
    .setExtras(
      {
        isGlobal: true,
      },
      (definition, extras) => ({
        ...definition,
        global: extras.isGlobal,
      }),
    )
    .build();

 

위 예제에서 setExtras 메서드에 전달된 첫 번째 인자는 "추가 (extra)" 속성들의 기본값을 담은 객체입니다. 두 번째 인자는 자동 생성된 모듈 정의 객체 (provider, exports 등 포함)와 소비자 또는 기본값에 의해 설정된 extras 객체를 받아, 수정된 모듈 정의 객체를 반환하는 함수입니다. 위 예제에서는 extras.isGlobal 속성을 꺼내어 모듈 정의의 global 속성에 할당하고 있습니다. 이 설정은 해당 모듈이 전역 모듈인지 아닌지를 결정합니다 (자세한 내용은 여기에서 확인할 수 있습니다).

 

이제 이 모듈을 사용할 때, 아래와 같이 추가적인 isGlobal 플래그를 전달할 수 있습니다:

@Module({
  imports: [
    ConfigModule.register({
      isGlobal: true,
      folder: './config',
    }),
  ],
})
export class AppModule {}

 

하지만 isGlobal은 "extra" 속성으로 선언되었기 때문에, 이 값은 MODULE_OPTIONS_TOKEN 프로바이더에 포함되지 않습니다:

@Injectable()
export class ConfigService {
  constructor(
    @Inject(MODULE_OPTIONS_TOKEN) private options: ConfigModuleOptions,
  ) {
    // "options" 객체에는 "isGlobal" 속성이 존재하지 않습니다
    // ...
  }
}

자동 생성된 메서드 확장하기

register, registerAsync 등과 같은 자동 생성된 정적 (static) 메서드는 필요에 따라 다음과 같이 확장할 수 있습니다.

@Module({
  providers: [ConfigService],
  exports: [ConfigService],
})
export class ConfigModule extends ConfigurableModuleClass {
  static register(options: typeof OPTIONS_TYPE): DynamicModule {
    return {
      // 여기에 사용자 정의 로직을 추가할 수 있습니다
      ...super.register(options),
    };
  }

  static registerAsync(options: typeof ASYNC_OPTIONS_TYPE): DynamicModule {
    return {
      // 여기에 사용자 정의 로직을 추가할 수 있습니다
      ...super.registerAsync(options),
    };
  }
}

 

OPTIONS_TYPE과 ASYNC_OPTIONS_TYPE 타입은 모듈 정의 파일에서 export 되어야 한다는 점에 주의하세요.

export const {
  ConfigurableModuleClass,
  MODULE_OPTIONS_TOKEN,
  OPTIONS_TYPE,
  ASYNC_OPTIONS_TYPE,
} = new ConfigurableModuleBuilder<ConfigModuleOptions>().build();

---

주입 범위 (Injection scopes)

다른 프로그래밍 언어 배경을 가진 사람들에게는 Nest에서는 거의 모든 것이 들어오는 요청 간에 공유된다는 점이 예상 밖일 수 있습니다. 우리는 데이터베이스에 대한 커넥션 풀, 전역 상태를 가진 싱글턴 서비스 등을 사용합니다. Node.js는 요청/응답 기반의 멀티스레드 상태 비저장 모델을 따르지 않기 때문에, 각 요청이 별도의 스레드에서 처리되지 않습니다. 따라서 싱글턴 인스턴스를 사용하는 것은 애플리케이션에서 완전히 안전합니다.

 

하지만 GraphQL 애플리케이션에서의 요청 기반 캐싱, 요청 추적, 멀티 태넌시와 같이 요청 기반 생명 주기가 필요한 경우도 있습니다. 이럴 때는 주입 스코프를 통해 원하는 프로바이더 생명 주기 동작을 구현할 수 있습니다.

프로바이더 스코프

프로바이더는 다움 중 하나의 스코프를 가질 수 있습니다.

DEFAULT	애플리케이션 전체에서 프로바이더의 단일 인스턴스가 공유됩니다. 인스턴스의 생명 주기는 애플리케이션의 생명 주기와 직접 연결되어 있으며, 애플리케이션이 부트스트랩되면 모든 싱글턴 프로바이더가 인스턴스화됩니다. 기본적으로 싱글턴 스코프가 사용됩니다.
REQUEST	들어오는 각 요청마다 프로바이더의 새로운 인스턴스가 생성돱니다. 해당 요청의 처리가 완료되면 인스턴스는 가비지 컬렉션 됩니다.
TRANSIENT	트랜지언트 프로바이더는 소비자 간에 공유되지 않습니다. 트랜지언트 프로바이더를 주입하는 각 소비자는 새로운 전용 인스턴스를 받게 됩니다.

힌트
대부분의 경우에는 싱글턴 스코프를 사용하는 것이 권장됩니다. 소비자와 요청 간에 프로바이더를 공유하면 인스턴스를 캐시 할 수 있고, 초기화는 애플리케이션 시작 시 한 번만 수행되기 때문입니다.

사용

@Injectable() 데코레이터의 옵션 객체에 scope 속성을 전달하여 주입 스코프를 지정할 수 있습니다:

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

@Injectable({ scope: Scope.REQUEST })
export class CatsService {}

 

마찬가지로, 커스텀 프로바이더의 경우 프로바이더 등록 시 롱핸드 (long-hand, 명시적인 전체 객체 형태의 등록 방식) 형식에서 scope 속성을 설정할 수 있습니다:

{
  provide: 'CACHE_MANAGER',
  useClass: CacheManager,
  scope: Scope.TRANSIENT,
}

힌트
Scope 열거형은 @nestjs/common에서 임포트 할 수 있습니다.

 

싱글턴 스코프는 기본값이므로 명시적으로 선언할 필요는 없습니다. 그래도 프로바이더를 싱글턴 스코프로 선언하고자 한다면, scope 속성에 Scope.DEFAULT 값을 사용할 수 있습니다.

알림
WebSocket 게이트웨이는 반드시 싱글턴으로 동작해야 하므로 요청 스코프 프로바이더를 사용해서는 안 됩니다. 각 게이트웨이는 실제 소켓을 캡슐화하고 있으며 여러 번 인스턴스화될 수 없습니다. 이 제한 사항은 Passport 전략이나 Cron 컨트롤러와 같은 일부 다른 프로바이더도 동일하게 적용됩니다.

컨트롤러 스코프

컨트롤러도 스코프를 가질 수 있으며, 이는 해당 컨트롤러에 선언된 모든 요청 메서드 핸들러에 적용됩니다. 프로바이더 스코프와 마찬가지로, 컨트롤러의 스코프는 생명 주기를 정의합니다. 요청 스코프 (Request-scoped) 컨트롤러의 경우, 들어오는 각 요청마다 새로운 인스턴스가 생성되고 요청 처리가 완료되면 가비지 컬렉션 됩니다.

 

컨트롤러 스코프는 ControllerOptions 객체의 scope 속성으로 선언될 수 있습니다:

@Controller({
  path: 'cats',
  scope: Scope.REQUEST,
})
export class CatsController {}

스코프 계층 구조 (Scope hierarchy)

REQUEST 스코프는 주입 체인을 따라 상위로 전파됩니다. 요청 스코프 프로바이더에 의존하는 컨트롤러는 자동으로 요청 스코프가 됩니다.

 

예를 들어, 다음과 같은 의존성 그래프가 있다고 가정해 봅시다: CatsController <- CatsService <- CatsRepository. 여기서 CatsService가 요청 스코프이고 나머지는 기본 싱글턴이라면, CatsController는 CatsService에 의존하고 있으므로 요청 스코프로 전환됩니다. 반면, CatsRepository는 요청 스코프 객체에 의존하지 않기 때문에 계속해서 싱글턴 스코프를 유지합니다.

 

반면, TRANSIENT 스코프는 이와 같은 전파 패턴을 따르지 않습니다. 예를 들어, 싱글턴 스코프의 DogsService가 트랜지언트 LoggerService를 주입받는다면, LoggerService는 매번 새로운 인스턴스로 주입되지만 DogsService 자체는 여전히 싱글턴 스코프를 유지합니다. 즉, 어디서든 DogsService를 주입하면 동일한 인스턴스를 받습니다. 만약 DogsService도 매번 새 인스턴스로 생성되기를 원한다면, DogsService 역시 명시적으로 TRANSIENT 스코프로 선언해야 합니다.

요청 프로바이더

HTTP 서버 기반 애플리케이션 (@nestjs/platform-express 또는 @nestjs/platform-fastify 등)에서 요청 스코프 프로바이더를 사용할 때, 원본 요청 객체에 접근하고 싶을 수 있습니다. 이 경우 REQUEST 객체를 주입하여 참조할 수 있습니다.

 

REQUEST 프로바이더는 본질적으로 요청 스코프이기 때문에, 사용할 때 명시적으로 스코프를 지정할 필요가 없습니다. 또한 스코프를 지정하려 해도 무시됩니다. 요청 스코프 프로바이더에 의존하는 모든 프로바이더는 자동으로 요청 스코프가 되며, 이 동작은 변경할 수 없습니다.

import { Injectable, Scope, Inject } from '@nestjs/common';
import { REQUEST } from '@nestjs/core';
import { Request } from 'express';

@Injectable({ scope: Scope.REQUEST })
export class CatsService {
  constructor(@Inject(REQUEST) private request: Request) {}
}

 

기저에 있는 플랫폼/프로토콜의 차이로 인해, 마이크로서비스나 GraphQL 애플리케이션에서는 요청 객체에 접근하는 방식이 조금 다릅니다. GraphQL 애플리케이션에서는 REQUEST 대신 CONTEXT를 주입합니다:

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

@Injectable({ scope: Scope.REQUEST })
export class CatsService {
  constructor(@Inject(CONTEXT) private context) {}
}

 

그런 다음 GraphQLModule에서 context 값을 설정할 때, request를 그 속성으로 포함하도록 구성해야 합니다.

Inquirer 프로바이더

로깅이나 메트릭 프로바이더처럼, 특정 프로바이더가 어떤 클래스에 의해 생성되었는지 알고 싶을 때는 INQUIRER 토큰을 주입하여 해당 클래스를 참조할 수 있습니다.

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

@Injectable({ scope: Scope.TRANSIENT })
export class HelloService {
  constructor(@Inject(INQUIRER) private parentClass: object) {}

  sayHello(message: string) {
    console.log(`${this.parentClass?.constructor?.name}: ${message}`);
  }
}

 

그리고 다음과 같이 사용할 수 있습니다.

import { Injectable } from '@nestjs/common';
import { HelloService } from './hello.service';

@Injectable()
export class AppService {
  constructor(private helloService: HelloService) {}

  getRoot(): string {
    this.helloService.sayHello('My name is getRoot');

    return 'Hello world!';
  }
}

 

위 예제에서 AppService#getRoot가 호출되면, "AppService: My name is getRoot"가 콘솔에 출력됩니다.

성능

요청 스코프 프로바이더를 사용하면 애플리케이션 성능에 영향을 미칩니다. Nest는 가능한 많은 메타데이터를 캐시 하려고 하지만, 여전히 매 요청마다 클래스의 인스턴스를 생성해야 합니다. 따라서 평균 응답 시간과 전체 벤치마크 결과가 느려질 수 있습니다. 반드시 요청 스코프가 필요한 경우가 아니라면, 기본 싱글턴 스코프를 사용하는 것이 강력히 권장됩니다.

힌트
겉보기에는 꽤 위협적으로 느껴질 수 있지만, 요청 스코프 프로바이더를 적절히 활용한 잘 설계된 애플리케이션이라면 지연 시간 (latency) 기준으로 성능 저하는 약 5% 이내에 불과합니다.

내구성 프로바이더

앞서 언급한 요청 프로바이더는 지연 시간이 증가할 수 있습니다. 요청 스코프 프로바이더가 컨트롤러 인스턴스에 주입되거나, 더 깊이 주입되어 있다면 해당 컨트롤러 자체도 요청 스코프가 되기 때문입니다. 이는 각 요청마다 컨트롤러 (및 그 요청 스코프 프로바이더)가 새로 생성되고, 이후 가비지 컬렉션 된다는 의미입니다. 예를 들어 3만 개의 요청이 동시에 발생하면, 3만 개의 일시적인 컨트롤러 인스턴스가 생성됩니다.

 

대부분의 프로바이더가 공통적으로 의존하는 프로바이더 (예: 데이터베이스 커넥션, 로거 서비스 등)가 요청 스코프일 경우, 이로 인해 해당 프로바이더를 의존하는 모든 프로바이더가 자동으로 요청 스코프가 됩니다. 이는 특히 멀티 태넌시 애플리케이션에서 문제가 될 수 있습니다. 예를 들어, 요청 객체에서 헤더나 토큰을 가져와 테넌트별 데이터베이스 연결이나 스키마를 선택하는 중앙 집중형 요청 스코프 "데이터 소스" 프로바이더가 있을 경우 더욱 그렇습니다.

 

예를 들어, 10명의 서로 다른 고객이 번갈아 사용하는 애플리케이션이 있다고 가정해 봅시다. 각 고객은 전용 데이터 소스를 가지고 있으며, 고객 A가 절대로 고객 B의 데이터베이스에 접근하지 못하도록 보장해야 합니다. 이를 달성하는 한 가지 방법은 요청 객체를 기반으로 현재 고객을 식별하고 해당 데이터베이스에 연결하는 요청 스코프의 "데이터 소스" 프로바이더를 선언하는 것입니다. 이 접근 방식을 사용하면 몇 분 안에 애플리케이션을 멀티 태넌시 애플리케이션으로 전환할 수 있습니다.

 

하지만 이 방식의 큰 단점은, 애플리케이션의 많은 컴포넌트가 이 "데이터 소스" 프로바이더에 의존하게 되면서, 이들 또한 암묵적으로 "요청 스코프"가 되고, 결국 애플리케이션 성능에 영향을 주게 된다는 점입니다.

 

그렇다면 더 나은 해결책은 없을까요? 고객이 10명뿐이라면, 요청마다 DI 트리를 매번 재생성하는 대신, 고객별로 10개의 개별 DI 서브 트리를 만들 수는 없을까요? 만약 각 요청마다 고유한 속성 (예: 요청 UUID)에 의존하지 않고, 공통된 특정 속성으로 요청을 분류할 수 있다면, 매 요청마다 DI 트리를 다시 만들 이유는 없습니다.

 

바로 이럴 때 내구성 프로바이더 (Durable Provider)가 유용합니다.

 

내구성 프로바이더를 적용하기 전에, 먼저 Nest에 "공통 요청 속성이 무엇인지"를 알려주는 전략을 등록해야 하며, 요청을 그룹화하고 해당 DI 서브 트리와 연관시키는 로직을 제공해야 합니다.

import {
  HostComponentInfo,
  ContextId,
  ContextIdFactory,
  ContextIdStrategy,
} from '@nestjs/core';
import { Request } from 'express';

const tenants = new Map<string, ContextId>();

export class AggregateByTenantContextIdStrategy implements ContextIdStrategy {
  attach(contextId: ContextId, request: Request) {
    const tenantId = request.headers['x-tenant-id'] as string;
    let tenantSubTreeId: ContextId;

    if (tenants.has(tenantId)) {
      tenantSubTreeId = tenants.get(tenantId);
    } else {
      tenantSubTreeId = ContextIdFactory.create();
      tenants.set(tenantId, tenantSubTreeId);
    }

    // 트리가 Durable하지 않다면 기본 contextId 반환
    return (info: HostComponentInfo) =>
      info.isTreeDurable ? tenantSubTreeId : contextId;
  }
}

힌트
요청 스코프와 마찬가지로, 내구성 (durability)은 주입 체인을 따라 전파됩니다. 즉, A가 B를 의존하고 B가 durABLE로 지정되어 있다면, A도 암묵적으로 durable이 됩니다 (단, A 프로바이더에 대해 명시적으로 durable을 false로 설정하지 않은 경우에 한해).

경고
이 전략은 많은 수의 태넌트와 함께 동작하는 애플리케이션에는 이상적이지 않다는 점에 유의하세요.

 

attach 메서드에서 반환된 값은 특정 호스트에 대해 어떤 컨텍스트 식별자를 사용할지 Nest에 지시합니다. 위의 예시에서는, 호스트 컴포넌트 (예: 요청 스코프 컨트롤러)가 durable로 표시된 경우, 원래 자동 생성된 contextId 대신 tenantSubTreeId를 사용하도록 지정했습니다 (프로바이더를 어떻게 durable로 지정하는지는 아래에서 설명됨). 또한 위 예제에서는 페이로드 (= 서브 트리의 "루트"를 나타내는 REQUEST/CONTEXT 프로바이더)가 등록되지 않습니다.

 

durable 트리에 대해 페이로드를 등록하고 싶다면, 다음과 같은 구문을 사용하세요:

// `AggregateByTenantContextIdStrategy#attach` 메서드의 반환 값:
return {
  resolve: (info: HostComponentInfo) =>
    info.isTreeDurable ? tenantSubTreeId : contextId,
  payload: { tenantId },
};

 

이제 @Inject(REQUEST) 또는 @Inject(CONTEXT)를 사용해 REQUEST 프로바이더 (또는 GraphQL 애플리케이션의 경우 CONTEXT)를 주입할 때, 페이로드 객체가 주입됩니다 (이 경우 단일 속성인 tenantId를 포함).

 

이 전략은 전역적으로 적용되므로, 애플리케이션 어디에든 등록할 수 있으며, 예를 들어 main.ts 파일에 등록할 수 있습니다:

ContextIdFactory.apply(new AggregateByTenantContextIdStrategy());

힌트
ContextIdFactory 클래스는 @nestjs/core 패키지에서 임포트 됩니다.

 

요청이 애플리케이션에 도달하기 전에 해당 전략이 등록되기만 하면, 모든 것이 의도한 대로 작동합니다.

 

마지막으로, 일반 프로바이더를 durable 프로바이더로 전환하려면, durable 플래그를 true로 설정하고 스코프를 Scope.REQUEST로 지정하면 됩니다 (이미 요청 스코프 체인 내에 있다면 스코프 설정은 생략 가능).

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

@Injectable({ scope: Scope.REQUEST, durable: true })
export class CatsService {}

 

마찬가지로, 커스텀 프로바이더의 경우 프로바이더 등록 시 롱핸드 형식에서 durable 속성을 설정할 수 있습니다:

{
  provide: 'foobar',
  useFactory: () => { ... },
  scope: Scope.REQUEST,
  durable: true,
}

Reference

• Nest.js | Dynamic modules
• Nest.js | Injection scopes