[Nest.js] Fundamentals | Lifecycle events, Discovery service

Lifecycle events

Nest 애플리케이션과 모든 애플리케이션 구성 요소는 Nest가 관리하는 생명 주기를 가집니다. Nest는 주요 생명 주기 이벤트에 대한 가시성과, 해당 시점에 모듈, 프로바이더 또는 컨트롤러에서 등록된 코드를 실행할 수 있는 생명 주기 후크 (lifecycle hook)를 제공합니다.

생명 주기 순서

다음 다이어그램은 애플리케이션이 부트스트랩된 시점부터 Node 프로세스가 종료될 때까지 주요 생명 주기 이벤트 순서를 보여줍니다. 전체 생명 주기는 다음과 같이 세 단계로 나눌 수 있습니다: 초기화 (initializing), 실행 (running), 종료 (terminating). 이 생명 주기를 활용하면 모듈과 서비스의 적절한 초기화, 활성 연결 관리, 종료 신호 수신 시 애플리케이션의 정상적인 종료를 계획할 수 있습니다.

생명 주기 이벤트

생명 주기 이벤트는 애플리케이션의 부트스트랩 및 종료 과정에서 발생합니다. Nest는 각 생명 주기 이벤트 시점에 대해 모듈, 프로바이더, 컨트롤러에 등록된 생명 주기 후크 메서드를 호출합니다 (단, 종료 후크는 아래 설명처럼 먼저 활성화해야 합니다). 위의 다이어그램에서 보듯, Nest는 연결을 수신하기 시작하거나 중단하기 위해 내부 메서드도 호출합니다.

 

다음 표에서 onModuleInit과 onApplicationBootstrap은 app.init() 또는 app.listen()을 명시적으로 호출했을 때만 트리거 됩니다.

 

또한 onModuleDestroy, beforeApplicationShutdown, onApplicationShutdown은 app.close()를 명시적으로 호출하거나, 프로세스가 SIGTERM과 같은 시스템 종료 신호를 수신했을 때, 그리고 애플리케이션 부트스트랩 시 enableShutdownHooks를 올바르게 호출한 경우에만 트리거 됩니다 (자세한 내용은 아래 "Application shutdown" 항목 참조).

생명 주기 후크 메서드	후크 메서드 호출을 트리거하는 생명 주기 이벤트
onModuleInit()	해당 모듈의 의존성이 모두 해결된 후 한 번 호출됩니다.
onApplicationBootstrap()	모든 모듈이 초기화된 후, 연결 수신을 시작하기 전에 호출됩니다.
onModuleDestroy()	종료 신호 (SIGTERM 등)를 수신한 후 호출됩니다.
beforeApplicationShutdown()	모든 onModuleDestroy() 핸들러가 완료된 후 호출되며 (Promise가 resolve 또는 reject된 상태), 이 단계가 끝나면 기존 연결이 모두 닫힙니다 (app.close() 호출됨).
onApplicationShutdown()	연결이 모두 닫힌 후 (app.close()가 resolve된 후) 호출됩니다.

 

* 위 이벤트들의 경우, app.close()를 명시적으로 호출하지 않는다면, SIGTERM 같은 시스템 종료 신호에 반응하게 하려면 별도로 활성화해야 합니다. 자세한 내용은 아래 "Application shutdown" 섹션을 참고하세요.

주의
위에 나열된 생명 주기 후크들은 request-scoped 클래스에는 호출되지 않습니다. request scope 클래스는 애플리케이션 생명 주기와 연결되어 있지 않으며, 수명이 예측 불가능합니다. 이들은 각 요청마다 별도로 생성되며, 응답이 완료되면 자동으로 garbage-collected 됩니다.

힌트
onModuleInit()과 onApplicationBootstrap()의 실행 순서는 모듈의 import 순서에 직접적으로 의존하며, 이전 후크가 완료될 때까지 대기합니다.

사용

각 생명 주기 후크는 인터페이스로 표현됩니다. 이 인터페이스들은 TypeScript 컴파일 후에는 존재하지 않기 때문에 기술적으로는 선택 사항이지만, 강한 타입 지원과 에디터 도구의 도움을 받기 위해서는 사용하는 것이 좋은 관례입니다. 생명 주기 후크를 등록하려면, 해당 인터페이스를 구현하면 됩니다. 예를 들어, 특정 클래스 (예: 컨트롤러, 프로바이더, 모듈)에서 모듈 초기화 시 호출될 메서드를 등록하려면, OnModuleInit 인터페이스를 구현하고 onModuleInit() 메서드를 작성하면 됩니다:

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

