[Nest.js] Fundamentals | Lazy-loading modules, Execution context

모듈 지연 로딩

기본적으로 모듈은 즉시 로드 (eagerly loaded) 되며, 이는 애플리케이션이 시작되면 모든 모듈이 즉시 로드된다는 의미입니다. 대부분의 애플리케이션에는 이 방식으로 충분하지만, 서버리스 환경에서 실행되는 앱이나 워커에서는 시작 지연 시간 ("콜드 스타트")이 중요하므로 병목이 될 수 있습니다.

 

지연 로딩을 사용하면 특정 서버리스 함수 호출에 필요한 모듈만 로드함으로써 부트스트랩 시간을 줄일 수 있습니다. 또한, 서버리스 함수가 "웜 (warm)" 상태가 되었을 때 다른 모듈을 비동기로 로드함으로써 이후 호출의 부트스트랩 시간을 더욱 단축할 수 있습니다 (지연된 모듈 등록).

힌트
Angular 프레임워크에 익숙하다면 "lazy-loading modules (지연 로딩 모듈)"이라는 용어를 본 적이 있을 수 있습니다. 하지만 Nest에서는 이 기술이 기능적으로 다르므로, 단지 이름만 비슷할 뿐 완전히 다른 기능으로 이해해야 합니다.

주의
지연 로딩된 모듈 및 서비스에서는 라이프사이클 훅 메서드가 호출되지 않는다는 점에 유의하세요.

시작하기

Nest에서는 LazyModuleLoader 클래스를 통해 필요할 때 모듈을 로드할 수 있으며, 일반적인 방식으로 클래스에 주입하여 사용할 수 있습니다.

@Injectable()
export class CatsService {
  constructor(private lazyModuleLoader: LazyModuleLoader) {}
}

힌트
LazyModuleLoader 클래스는 @nestjs/core 패키지에서 import 됩니다.

 

또는 애플리케이션 부트스트랩 파일 (main.ts) 내에서 LazyModuleLoader 프로바이더에 대한 참조를 다음과 같이 얻을 수도 있습니다:

// "app"은 Nest 애플리케이션 인스턴스를 의미합니다.
const lazyModuleLoader = app.get(LazyModuleLoader);

 

이제 아래와 같은 방식으로 원하는 모듈을 로드할 수 있습니다:

const { LazyModule } = await import('./lazy.module');
const moduleRef = await this.lazyModuleLoader.load(() => LazyModule);

힌트
"지연 로딩된" 모듈은 최초 LazyModuleLoader#load 메서드가 호출될 때 캐시에 저장됩니다. 이는 이후 동일한 모듈을 로드하려는 모든 시도가 매우 빠르게 캐시 된 인스턴스를 반환하며, 모듈을 다시 로드하지 않는다는 것을 의미합니다.

Load "LazyModule" attempt: 1
time: 2.379ms
Load "LazyModule" attempt: 2
time: 0.294ms
Load "LazyModule" attempt: 3
time: 0.303ms​

또한 "지연 로딩된" 모듈은 애플리케이션 부트스트랩 시 즉시 로드된 모듈들과 이후에 등록된 다른 지연 로딩 모듈들과 동일한 모듈 그래프를 공유합니다.

 

lazy.module.ts 는 일반 Nest 모듈을 export 하는 TypeScript 파일이며, 별도의 추가 변경은 필요하지 않습니다.

 

LazyModuleLoader#load 메서드는 LazyModule의 모듈 참조를 반환하며, 이를 통해 내부의 프로바이더 목록을 탐색하고, 주입 토큰을 조회 키로 사용하여 원하는 프로바이더에 접근할 수 있습니다.

 

예를 들어, 다음과 같은 정의를 가진 LazyModule이 있다고 가정해 봅시다:

@Module({
  providers: [LazyService],
  exports: [LazyService],
})
export class LazyModule {}

힌트
지연 로딩된 모듈은 전역 모듈로 등록할 수 없습니다. 이는 모든 정적 모듈이 이미 인스턴스화된 이후에 필요시 로드되기 때문에 전역 등록이 의미가 없기 때문입니다. 마찬가지로, 전역으로 등록된 enhancer들 (guard, interceptor 등)도 정상적으로 동작하지 않습니다.

 

이제 다음과 같이 LazyService 프로바이더에 대한 참조를 얻을 수 있습니다.

const { LazyModule } = await import('./lazy.module');
const moduleRef = await this.lazyModuleLoader.load(() => LazyModule);

