[Nest.js] Fundamentals - Custom providers, Asynchronous providers

커스텀 프로바이더

앞선 챕터들에서는 Nest에서의 의존성 주입 (Dependency Injection, DI)의 다양한 측면과 사용 방법에 대해 다루었습니다. 그중 하나는 클래스에 인스턴스 (대개 서비스 프로바이더)를 주입하는 생성자 기반 의존성 주입입니다. 의존성 주입이 Nest의 핵심에 근본적으로 내장되어 있다는 사실은 이제 더 이상 놀랍지 않을 것입니다. 지금까지는 주로 하나의 주요 패턴만 살펴보았지만, 애플리케이션이 복잡해질수록 DI 시스템의 전체 기능을 활용해야 할 필요가 있습니다. 이제 이를 더 자세히 살펴보겠습니다.

DI의 기본 원리

의존성 주입은 제어의 역전 (Inversion of Control, IoC) 기법 중 하나로, 의존성의 인스턴스 생성을 개발자 코드가 아닌 IoC 컨테이너 (여기서는 NestJS 런타임 시스템)에 위임하는 방식입니다. Providers 챕터에서 보았던 예제를 다시 살펴보겠습니다.

 

먼저, 프로바이더를 정의합니다. @Injectable() 데코레이터는 CatsService 클래스를 프로바이더로 표시합니다.

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

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

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

 

그다음, Nest가 해당 프로바이더를 우리의 컨트롤러 클래스에 주입하도록 요청합니다:

import { Controller, Get } from '@nestjs/common';
import { CatsService } from './cats.service';
import { Cat } from './interfaces/cat.interface';

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

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

 

마지막으로, 해당 프로바이더를 Nest IoC 컨테이너에 등록합니다:

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 {}

 

이 기능이 작동하기 위해 내부적으로 어떤 일이 일어나는 걸까요? 이 과정에는 세 가지 핵심 단계가 있습니다:

1. cats.service.ts에서 @Injectable() 데코레이터는 CatsService 클래스를 Nest IoC 컨테이너가 관리할 수 있는 클래스로 선언합니다.
2. cats.controller.ts에서 CatsController는 생성자 주입을 통해 CatsService 토큰에 대한 의존성을 선언합니다.
3. app.module.ts에서 CatsService 토큰을 cats.service.ts 파일의 CatsService 클래스와 연결합니다. 이 연결 과정은 아래에서 보게 될 등록 (registration) 과정의 일환입니다.

  constructor(private catsService: CatsService)

 

Nest IoC 컨테이너가 CatsController를 인스턴스화할 때, 먼저 해당 클래스의 모든 의존성을 확인합니다. CatsService 의존성을 발견하면, 위의 3단계 등록 과정에 따라 CatsService 토큰을 조회하여 CatsService 클래스를 반환받습니다. 기본 동작인 SINGLETON 스코프를 가정하면, Nest는 CatsService 인스턴스를 새로 생성하고 이를 캐싱한 뒤 반환하거나, 이미 캐싱된 인스턴스가 있다면 그 인스턴스를 그대로 반환합니다.

 

*이 설명은 개념을 쉽게 전달하기 위해 약간 단순화된 것입니다. 중요한 부분 중 하나는 의존성을 분석하는 과정이 매우 정교하며, 애플리케이션 부트스트랩 시점에 이루어진다는 점입니다. 핵심적인 특징 중 하나는 이 의존성 분석 (또는 "의존성 그래프 생성")이 전이적이라는 ㅈ것입니다. 위의 예시에서 CatsService 자체에 또 다른 의존성이 있다면, Nest는 그것들도 함께 해결합니다. 의존성 그래프는 모든 의존성이 올바른 순서 (본질적으로 "하향식")로 해결되도록 보장합니다. 이 메커니즘 덕분에 개발자는 복잡한 의존성 그래프를 직접 관리할 필요가 없습니다.

표준 프로바이더

@Module() 데코레이터를 좀 더 자세히 살펴보겠습니다. app.module에서는 다음과 같이 선언합니다:

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

 

providers 속성은 프로바이더들의 배열을 받습니다. 지금까지는 클래스 이름 목록을 통해 프로바이더를 제공해 왔습니다. 실제로 providers: [CatsService]라는 문법은 다음과 같은 더 완전한 문법의 축약입니다.