@Injectable()
export class UsersService implements OnModuleInit {
  onModuleInit() {
    console.log(`The module has been initialized.`);
  }
}

비동기 초기화

OnModuleInit과 OnApplicationBootstrap 후크는 애플리케이션 초기화 과정을 지연시킬 수 있도록 해 줍니다. 즉, 해당 메서드에서 Promise를 반환하거나 async로 선언하고 메서드 내부에서 await를 사용하여 비동기 작업이 완료될 때까지 대기할 수 있습니다.

async onModuleInit(): Promise<void> {
  await this.fetch();
}

애플리케이션 종료

onModuleDestroy(), beforeApplicationShutdown(), onApplicationShutdown() 후크는 종료 단계에서 호출됩니다. 이들은 app.close()를 명시적으로 호출했을 때나, SIGTERM과 같은 시스템 종료 신호를 수신했을 때(옵트인 한 경우)에 실행됩니다. 이 기능은 Kubernetes에서 컨테이너 생명 주기를 관리하거나, Heroku에서 dyno 종료 처리를 위한 용도로 자주 사용됩니다.

 

종료 후크 리스너는 시스템 자원을 소비하므로 기본적으로 비활성화되어 있습니다. 종료 후크를 사용하려면, enableShutdownHooks()를 호출하여 리스너를 활성화해야 합니다.

import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  // 종료 후크 리스너 활성화
  app.enableShutdownHooks();

  await app.listen(process.env.PORT ?? 3000);
}
bootstrap();

주의
플랫폼의 본질적인 제한으로 인해, NestJS는 Windows에서 애플리케이션 종료 후크에 대해 제한적인 지원만 제공합니다. SIGINT, SIGBREAK, 그리고 어느 정도는 SIGHUP이 작동할 수 있습니다 - 자세한 내용은 참고하세요, 하지만 SIGTERM은 Windows에서 절대 작동하지 않습니다. 이는 작업 관리자에서 프로세스를 종료하는 것이 무조건적이기 때문입니다. 즉, "애플리케이션이 이를 감지하거나 방지할 방법이 없다"는 뜻입니다. Windows에서 SIGINT, SIGBREAK 등이 어떻게 처리되는지에 대해서는 libuv 문서를 참고하세요. 또한, Node.js의 Process Signal Events 문서도 참고할 수 있습니다.

정보
enableShutdownHooks는 리스너를 시작하므로 메모리를 소비합니다. 하나의 Node 프로세스에서 여러 Nest 애플리케이션을 동시에 실행하는 경우 (예: Jest로 병렬 테스트 실행 시), Node가 리스너 수가 과도하다고 경고할 수 있습니다. 이러한 이유로 enableShutdownHooks는 기본적으로 활성화되어 있지 않습니다. 단일 Node 프로세스에서 여러 인스턴스를 실행할 때 이 조건을 반드시 인지하세요.

 

애플리케이션이 종료 신호를 수신하면, 등록된 onModuleDestroy(), beforeApplicationShutdown(), onApplicationShutdown() 메서드를 해당 순서대로 호출하며, 이때 해당 신호를 첫 번째 매개변수로 전달합니다. 등록된 함수가 비동기 호출을 await 하는 경우 (Promise를 반환할 경우), Nest는 해당 Promise가 resolve 되거나 reject 될 때까지 다음 단계로 진행하지 않습니다.

@Injectable()
class UsersService implements OnApplicationShutdown {
  onApplicationShutdown(signal: string) {
    console.log(signal); // 예: "SIGINT"
  }
}

정보
app.close()를 호출해도 Node 프로세스는 종료되지 않으며, 단지 onModuleDestroy()와 onApplicationShutdown() 후크만 트리거 됩니다. 따라서, 백그라운드에서 실행 중인 interval, 정기 실행 작업 등이 있다면 프로세스는 자동으로 종료되지 않습니다.

Discovery service

@nestjs/core 패키지에서 제공하는 DiscoveryService는 NestJS 애플리케이션 내에서 프로바이더, 컨트롤러 및 기타 메타데이터를 동적으로 탐색하고 가져올 수 있게 해 주는 강력한 유틸리티입니다. 이 기능은 특히 플러그인, 데코레이터 또는 런타임 리플렉션에 의존하는 고급 기능을 구축할 때 유용합니다. DiscoveryService를 활용하면 더 유연하고 모듈화 된 아키텍처를 설계할 수 있으며, 애플리케이션에서 자동화 및 동적 동작을 구현할 수 있습니다.