const { LazyService } = await import('./lazy.service');
const lazyService = moduleRef.get(LazyService);

주의
Webpack을 사용하는 경우 tsconfig.json 파일을 반드시 업데이트해야 합니다. compilerOptions.module을 "esnext"로 설정하고, compilerOptions.moduleResolution 속성에 "node" 값을 추가하세요:

{
  "compilerOptions": {
    "module": "esnext",
    "moduleResolution": "node",
    ...
  }
}​

이 설정을 통해 코드 분할 (code splitting) 기능을 활용할 수 있습니다.

 

컨트롤러, 게이트웨이, 리졸버의 지연 로딩

Nest에서 컨트롤러 (또는 GraphQL 애플리케이션의 리졸버)는 경로/라우트/토픽 (또는 쿼리/뮤테이션)의 집합을 나타내므로, LazyModuleLoader 클래스를 사용하여 이들을 지연 로딩할 수는 없습니다.

주의
지연 로딩된 모듈 내부에 등록된 컨트롤러, 리졸버, 게이트웨이는 예상대로 동작하지 않습니다. 마찬가지로 MiddlewareConsumer 인터페이스를 구현하여 미들웨어를 온디맨드 방식으로 등록하는 것도 불가능합니다.

 

예를 들어, Fastify 드라이버 (@nestjs/platform-fastify 패키지 사용)를 기반으로 REST API (HTTP 애플리케이션)를 구축한다고 가정해 봅시다. Fastify는 애플리케이션이 준비되고 메시지를 수신하기 시작한 이후에는 라우트를 등록할 수 없습니다. 즉, 모듈의 컨트롤러에 등록된 라우트 매핑을 분석하더라도, 지연 로딩된 라우트는 런타임에 등록할 방법이 없기 때문에 접근할 수 없습니다.

 

마찬가지로, @nestjs/microservices 패키지에서 제공하는 일부 전송 전략 (예: Kafka, gRPC, RabbitMQ 등)은 연결이 설정되기 전에 특정 토픽/채널에 대한 구독 및 수신 설정이 필요합니다. 애플리케이션이 메시지 수신을 시작한 이후에는 새로운 토픽에 대해 구독/수신할 수 없습니다.

 

마지막으로, @nestjs/graphql 패키지에서 code-first 방식을 사용할 경우, 메타데이터를 기반으로 GraphQL 스키마가 동적으로 생성됩니다. 이는 모든 관련 클래스가 사전에 로드되어 있어야 함을 의미합니다. 그렇지 않으면 올바른 스키마를 생성할 수 없습니다.

일반적인 사용 사례

지연 로딩 모듈은 주로 워커, 크론 잡, 람다 및 서버리스 함수, 웹훅 등이 입력 인자 (라우트 경로, 날짜, 쿼리 파라미터 등)에 따라 서로 다른 서비스 (다른 로직)를 실행해야 할 때 사용됩니다. 반면, 애플리케이션 시작 시간이 크게 중요하지 않은 모놀리식 애플리케이션에서는 지연 로딩 모듈이 큰 의미를 갖지 않을 수 있습니다.

실행 컨텍스트

Nest는 여러 애플리케이션 컨텍스트 (예: Nest HTTP 서버 기반, 마이크로서비스, WebSocket 애플리케이션 컨텍스트) 에서 동작하는 애플리케이션을 쉽게 작성할 수 있도록 돕는 여러 유틸리티 클래스를 제공합니다. 이러한 유틸리티는 현재 실행 컨텍스트에 대한 정보를 제공하며, 이를 활용해 다양한 컨트롤러, 메서드, 실행 컨텍스트 전반에서 동작할 수 있는 범용적인 가드, 필터, 인터셉터를 구축할 수 있습니다.

 

이번 장에서는 ArgumentsHost와 ExecutionContext라는 두 가지 클래스를 다룹니다.

ArgumentsHost 클래스

ArgumentsHost 클래스는 핸들러에 전달되는 인자를 가져오는 메서드를 제공합니다. 이를 통해 어떤 컨텍스트 (예: HTTP, RPC (마이크로서비스), WebSocket)에서 인자를 가져올지 선택할 수 있습니다. Nest 프레임워크는 ArgumentsHost 인스턴스를 제공하며, 일반적으로 host라는 매개변수로 참조되며, 예외 필터의 catch() 메서드처럼 접근이 필요한 곳에서 사용됩니다.

 

