[Nest.js] Overview - Interceptors, Custom decorators

인터셉터

인터셉터 (interceptor)는 @Injectable() 데코레이터가 붙은 클래스이며, NestInterceptor 인터페이스를 구현합니다.

 

인터셉터는 관점 지향 프로그래밍 (AOP) 기법에서 영감을 받은 유용한 기능들을 제공합니다. 이를 통해 다음과 같은 작업이 가능합니다:

• 메서드 실행 전/후에 추가 로직을 바인딩
• 함수에서 반환된 결과를 변환
• 함수에서 던진 예외를 변환
• 기본 함수 동작을 확장
• 특정 조건에 따라 함수 자체를 완전히 대체 (예: 캐싱 목적)

기본 사항

각 인터셉터는 intercept() 메서드를 구현하며, 이 메서드는 두 개의 인자를 받습니다. 첫 번째 인자는 ExecutionContext 인스턴스이며, 이는 가드에서 사용하는 것과 동일한 객체입니다. ExecutionContext는 ArgumentsHost를 상속받습니다. ArgumentsHost는 앞서 예외 필터 챕터에서 살펴본 바와 같이, 원래 핸들러에 전달된 인자들을 감싸는 래퍼 객체이며, 애플리케이션의 유형에 따라 다양한 인자 배열을 포함합니다. 이 주제에 대해서는 예외 필터 섹션을 다시 참고할 수 있습니다.

실행 컨텍스트

ExecutionContext는 ArgumentsHost를 상속함으로써 현재 실행 과정에 대한 추가적인 세부 정보를 제공하는 여러 보조 메서드들도 함께 제공합니다. 이러한 정보들은 보다 일반적인 인터셉터를 구축할 때 유용하며, 다양한 컨트롤러, 메서드, 실행 컨텍스트에서 동작할 수 있도록 도와줍니다. ExecutionContext에 대해 더 자세히 알아보려면 여기를 참고하세요.

핸들러 호출

두 번째 인자는 CallHandler입니다. CallHandler 인터페이스는 handle() 메서드를 구현하고 있으며, 이 메서드를 사용하여 인터셉터 내부에서 라우트 핸들러 메서드를 호출할 수 있습니다. 만약 intercept() 메서드 구현 내에서 handle() 메서드를 호출하지 않으면, 해당 라우트 핸들러 메서드는 전혀 실행되지 않습니다.

 

이러한 구조 덕분에 intercept() 메서드는 요청/응답 스트림을 효과적으로 감싸는 (wrapper) 역할을 하게 됩니다. 결과적으로, 최종 라우트 핸들러가 실행되기 전과 후 모두에 사용자 정의 로직을 구현할 수 있습니다. handle() 호출 전에 실행되는 코드를 작성하는 것은 분명하지만, 그 이후에 어떤 작업을 수행할 수 있을까요? 이는 handle()이 Observable을 반환하기 때문에, RxJS의 강력한 연산자들을 활용하여 응답을 추가로 조작할 수 있습니다. AOP (관점 지향 프로그래밍) 용어로, 라우트 핸들러를 호출하는 시점 (즉, handle() 호출)은 포인트컷 (Pointcut)이라고 하며, 이는 우리가 추가 로직을 삽입할 수 있는 지점을 나타냅니다.

 

예를 들어, POST /cats 요청이 있다고 가정합시다. 이 요청은 CatsController에 정의된 create() 핸들러를 대상으로 합니다. 만약 도중에 handle()을 호출하지 않는 인터셉터가 실행되면, create() 메서드는 전혀 실행되지 않습니다. 그러나 handle()이 호출되고 그 Observable이 반환되면, create() 핸들러가 실행되며, 그 응답 스트림을 통해 추가적인 처리를 수행한 후 최종 결과를 클라이언트에게 반환할 수 있습니다.

관점 가로채기 (Aspect interception)

우리가 살펴볼 첫 번째 사용 사례는 인터셉터를 사용하여 사용자 상호작용을 로깅하는 것입니다 (예: 사용자 호출 저장, 비동기 이벤트 디스패치, 타임스탬프 계산 등). 아래는 간단한 LoggingInterceptor 예시입니다:

import { Injectable, NestInterceptor, ExecutionContext, CallHandler } from '@nestjs/common';
import { Observable } from 'rxjs';
import { tap } from 'rxjs/operators';