providers: [
  {
    provide: CatsService,
    useClass: CatsService,
  },
];

 

이제 이러한 명시적인 구성 방식을 보면, 등록 과정이 어떻게 이루어지는지 이해할 수 있습니다. 여기서는 CatsService 토큰을 CatsService 클래스와 명확하게 연결하고 있습니다. 축약형 표기법은 단지 일반적인 사용 사례 (토큰 이름과 클래스 이름이 동일할 때)를 간소화하기 위한 편의 기능일 뿐입니다.

커스텀 프로바이더

기능 요구사항이 표준 프로바이더 (Standard providers)로는 충족되지 않을 때는 어떻게 해야 할까요? 다음은 그런 사례들입니다:

• Nest가 클래스를 인스턴스화하거나 캐시 된 인스턴스를 반환하는 대신, 직접 커스텀 인스턴스를 생성하고 싶은 경우
• 기존 클래스를 다른 의존성에서 재사용하고 싶은 경우
• 테스트를 위해 클래스를 모킹 (mock)한 버전으로 대체하고 싶은 경우

Nest는 이러한 상황을 처리할 수 있도록 커스텀 프로바이더 (Custom providers)를 정의할 수 있게 해 줍니다. 이를 위한 다양한 정의 방법도 함께 제공합니다. 이제 각 방식을 함께 살펴보겠습니다.

힌트
의존성 해결 과정에서 문제가 발생한다면, NEST_DEBUG 환경 변수를 설정하여 애플리케이션 시작 시 의존성 해결 로그를 추가로 확인할 수 있습니다.

값 프로바이더: useValue

useValue 문법은 상수 값을 주입하거나, 외부 라이브러리를 Nest 컨테이너에 넣거나, 실제 구현체를 목 객체로 대체할 때 유용합니다. 예를 들어, 테스트를 위해 Nest가 목업 된 CatsService를 사용하도록 강제하고 싶다고 가정해 봅시다.

import { CatsService } from './cats.service';

const mockCatsService = {
  /* 목업 구현
  ...
  */
};

@Module({
  imports: [CatsModule],
  providers: [
    {
      provide: CatsService,
      useValue: mockCatsService,
    },
  ],
})
export class AppModule {}

 

이 예제에서 CatsService 토큰은 mockCatsService 목 객체로 해결됩니다. useValue는 값을 요구하는데, 이 경우 대체하려는 CatsService 클래스와 동일한 인터페이스를 가진 리터럴 객체입니다. TypeScript의 구조적 타이핑 (Structural Typing) 덕분에, 호환되는 인터페이스를 가진 객체라면 어떤 것이든 사용할 수 있으며, 리터럴 객체는 물론 new로 생성한 클래스 인스턴스도 가능합니다.

비클래스 기반 프로바이더 토큰

지금까지 우리는 클래스 이름을 프로바이더 토큰으로 사용해 왔습니다 (providers 배열 내 provide 속성의 값). 이는 생성자 기반 주입에서 일반적으로 사용되는 패턴과 일치하며, 이 경우 토큰 역시 클래스 이름입니다. (토큰 개념이 완전히 익숙하지 않다면 앞서 설명한 DI 기본 내용을 참고하세요.) 하지만 때로는 문자열이나 심볼을 DI 토큰으로 사용하는 유연성이 필요할 수 있습니다. 예를 들어:

import { connection } from './connection';

@Module({
  providers: [
    {
      provide: 'CONNECTION',
      useValue: connection,
    },
  ],
})
export class AppModule {}

 

이 예제에서는 문자열 토큰 'CONNECTION'을 외부 파일에서 가져온 기존의 커넥션 객체와 연결하고 있습니다.

알림
문자열 외에도 JavaScript 심볼이나 TypeScript 열거형 (enum)을 토큰 값으로 사용할 수 있습니다.

 

앞서 우리는 표준 생성자 기반 주입 패턴을 사용하여 프로바이더를 주입하는 방법을 살펴보았습니다. 이 패턴에서는 의존성을 클래스 이름으로 선언해야 합니다. 반면, 'CONNECTION' 커스텀 프로바이더는 문자열 토큰을 사용합니다. 이러한 프로바이더를 주입하려면 어떻게 해야 할까요? 이를 위해 @Inject() 데코레이터를 사용합니다. 이 데코레이터에서는 토큰을 인자로 하나 받습니다.