시작하기

DiscoveryService를 사용하기 전에, 이를 사용할 모듈에 DiscoveryModule을 Import 해야 합니다. 이 과정을 통해 DiscoveryService가 의존성 주입 대상으로 등록됩니다. 다음은 NestJS 모듈에서 이를 설정하는 예시입니다:

import { Module } from '@nestjs/common';
import { DiscoveryModule } from '@nestjs/core';
import { ExampleService } from './example.service';

@Module({
  imports: [DiscoveryModule],
  providers: [ExampleService],
})
export class ExampleModule {}

 

모듈 설정이 완료되면, DiscoveryService는 동적 탐색이 필요한 어떤 프로바이더나 서비스에도 주입하여 사용할 수 있습니다.

@Injectable()
export class ExampleService {
  constructor(private readonly discoveryService: DiscoveryService) {}
}

프로바이더 및 컨트롤러 탐색하기

DiscoveryService의 핵심 기능 중 하나는 애플리케이션에 등록된 모든 프로바이더를 조회하는 것입니다. 이는 특정 조건에 따라 프로바이더를 동적으로 처리할 때 유용합니다. 다음 코드는 모든 프로바이더에 접근하는 방법을 보여줍니다.

const providers = this.discoveryService.getProviders();
console.log(providers);

 

각 프로바이더 객체에는 인스턴스, 토큰, 메타데이터 등의 정보가 포함되어 있습니다. 마찬가지로, 애플리케이션에 등록된 모든 컨트롤러를 조회하고 싶다면 다음과 같이 할 수 있습니다:

const controllers = this.discoveryService.getControllers();
console.log(controllers);

 

이 기능은 컨트롤러를 동적으로 처리해야 하는 상황, 예를 들어 분석 추적 (analytics tracking)이나 자동 등록 메커니즘과 같은 경우에 특히 유용합니다.

메타데이터 추출하기

프로바이더 및 컨트롤러를 탐색하는 것을 넘어, DiscoveryService는 이러한 구성 요소에 부착된 메타데이터를 조회하는 기능도 제공합니다. 이는 런타임에 메타데이터를 저장하는 커스텀 데코레이터를 사용할 때 특히 유용합니다. 예를 들어, 특정 메타데이터로 프로바이더를 태그 하는 커스텀 데코레이터를 사용하는 경우를 생각해 봅시다:

import { DiscoveryService } from '@nestjs/core';

export const FeatureFlag = DiscoveryService.createDecorator();

 

이 데코레이터를 서비스에 적용하면, 해당 서비스에 메타데이터를 저장할 수 있으며, 이 메타데이터는 나중에 조회할 수 있습니다.

import { Injectable } from '@nestjs/common';
import { FeatureFlag } from './custom-metadata.decorator';

@Injectable()
@FeatureFlag('experimental')
export class CustomService {}

 

이와 같은 방식으로 메타데이터가 프로바이더에 부착되면, DiscoveryService를 사용해 해당 메타데이터 값에 따라 프로바이더를 쉽게 필터링할 수 있습니다. 다음 코드는 특정 메타데이터 값으로 태그 된 프로바이더를 조회하는 방법을 보여줍니다:

const providers = this.discoveryService.getProviders();

const [provider] = providers.filter(
  (item) =>
    this.discoveryService.getMetadataByDecorator(FeatureFlag, item) ===
    'experimental',
);

console.log(
  'Providers with the "experimental" feature flag metadata:',
  provider,
);

결론

DiscoveryService는 NestJS 애플리케이션에서 런타임 리플렉션을 가능하게 해주는 다재다능하고 강력한 도구입니다. 프로바이더, 컨트롤러, 메타데이터를 동적으로 탐색할 수 있도록 함으로써, 확장 가능한 프레임워크, 플러그인, 자동화 기반 기능을 구축하는 데 핵심적인 역할을 합니다. 프로바이더를 스캔 및 처리하거나, 고급 처리를 위한 메타데이터를 추출하거나, 모듈화 되고 확장 가능한 아키텍처를 만들고자 할 때, DiscoveryService는 이러한 목표를 달성하기 위한 효율적이고 구조화된 방식을 제공합니다.

Reference

• Nest.js | Lifecycle events
• Nest.js | Discovery service