@Injectable()
export class LoggingInterceptor implements NestInterceptor {
  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
    console.log('Before...');

    const now = Date.now();
    return next
      .handle()
      .pipe(
        tap(() => console.log(`After... ${Date.now() - now}ms`)),
      );
  }
}

힌트
NestInterceptor<T, R>는 제네릭 인터페이스로, 여기서 T는 Observable<T>의 타입 (응답 스트림을 지원함)을 나타내며, R은 Observable<R>에 감싸진 값의 타입을 의미합니다.

알림
인터셉터는 컨트롤러, 프로바이더, 가드 등과 마찬가지로 생성자를 통해 의존성을 주입받을 수 있습니다.

 

handle()은 RxJS Observable을 반환하므로, 우리는 스트림을 조작하기 위해 다양한 연산자들을 사용할 수 있습니다. 위 예제에서는 tap() 연산자를 사용했는데, 이 연산자는 Observable 스트림이 정상적으로 종료되거나 예외적으로 종료될 때 익명 로깅 함수를 호출하지만, 그 외에는 응답 사이클에 간섭하지 않습니다.

인터셉터 연결하기

인터셉터를 설정하려면 @nestjs/common 패키지에서 가져온 @UseInterceptors() 데코레이터를 사용합니다. 파이프나 가드처럼 인터셉터도 컨트롤러 범위, 메서드 범위, 또는 전역 범위로 설정할 수 있습니다.

@UseInterceptors(LoggingInterceptor)
export class CatsController {}

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

 

위와 같은 구성 방식으로 설정하면, CatsController에 정의된 각 라우트 핸들러는 LoggingInterceptors를 사용하게 됩니다. 누군가 GET /cats 엔드포인트를 호출하면, 표준 출력에 다음과 같은 출력이 나타납니다:

Before...
After... 1ms

 

여기서 우리는 LoggingInterceptor 클래스를 전달했습니다 (인스턴스가 아닌). 이렇게 하면 인스턴스화 책임을 프레임워크에 위임하게 되어 의존성 주입이 가능해집니다. 파이프 (pipes), 가드 (guards), 예외 필터 (exception filters)와 마찬가지로, 인라인 (in-place) 인스턴스를 전달할 수도 있습니다.

@UseInterceptors(new LoggingInterceptor())
export class CatsController {}

 

앞서 언급했듯이, 위의 구성은 해당 컨트롤러에 선언된 모든 핸들러에 인터셉터를 적용합니다. 인터셉터의 범위를 단일 메서드로 제한하고 싶다면, 단순히 해당 메서드에 데코레이터를 적용하면 됩니다.

 

전역 인터셉터 (global interceptor)를 설정하려면, Nest 애플리케이션 인스턴스의 useGlobalInterceptors() 메서드를 사용합니다:

const app = await NestFactory.create(AppModule);
app.useGlobalInterceptors(new LoggingInterceptor());

 

전역 인터셉터는 애플리케이션 전체, 즉 모든 컨트롤러와 모든 라우트에 걸쳐 사용됩니다. 의존성 주입 측면에서 보면, 위의 예시처럼 useGlobalInterceptors()를 사용하여 모듈 외부에서 등록된 전역 인터셉터는 의존성을 주입받을 수 없습니다. 이는 해당 바인딩이 어떤 모듈의 컨텍스트 밖에서 수행되기 때문입니다. 이 문제를 해결하려면, 다음과 같은 구성 방식으로 어떤 모듈 내부에서 인터셉터를 직접 설정할 수 있습니다:

import { Module } from '@nestjs/common';
import { APP_INTERCEPTOR } from '@nestjs/core';

@Module({
  providers: [
    {
      provide: APP_INTERCEPTOR,
      useClass: LoggingInterceptor,
    },
  ],
})
export class AppModule {}

힌트
이 방법을 사용하여 인터셉터에 의존성 주입을 수행할 때, 이 구성이 사용된 모듈이 어디든지 간에 해당 인터셉터는 실제로 전역 (Global)으로 적용된다는 점에 유의해야 합니다. 이 작업은 인터셉터 (위 예시에서는 LoggingInterceptor)가 정의된 모듈에서 수행하는 것이 좋습니다. 또한 useClass만이 커스텀 프로바이더를 등록하는 유일한 방법은 아닙니다. 더 다양한 방법을 여기에서 확인할 수 있습니다. 

응답 매핑