@Injectable()
export class CatsRepository {
  constructor(@Inject('CONNECTION') connection: Connection) {}
}

힌트
@Inject() 데코레이터는 @nestjs/common 패키지에서 가져옵니다.

 

위 예제에서는 설명을 위해 문자열 'CONNECTION'을 직접 사용했지만, 코드의 가독성과 유지보수성을 위해 토큰은 constants.ts와 같은 별도의 파일에 정의하는 것이 모범 사례입니다. 이는 심볼이나 열거형 (enum)을 별도 파일에 정의하고 필요할 때 import 해서 사용하는 방식과 동일하게 다루는 것이 좋습니다.

클래스 프로바이더: useClass

useClass 문법은 토큰이 어떤 클래스에 매핑될지 동적으로 결정할 수 있게 해 줍니다. 예를 들어, 기본 또는 추상적인 ConfigService 클래스가 있고, 현재 실행 환경에 따라 서로 다른 ConfigService 구현체를 Nest가 제공하도록 하고 싶다고 가정해 봅시다. 아래 코드는 그러한 전략을 구현한 예시입니다.

const configServiceProvider = {
  provide: ConfigService,
  useClass:
    process.env.NODE_ENV === 'development'
      ? DevelopmentConfigService
      : ProductionConfigService,
};

@Module({
  providers: [configServiceProvider],
})
export class AppModule {}

 

이 코드 예제에서 몇 가지 세부 사항을 살펴보겠습니다. 먼저, configServiceProvider를 리터럴 객체로 먼저 정의한 뒤, 이를 모듈 데코레이터의 providers 속성에 전달하고 있습니다. 이는 단순한 코드 구성 방식의 차이일 뿐이며, 기능적으로는 이 장에서 지금까지 사용한 다른 예제들과 동일합니다.

 

또한, 우리는 ConfigService 클래스 이름을 토큰으로 사용했습니다. ConfigService에 의존하는 클래스가 있을 경우, Nest는 등록된 클래스 (DevelopmentConfigService 또는 ProductionConfigService)의 인스턴스를 주입합니다. 이는 다른 곳에 선언된 기본 구현 (@Injectable() 데코레이터로 선언된 ConfigService 등)을 덮어쓰게 됩니다.

팩토리 프로바이더: useFactory

useFactory 문법은 프로바이더를 동적으로 생성할 수 있게 해 줍니다. 실제 프로바이더는 팩토리 함수가 반환하는 값에 의해 제공됩니다. 이 팩토리 함수는 단순할 수도 있고 복잡할 수도 있습니다. 단순한 경우에는 다른 프로바이더에 의존하지 않을 수 있고, 복잡한 경우에는 결과를 계산하기 위해 다른 프로바이더를 주입받을 수도 있습니다. 이러한 복잡한 경우를 지원하기 위해 useFactory는 다음 두 가지 메커니즘을 함께 제공합니다:

1. 팩토리 함수는 (선택적으로) 인자를 받을 수 있습니다.
2. inject 속성은 Nest가 인스턴스를 주입해야 할 프로바이더 목록을 배열로 받습니다. Nest는 이 목록의 각 프로바이더를 해석해 팩토리 함수의 인자로 전달합니다. 이때, 순서가 중요하며, 필요시 각 항목을 선택적으로 지정할 수도 있습니다.

아래 예제는 이러한 동작을 잘 보여줍니다.

const connectionProvider = {
  provide: 'CONNECTION',
  useFactory: (optionsProvider: MyOptionsProvider, optionalProvider?: string) => {
    const options = optionsProvider.get();
    return new DatabaseConnection(options);
  },
  inject: [MyOptionsProvider, { token: 'SomeOptionalProvider', optional: true }],
  //       \______________/             \__________________/
  //        이 프로바이더는              이 토큰을 가진 프로바이더는
  //        필수입니다.                   `undefined`로 해결될 수 있습니다.
};

@Module({
  providers: [
    connectionProvider,
    MyOptionsProvider, // 클래스 기반 프로바이더
    // { provide: 'SomeOptionalProvider', useValue: 'anything' }, // 선택적 프로바이더 예시
  ],
})
export class AppModule {}

별칭 프로바이더: useExisting