ArgumentsHost는 단순히 핸들러 인자에 대한 추상화 역할을 합니다. 예를 들어, HTTP 서버 애플리케이션 (@nestjs/platform-express 사용 시)에는 host 객체가 Express의 [request, response, next] 배열을 캡슐화하며, 여기서 request는 요청 객체, response는 응답 객체, next는 요청-응답 사이클을 제어하는 함수입니다. 반면, GraphQL 애플리케이션에서는 host 객체가 [root, args, context, info] 배열을 포함합니다.

현재 애플리케이션 컨텍스트

여러 애플리케이션 컨텍스트 전반에서 실행될 수 있는 범용 가드, 필터, 인터셉터를 작성할 때는, 현재 메서드가 어떤 애플리케이션 타입에서 실행되고 있는지를 판별할 수 있는 방법이 필요합니다. 이를 위해 ArgumentsHost의 getType() 메서드를 사용합니다.

if (host.getType() === 'http') {
  // 일반 HTTP 요청(REST) 컨텍스트에서만 중요한 작업 수행
} else if (host.getType() === 'rpc') {
  // 마이크로서비스 요청 컨텍스트에서만 중요한 작업 수행
} else if (host.getType<GqlContextType>() === 'graphql') {
  // GraphQL 요청 컨텍스트에서만 중요한 작업 수행
}

힌트
GqlContextType은 @nestjs/graphql 패키지에서 import 됩니다.

 

애플리케이션 타입을 확인할 수 있게 되면, 아래와 같이 보다 범용적인 컴포넌트를 작성할 수 있습니다.

호스트 핸들러 매개변수

호스트 객체의 getArgs() 메서드를 사용하면, 핸들러에 전달된 인자의 배열을 가져올 수 있습니다.

const [req, res, next] = host.getArgs();

 

getArgByIndex() 메서드를 사용하면 특정 인덱스의 인자만 선택적으로 가져올 수 있습니다.

const request = host.getArgByIndex(0);
const response = host.getArgByIndex(1);

 

이 예제들에서는 요청 및 응답 객체를 인덱스로 가져왔지만, 이는 특정 실행 컨텍스트에 애플리케이션이 결합되므로 일반적으로 권장되지 않습니다. 대신, 호스트 객체의 유틸리티 메서드를 사용하여 현재 애플리케이션에 적합한 실행 컨텍스트로 전환함으로써 코드를 더욱 견고하고 재사용 가능하게 만들 수 있습니다. 아래는 이러한 컨텍스트 전환 유틸리티 메서드입니다.

/**
 * RPC 컨텍스트로 전환합니다.
 */
switchToRpc(): RpcArgumentsHost;
/**
 * HTTP 컨텍스트로 전환합니다.
 */
switchToHttp(): HttpArgumentsHost;
/**
 * WebSocket 컨텍스트로 전환합니다.
 */
switchToWs(): WsArgumentsHost;

 

앞선 예제를 switchToHttp() 메서드를 사용하여 다시 작성해 보겠습니다. host.switchToHttp() 호출은 HTTP 애플리케이션 컨텍스트에 적합한 HttpArgumentsHost 객체를 반환합니다. HttpArgumentsHost 객체에는 원하는 객체를 추출할 수 있는 유용한 메서드 두 가지가 있으며, 이 경우에는 Express 타입 단언을 사용하여 네이티브 Express 타입 객체를 반환합니다:

const ctx = host.switchToHttp();
const request = ctx.getRequest<Request>();
const response = ctx.getResponse<Response>();

 

마찬가지로 WsArgumentsHost와 RpcArgumentsHost도 각각 WebSocket 및 마이크로서비스 컨텍스트에 적합한 객체를 반환하는 메서드를 제공합니다. 아래는 WsArgumentsHost의 메서드입니다:

export interface WsArgumentsHost {
  /**
   * 데이터 객체를 반환합니다.
   */
  getData<T>(): T;
  /**
   * 클라이언트 객체를 반환합니다.
   */
  getClient<T>(): T;
}

 

다음은 RpcArgumentsHost의 메서드입니다:

export interface RpcArgumentsHost {
  /**
   * 데이터 객체를 반환합니다.
   */
  getData<T>(): T;

  /**
   * 컨텍스트 객체를 반환합니다.
   */
  getContext<T>(): T;
}

 

ExecutionContext 클래스는 ArgumentsHost를 상속하며, 현재 실행 프로세스에 대한 추가 정보를 제공합니다. ArgumentsHost와 마찬가지로, Nest는 canActive() 메서드 (guard에서)나 intercept() 메서드 (interceptor에서)와 같은 필요한 곳에 ExecutionContext 인스턴스를 제공합니다. 이 클래스는 다음과 같은 메서드들을 제공합니다:

export interface ExecutionContext extends ArgumentsHost {
  /**
   * 현재 핸들러가 속한 컨트롤러 클래스의 타입을 반환합니다.
   */
  getClass<T>(): Type<T>;
  /**
   * 요청 파이프라인에서 다음으로 호출될 핸들러(메서드)를 반환합니다.
   */
  getHandler(): Function;
}

 

getHandler() 메서드는 곧 호출될 핸들러에 대한 참조를 반환합니다. getClass() 메서드는 해당 핸들러가 속한 컨트롤러 클래스의 타입을 반환합니다. 예를 들어, HTTP 컨텍스트에서 현재 처리 중인 요청이 CatsController의 create() 메서드에 바인딩된 POST 요청이라면, getHandler()는 create() 메서드의 참조를 반환하고, getClass()는 CatsController 클래스 (인스턴스가 아님)를 반환합니다.

const methodKey = ctx.getHandler().name; // "create"
const className = ctx.getClass().name; // "CatsController"

 

현재 클래스와 핸들러 메서드에 대한 참조에 접근할 수 있는 기능은 큰 유연성을 제공합니다. 무엇보다도, guard나 interceptor 내부에서 Reflector#createDecorator로 생성된 커스텀 데코레이터나 Nest 내장 @SetMetadata() 데코레이터로 설정된 메타데이터에 접근할 수 있는 기회를 제공합니다. 이러한 활용 사례는 아래에서 다룹니다.

리플렉션과 메타데이터

Nest는 Reflector#createDecorator 메서드로 생성한 데코레이터와 내장 @SetMetadata() 데코레이터를 통해 라우트 핸들러에 커스텀 메타데이터를 부착할 수 있는 기능을 제공합니다. 이 섹션에서는 두 가지 접근 방식을 비교하고, 가드나 인터셉터 내부에서 메타데이터에 접근하는 방법을 살펴보겠습니다.

 

Reflector#createDecorator를 사용해 타입이 강제된 데코레이터를 만들려면, 타입 인자를 지정해야 합니다. 예를 들어, 문자열 배열을 인자로 받는 Roles 데코레이터를 만들어 보겠습니다.

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

export const Roles = Reflector.createDecorator<string[]>();

 

여기서 Roles 데코레이터는 string[] 타입의 인자를 하나 받는 함수입니다.

 

이제 이 데코레이터를 사용하려면, 단순히 핸들러에 데코레이터를 적용하면 됩니다:

@Post()
@Roles(['admin'])
async create(@Body() createCatDto: CreateCatDto) {
  this.catsService.create(createCatDto);
}

 

여기서는 create() 메서드에 Roles 데코레이터 메타데이터를 부착하여, 오직 admin 역할을 가진 사용자만 이 라우트에 접근할 수 있음을 나타냅니다.

 

이제 해당 라우트의 역할 (커스텀 메타데이터)에 접근하려면, Reflector 헬퍼 클래스를 다시 사용하면 됩니다. Reflector는 일반적인 방식으로 클래스에 주입할 수 있습니다:

@Injectable()
export class RolesGuard {
  constructor(private reflector: Reflector) {}
}

힌트
Reflector 클래스는 @nestjs/core 패키지에서 import 됩니다.

 

이제 핸들러의 메타데이터를 읽으려면, get() 메서드를 사용하면 됩니다:

const roles = this.reflector.get(Roles, context.getHandler());

 

Reflector#get 메서드는 두 개의 인자를 받아 메타데이터에 쉽게 접근할 수 있게 해 줍니다: 하나는 데코레이터 참조이고, 다른 하나는 메타데이터를 추출할 대상 (context)입니다. 이 예제에서는 Roles 데코레이터 (위의 roles.decorator.ts 파일 참조)가 지정된 데코레이터이고, context는 context.getHandler() 호출을 통해 제공되며, 이는 현재 처리 중인 라우트 핸들러에 대한 메타데이터를 추출하게 됩니다. 참고로, getHandler()는 라우트 핸들러 함수에 대한 참조를 반환합니다.

 

또한, 컨트롤러 클래스의 모든 라우트에 적용되도록 메타데이터를 컨트롤러 수준에서 설정할 수도 있습니다.

@Roles(['admin'])
@Controller('cats')
export class CatsController {}

 