handle() 메서드는 Observable을 반환한다는 것을 우리는 이미 알고 있습니다. 이 스트림은 라우트 핸들러가 반환한 값을 포함하므로, RxJS의 map() 연산자를 사용하여 쉽게 변형할 수 있습니다.

주의
응답 매핑 기능은 라이브러리 고유의 응답 전략과 함께 사용할 수 없습니다. (@Res() 객체를 직접 사용하는 것은 금지됩니다.)

 

TransformInterceptor를 생성해 봅시다. 이 인터셉터는 각 응답을 단순하게 수정하여 동작 과정을 보여줄 것입니다. RxJS의 map() 연산자를 사용하여 응답 객체를 새로 생성된 객체의 data 속성에 할당하고, 이 새 객체를 클라이언트에 반환합니다.

import { Injectable, NestInterceptor, ExecutionContext, CallHandler } from '@nestjs/common';
import { Observable } from 'rxjs';
import { map } from 'rxjs/operators';

export interface Response<T> {
  data: T;
}

@Injectable()
export class TransformInterceptor<T> implements NestInterceptor<T, Response<T>> {
  intercept(context: ExecutionContext, next: CallHandler): Observable<Response<T>> {
    return next.handle().pipe(map(data => ({ data })));
  }
}

힌트
Nest의 인터셉터는 intercept() 메서드가 동기식이든 비동기식이든 모두 동작합니다. 필요하다면 메서드를 async로 간단히 변경하여 사용할 수 있습니다.

 

위와 같이 구성하면, 누군가 GET /cats 엔드포인트를 호출했을 때의 응답은 다음과 같습니다 (해당 라우트 핸들러가 빈 배열 []을 반환한다고 가정할 경우):

{
  "data": []
}

 

인터셉터는 애플리케이션 전반에 걸쳐 반복적으로 발생하는 요구 사항에 대해 재사용 가능한 솔루션을 만드는 데 큰 가치를 가집니다. 예를 들어, 모든 null 값을 빈 문자열 ''로 변환해야 하는 상황을 생각해 봅시다. 이 작업은 단 한 줄의 코드로 수행할 수 있으며, 인터셉터를 전역으로 바인딩하면 등록된 모든 핸들러에서 자동으로 적용합니다.

import { Injectable, NestInterceptor, ExecutionContext, CallHandler } from '@nestjs/common';
import { Observable } from 'rxjs';
import { map } from 'rxjs/operators';

@Injectable()
export class ExcludeNullInterceptor implements NestInterceptor {
  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
    return next
      .handle()
      .pipe(map(value => value === null ? '' : value ));
  }
}

예외 매핑

또 다른 흥미로운 사용 사례는 RxJS의 catchError() 연산자를 활용하여 발생한 예외를 오버라이드 (재정의)하는 것입니다.

import {
  Injectable,
  NestInterceptor,
  ExecutionContext,
  BadGatewayException,
  CallHandler,
} from '@nestjs/common';
import { Observable, throwError } from 'rxjs';
import { catchError } from 'rxjs/operators';

@Injectable()
export class ErrorsInterceptor implements NestInterceptor {
  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
    return next
      .handle()
      .pipe(
        catchError(err => throwError(() => new BadGatewayException())),
      );
  }
}

스트림 재정의

경우에 따라 핸들러의 호출 자체를 완전히 막고, 대신 다른 값을 반환하고 싶을 때가 있습니다. 그 대표적인 예로는 응답 시간을 개선하기 위한 캐시 (cache) 구현이 있습니다. 이제 캐시에서 응답을 반환하는 간단한 캐시 인터셉터 예제를 살펴보겠습니다. 실제 상황에서는 TTL, 캐시 무효화, 캐시 크기 등의 요소도 고려해야 하지만, 여기서는 개념을 설명하기 위한 기본적인 예제만 제공합니다.

import { Injectable, NestInterceptor, ExecutionContext, CallHandler } from '@nestjs/common';
import { Observable, of } from 'rxjs';

@Injectable()
export class CacheInterceptor implements NestInterceptor {
  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
    const isCached = true;
    if (isCached) {
      return of([]);
    }
    return next.handle();
  }
}

 