useExisting 문법은 기존 프로바이더에 대한 별칭 (alias)을 생성할 수 있게 해 줍니다. 이로써 하나의 프로바이더를 두 개 이상의 토큰으로 접근할 수 있게 해 줍니다. 아래 예제에서는 문자열 기반 토큰 'AliasedLoggerService'가 클래스 기반 토큰 LoggerService의 별칭 역할을 합니다. 예를 들어, 'AliasedLoggerService'와 LoggerService 각각을 의존성으로 가진 두 컴포넌트가 있다고 가정하면, 두 토큰이 모두 SINGLETON 스코프로 지정된 경우 동일한 인스턴스로 해결됩니다.

@Injectable()
class LoggerService {
  /* 구현 상세 */
}

const loggerAliasProvider = {
  provide: 'AliasedLoggerService',
  useExisting: LoggerService,
};

@Module({
  providers: [LoggerService, loggerAliasProvider],
})
export class AppModule {}

비서비스 기반 프로바이더

프로바이더는 주로 서비스를 제공하지만, 그 용도에 제한은 없습니다. 프로바이더는 어떤 값이든 제공할 수 있습니다. 예를 들어, 아래와 같이 현재 환경에 따라 구성 객체 배열을 제공하는 프로바이더도 만들 수 있습니다.

const configFactory = {
  provide: 'CONFIG',
  useFactory: () => {
    return process.env.NODE_ENV === 'development' ? devConfig : prodConfig;
  },
};

@Module({
  providers: [configFactory],
})
export class AppModule {}

커스텀 프로바이더 내보내기

다른 프로바이더와 마찬가지로, 커스텀 프로바이더도 정의된 모듈 내부에 한정된 범위 (scope)를 가집니다. 이를 다른 모듈에서도 사용할 수 있도록 하려면 export 해야 합니다. 커스텀 프로바이더를 export 하려면 토큰 또는 전체 프로바이더 객체를 사용할 수 있습니다.

 

다음 예제는 토큰을 사용하여 export 하는 방법을 보여줍니다.

const connectionFactory = {
  provide: 'CONNECTION',
  useFactory: (optionsProvider: OptionsProvider) => {
    const options = optionsProvider.get();
    return new DatabaseConnection(options);
  },
  inject: [OptionsProvider],
};

@Module({
  providers: [connectionFactory],
  exports: ['CONNECTION'],
})
export class AppModule {}

 

또는, 전체 프로바이더 객체를 사용하여 export 할 수도 있습니다:

const connectionFactory = {
  provide: 'CONNECTION',
  useFactory: (optionsProvider: OptionsProvider) => {
    const options = optionsProvider.get();
    return new DatabaseConnection(options);
  },
  inject: [OptionsProvider],
};

@Module({
  providers: [connectionFactory],
  exports: [connectionFactory],
})
export class AppModule {}

---

비동기 프로바이더

애플리케이션이 시작되기 전에 하나 이상의 비동기 작업이 완료될 때까지 시작을 지연시켜야 하는 경우가 있습니다. 예를 들어, 데이터베이스 연결이 완료되기 전까지는 요청을 받지 않도록 하고 싶을 수 있습니다. 이러한 요구는 비동기 프로바이더 (Asynchronous providers)를 사용하여 해결할 수 있습니다.

 

이를 위한 문법은 useFactory 문법과 함께 async/await을 사용하는 것입니다. 팩토리 함수는 Promise를 반환하며, 그 안에서 비동기 작업을 await 할 수 있습니다. Nest는 해당 프로바이더에 의존하는 어떤 클래스도 인스턴스화하기 전에 해당 Promise가 해결될 때까지 대기합니다.

{
  provide: 'ASYNC_CONNECTION',
  useFactory: async () => {
    const connection = await createConnection(options);
    return connection;
  },
}

힌트
커스텀 프로바이더 문법에 대해 더 알아보려면 여기를 참고하세요.

주입

비동기 프로바이더도 다른 일반 프로바이더들과 마찬가지로 토큰을 통해 다른 컴포넌트에 주입됩니다. 위 예제에서처럼, 다음과 같이 주입할 수 있습니다: @Inject('ASYNC_CONNECTION')

예제

TypeORM 레시피에는 비동기 프로바이더를 활용한 더 실질적인 예제가 포함되어 있습니다.

Reference

• Nest.js | Custom providers
• Nest.js | Asynchronous providers