이 경우에는 메타데이터를 컨트롤러 수준에서 추출하기 위해, context.getHandler() 대신 context.getClass()를 두 번째 인자로 전달합니다. 즉, 메타데이터를 추출할 context로 컨트롤러 클래스를 제공하는 방식입니다.

const roles = this.reflector.get(Roles, context.getClass());

 

여러 수준에서 메타데이터를 제공할 수 있기 때문에, 여러 context로부터 메타데이터를 추출하고 병합해야 할 수도 있습니다. 이를 돕기 위해 Reflector 클래스는 두 가지 유틸리티 메서드를 제공합니다. 이 메서드들은 컨트롤러와 메서드의 메타데이터를 한 번에 추출하고, 서로 다른 방식으로 병합합니다.

 

다음과 같은 상황을 생각해 봅시다. Roles 메타데이터를 컨트롤러와 메서드 양쪽에 모두 설정한 경우입니다.

@Roles(['user'])
@Controller('cats')
export class CatsController {
  @Post()
  @Roles(['admin'])
  async create(@Body() createCatDto: CreateCatDto) {
    this.catsService.create(createCatDto);
  }
}

 

기본 역할을 'user'로 지정하고, 특정 메서드에만 선택적으로 이를 덮어쓰고자 한다면 getAllAndOverride() 메서드를 사용하는 것이 적합합니다.

const roles = this.reflector.getAllAndOverride(Roles, [context.getHandler(), context.getClass()]);

 

이 코드가 create() 메서드의 컨텍스트에서 실행된다면, roles는 ['admin']을 포함하게 됩니다.

 

양쪽의 메타데이터를 모두 가져와 병합하려면(배열과 객체를 모두 병합), getAllAndMerge() 메서드를 사용하세요.

const roles = this.reflector.getAllAndMerge(Roles, [context.getHandler(), context.getClass()]);

 

이렇게 하면 roles는 ['user', 'admin']을 포함하게 됩니다.

 

이 두 가지 병합 메서드 모두에서, 첫 번째 인자로는 메타데이터 키를 전달하고, 두 번째 인자로는 메타데이터 대상 컨텍스트의 배열 (즉, getHandler() 및 또는 getClass() 메서드 호출)을 전달합니다.

저수준 접근

앞서 언급했듯이, Reflector#createDecorator를 사용하는 대신, 내장된 @SetMetadata() 데코레이터를 사용하여 핸들러에 메타데이터를 설정할 수도 있습니다.

@Post()
@SetMetadata('roles', ['admin'])
async create(@Body() createCatDto: CreateCatDto) {
  this.catsService.create(createCatDto);
}

힌트
@SetMetadata() 데코레이터는 @nestjs/common 패키지에서 import 합니다.

 

위와 같이 구성하면, roles 메타데이터 키에 ['admin'] 값을 할당하여 create() 메서드에 메타데이터를 설정하게 됩니다. 이렇게 작동은 하지만, @SetMetadata()를 라우트에서 직접 사용하는 것은 권장되지 않습니다. 대신 아래와 같이 사용자 정의 데코레이터를 생성하는 것이 좋습니다.

import { SetMetadata } from '@nestjs/common';

export const Roles = (...roles: string[]) => SetMetadata('roles', roles);

 

이 접근 방식은 훨씬 더 깔끔하고 가독성도 좋으며, Reflector#createDecorator 방식과 유사한 면이 있습니다. 차이점은 @SetMetadata를 사용하면 메타데이터의 키와 값에 대해 더 많은 제어가 가능하고, 인자를 여러 개 받을 수 있는 데코레이터도 만들 수 있다는 점입니다.

 

이제 우리가 만든 커스텀 @Roles() 데코레이터를 사용하여 create() 메서드를 데코레이트 할 수 있습니다.

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

 

라우트의 역할 (role) 정보 (커스텀 메타데이터)에 접근하기 위해, 다시 Reflector 헬퍼 클래스를 사용할 것입니다.

@Injectable()
export class RolesGuard {
  constructor(private reflector: Reflector) {}
}

힌트
Reflector 클래스는 @nestjs/core 패키지에서 import 합니다.

 

이제 핸들러의 메타데이터를 읽기 위해 get() 메서드를 사용합니다.

const roles = this.reflector.get<string[]>('roles', context.getHandler());

 

여기서는 데코레이터 참조를 전달하는 대신, 첫 번째 인자로 메타데이터 키 (이 경우 'roles')를 전달합니다. 나머지는 Reflector#createDecorator 예제와 동일합니다.

Reference

• Nest.js | Lazy-loading modules
• Nest.js | Execution context