CacheInterceptor는 현재 isCached 변수와 응답 [] 모두 하드코딩되어 있습니다. 여기서 중요한 점은 RxJS의 of() 연산자를 사용하여 새로운 스트림을 반환한다는 것입니다. 따라서 라우트 핸들러는 전혀 호출되지 않습니다. CacheInterceptor를 사용하는 엔드포인트가 호출되면, 하드코딩된 빈 배열 응답이 즉시 반환됩니다. 보다 범용적인 솔루션을 만들기 위해서는 Reflector를 활용하고 커스텀 데코레이터를 생성할 수 있습니다. Reflector에 대한 설명은 Guards 챕터에서 잘 다뤄지고 있습니다.

다른 연산자들

RxJS 연산자를 사용하여 스트림을 조작할 수 있다는 것은 다양한 기능을 가능하게 합니다. 또 하나의 일반적인 사용 사례를 살펴보겠습니다. 라우트 요청에 대해 타임아웃 처리를 하고 싶다고 가정해 봅시다. 일정 시간이 지나도록 엔드포인트가 아무것도 반환하지 않으면, 에러 응답으로 요청을 종료하고자 할 수 있습니다. 다음과 같은 구성으로 이를 구현할 수 있습니다:

import { Injectable, NestInterceptor, ExecutionContext, CallHandler, RequestTimeoutException } from '@nestjs/common';
import { Observable, throwError, TimeoutError } from 'rxjs';
import { catchError, timeout } from 'rxjs/operators';

@Injectable()
export class TimeoutInterceptor implements NestInterceptor {
  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
    return next.handle().pipe(
      timeout(5000),
      catchError(err => {
        if (err instanceof TimeoutError) {
          return throwError(() => new RequestTimeoutException());
        }
        return throwError(() => err);
      }),
    );
  };
};

 

5초가 지나면 요청 처리가 취소됩니다. 또한 RequestTimeoutException을 던지기 전에 사용자 정의 로직을 추가하여 (예를 들어) 자원을 해제하는 등의 처리를 할 수도 있습니다.

---

커스텀 데코레이터

Nest는 데코레이터라는 언어 기능을 중심으로 구축되어 있습니다. 데코레이터는 많은 주요 프로그래밍 언어에서 잘 알려진 개념이지만, JavaScript 세계에서는 비교적 새로운 기능입니다. 데코레이터가 어떻게 작동하는지 더 잘 이해하기 위해서는 관련 문서를 읽어보는 것을 권장합니다. 다음은 데코레이터에 대한 간단한 정의입니다:

ES2016 데코레이터는 함수를 반환하는 표현식으로, 대상 (target), 이름 (name), 속성 설명자 (property descriptor)를 인자로 받을 수 있습니다. 데코레이터는 @ 기호를 앞에 붙여 데코레이터를 적용할 대상을 가장 위에 위치시켜 사용합니다. 데코레이터는 클래스, 메서드, 속성 중 어느 곳에도 정의될 수 있습니다.

매개변수 데코레이터

Nest는 HTTP 라우트 핸들러와 함께 사용할 수 있는 유용한 매개변수 데코레이터들을 제공합니다. 아래는 제공되는 데코레이터 목록과 그것이 나타내는 순수 Express (또는 Fastify) 객체들입니다.

@Request(), @Req()	req
@Response(), @Res()	res
@Next()	next
@Session()	req.session
@Param(key?: string)	req.params / req.params[key]
@Body(key?: string)	req.body / req.body[key]
@Query(key?: string)	req.query / req.query[key]
@Headers(key?: string)	req.headers / req.headers[name]
@Ip()	req.ip
@HostParam()	req.hosts

 

또한, 자신만의 커스텀 데코레이터를 생성할 수도 있습니다. 이것이 왜 유용할까요?

 

Node.js 세계에서는 요청 객체에 속성을 추가하는 것이 일반적인 관례입니다. 그러고 나서 각 라우트 핸들러에서 다음과 같은 코드로 이를 수동으로 추출합니다.

const user = req.user;

 

코드를 더 읽기 쉽고 명확하게 만들기 위해 @User() 데코레이터를 생성하고 이를 모든 컨트롤러에서 재사용할 수 있습니다.

import { createParamDecorator, ExecutionContext } from '@nestjs/common';

export const User = createParamDecorator(
  (data: unknown, ctx: ExecutionContext) => {
    const request = ctx.switchToHttp().getRequest();
    return request.user;
  },
);

 

그런 다음, 필요에 따라 언제든지 간단하게 사용할 수 있습니다.

@Get()
async findOne(@User() user: UserEntity) {
  console.log(user);
}

데이터 전달

데코레이터의 동작이 특정 조건에 따라 달라져야 할 경우, data 매개변수를 사용하여 데코레이터 팩토리 함수에 인자를 전달할 수 있습니다. 한 가지 사용 예로는, 요청 객체에서 키를 기준으로 속성을 추출하는 커스텀 데코레이터가 있습니다. 예를 들어, 인증 계청이 요청을 검증하고 사용자 엔티티를 요청 객체에 추가한다고 가정해 봅시다. 인증된 요청의 사용자 엔티티는 다음과 같을 수 있습니다:

{
  "id": 101,
  "firstName": "Alan",
  "lastName": "Turing",
  "email": "alan@email.com",
  "roles": ["admin"]
}

 

속성 이름을 키로 받아 해당 값이 존재하면 반환하고, 존재하지 않거나 user 객체가 생성되지 않은 경우에는 undefined를 반환하는 데코레이터를 정의해 봅시다.

import { createParamDecorator, ExecutionContext } from '@nestjs/common';

export const User = createParamDecorator(
  (data: string, ctx: ExecutionContext) => {
    const request = ctx.switchToHttp().getRequest();
    const user = request.user;

    return data ? user?.[data] : user;
  },
);

 

다음은 컨트롤러에서 @User() 데코레이터를 통해 특정 속성에 접근하는 방법입니다:

@Get()
async findOne(@User('firstName') firstName: string) {
  console.log(`Hello ${firstName}`);
}

 

이 동일한 데코레이터를 다른 키와 함께 사용하여 서로 다른 속성에 접근할 수 있습니다. user 객체가 깊거나 복잡한 구조를 가지고 있는 경우, 이를 통해 요청 핸들러 구현을 더 쉽고 읽기 좋게 만들 수 있습니다.

힌트
TypeScript 사용자라면 createParamDecorator<T>()는 제네릭이라는 점에 유의하세요. 예를 들어 createParamDecorator<string>((data, ctx) => ...)와 같이 명시적으로 타입 안정성을 보장할 수 있습니다. 또는 팩토리 함수 내부에서 createParamDecorator((data: string, ctx) => ...)처럼 파라미터 타입을 지정할 수도 있습니다. 둘 다 생략하면 data의 타입은 any가 됩니다.

파이프와 함께 사용하기

Nest는 커스텀 매개변수 데코레이터를 기본 제공 데코레이터들 (@Body(), @Param(), @Query())과 동일하게 처리합니다. 이는 커스텀 데코레이터로 주석 처리된 파라미터에도 파이프가 실행된다는 뜻입니다 (예제에서는 user 인자). 또한 파이프를 커스텀 데코레이터에 직접 적용할 수도 있습니다.

@Get()
async findOne(
  @User(new ValidationPipe({ validateCustomDecorators: true }))
  user: UserEntity,
) {
  console.log(user);
}

힌트
validateCustomDecorators 옵션이 true로 설정되어 있어야 합니다. 기본적으로 ValidationPipe는 커스텀 데코레이터로 주석 처리된 인자를 검증하지 않습니다.

데코레이터 합성

Nest는 여러 데코레이터를 하나로 결합할 수 있는 헬퍼 메서드를 제공합니다. 예를 들어, 인증과 관련된 모든 데코레이터를 하나의 데코레이터로 통합하고 싶다고 가정해 봅시다. 다음과 같은 구성으로 이를 구현할 수 있습니다:

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

export function Auth(...roles: Role[]) {
  return applyDecorators(
    SetMetadata('roles', roles),
    UseGuards(AuthGuard, RolesGuard),
    ApiBearerAuth(),
    ApiUnauthorizedResponse({ description: 'Unauthorized' }),
  );
}

 

그런 다음, 이 커스텀 @Auth() 데코레이터를 다음과 같이 사용할 수 있습니다:

@Get('users')
@Auth('admin')
findAllUsers() {}

 

이렇게 하면 네 개의 데코레이터가 하나의 선언으로 모두 적용되는 효과를 얻을 수 있습니다.

경고
@nestjs/swagger 패키지의 @ApiHideProperty() 데코레이터는 합성이 불가능하며, applyDecorators 함수와 함께 사용할 경우 제대로 작동하지 않습니다.

Reference

• Nest.js | Interceptors
• Nest.js | Custom decorators