NestJS Request Lifecycle (3) - Interceptor

이전 글

• 2022.12.22 - [Backend/NestJS] - NestJS Request Lifecycle (0) - 개요
• 2022.12.22 - [Backend/NestJS] - NestJS Request Lifecycle (1) - Middleware
• 2022.12.23 - [Backend/NestJS] - NestJS Request Lifecycle (2) - Guard

---

인터셉터

NestJS 내에서 인터셉터란 컨트롤러 전, 후에서 다양한 역할을 해주는 생명주기를 의미한다. 공식문서에서 설명하는 인터셉터가 구체적으로 하는 일은 다음과 같다.

• 메서드(컨트롤러) 실행 전, 후의 추가적인 로직 수행
• 함수에서 반환된 결과 및 예외에 대한 변환
• 기본 함수 동작의 확장
• 특정 조건 하에서 완전한 함수의 재정의(ex. 캐싱 목적)

출처: NestJS 공식 문서(https://docs.nestjs.com/interceptors)

인터셉터에는 2개의 인자가 사용된다. 첫번째는 앞선 가드에서도 다룬 실행컨텍스트(ExecutionContext)이다. 이를 이용하여 인터셉터는 특정 컨텍스트가 어떤 핸들러를 통해 처리되는지 알 수 있다. 두번째는 콜핸들러(CallHandler)이다. 인터셉터는 이 콜핸들러의 handle() 메서드를 통해 반환되는 RxJS Observable 객체를 반환하도록 작성되어야한다. 각각의 인자를 통해, 인터셉터는 핸들러 실행 전, 후에 접근할 수 있게된다.

 

인터셉터 작성

NestJS의 인터셉터를 작성하기 위해서는 @Injectable() 데코레이터를 통한 클래스를 작성해주어야한다. 이 때 해당 클래스는 NestJS의 NestInterceptor를 상속해야하며, 클래스 내부적으로는 interceptor 메서드를 포함해야한다. 이 때 작성되는 interceptor 메서드의 인자로, 앞서 언급한 ExecutionContext와 CallHandler가 포함된다. 기본적으로 작성되어야 할 코드는 다음과 같다.

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

@Injectable()
export class TestInterceptor implements NestInterceptor {
    intercept(context: ExecutionContext, next: CallHandler<any>): Observable<any> | Promise<Observable<any>> {
        // 핸들러 도달 전 인터셉터 로직
        return next.handle().pipe(
            // 핸들러 도달 이후 인터셉터 로직
        )
    }
}

 

인터셉터 적용

NestJS 프로젝트에 인터셉터를 적용하는 방법은 크게 3가지가 존재한다. (가드의 방식과 동일)

1. 모듈 밖에서 작동하는 전역 인터셉터
2. 모듈 내에서 작동하는 전역 인터셉터
3. 모듈 내 특정 컨트롤러 혹은 메서드에 작동하는 인터셉터

이들의 작동 순서는 조금 특이한데, 초기에 예상한 1 -> 2 -> 3 순서가 아닌 2 -> 1 -> 3 순서로 작동한다! (핸들러를 거친 뒤에는 역순)

모듈 밖에서 작동하는 전역 인터셉터

이를 위해서는 NestJS 애플리케이션의 useGlobalInterceptors() 메서드를 활용할 수 있다. 이 때 해당 메서드에는 인터셉터 클래스의 인스턴스가 직접 전달되어야하며, 모듈 밖에서 추가해주는 인터셉터이기 때문에 다른 의존성은 사용할 수 없다.

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

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  app.useGlobalInterceptors(new TestInterceptor());
  await app.listen(3000);
}
bootstrap();

모듈 내에서 작동하는 전역 인터셉터

해당 방식을 통하면 다른 의존성을 사용하면서도 인터셉터를 전역으로 설정할 수 있다. 

공식문서에 따르면, 해당 방식은 다음의 특징을 갖는다.

특정 인터셉터의 전역 설정을 위해 해당 방식으로 모듈에 의존성 주입을 할 때, 주입되는 모듈의 위치에 상관없이 이는 전역으로 작동합니다. 즉, 인터셉터의 주입은 해당 인터셉터가 생성된 모듈에서 이루어져도 무방합니다.

이에 따르면 전역 인터셉터 설정을 위한 의존성 주입은 꼭 최상위 모듈에 이루어지지 않아도 된다는 것을 의미한다.

이를 확인하기 위해 최상위 모듈이 아닌 TestModule을 생성해서 의존성 주입을 해보겠다.

import { Module } from '@nestjs/common';
import { APP_INTERCEPTOR } from '@nestjs/core';
import { TestInterceptor } from './app.interceptor';

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

해당 모듈을 최상위 모듈(app.module.ts)에 주입 후 TestModule과 무관한 컨트롤러를 호출해보니 전역으로 잘 작동한다! 

모듈 내 특정 컨트롤러 혹은 메서드에 작동하는 인터셉터

해당 방식을 통하면, 특정 컨트롤러 혹은 메서드에만 적용되는 인터셉터를 추가할 수 있다.  NestJS의 @UseInterceptors() 데코레이터를 통해 추가하는 방식이고, 메서드의 인자로는 인터셉터 클래스 혹은 클래스를 통한 인스턴스가 요구된다.

import { Controller, Get, UseInterceptors } from '@nestjs/common';
import { AppService } from './app.service';
import { TestInterceptor } from './interceptors/test2.interceptor';

@Controller()
export class AppController {
  constructor(private readonly appService: AppService) {}

  @Get('test')
  @UseInterceptors(TestInterceptor) // 인터셉터를 추가하는 방식
  getHello(): string {
    return this.appService.getHello();
  }
}

 

인터셉터 활용

다음은 NestJS에서 인터셉터를 활용하는 방안들에 대해 알아보겠다. 예시들은 공식문서의 예제를 가져온 것도 있고, 실제 프로젝트에 활용했던 코드를 가져온 부분도 존재한다.

핸들러 처리 시간 로그 출력 예제

여기에서는 NestJS 인터셉터와 RxJS의 tap Operator를 이용하여 핸들러를 처리하는데 얼마나 걸리는지 로그를 출력하는 예제를 작성한다. 코드는 다음과 같다.

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

@Injectable()
export class TestInterceptor implements NestInterceptor {
  intercept(
    context: ExecutionContext,
    next: CallHandler<any>,
  ): Observable<any> | Promise<Observable<any>> {
    const timer = Date.now();
    console.log('핸들러 도착 전...');
    return next
      .handle()
      .pipe(tap(() => console.log(`핸들러 도착 후...${Date.now() - timer}ms`)));
  }
}

반환 형태 템플릿 적용

다음은 클라이언트의 요청에 대한 응답을 일정한 데이터 구조를 통해 반환하기 위한 인터셉터 예제이다.

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

// 사용자에게 반환할 데이터 템플릿
interface ResponseTemplate<T> {
  message: string;
  data: T;
}

@Injectable()
export class TestInterceptor<T>
  implements NestInterceptor<T, ResponseTemplate<T>>
{
  intercept(
    context: ExecutionContext,
    next: CallHandler,
  ):
    | Observable<ResponseTemplate<T>>
    | Promise<Observable<ResponseTemplate<T>>> {
    return next.handle().pipe(
      map((resData) => ({
        message: resData.message || '',
        data: resData.data || '',
      })),
    );
  }
}

예외 처리 

다음은 에러가 발생했을 때 이를 무시하고 일괄적으로 NestJS BadRequest 처리를 해주는 인터셉터이다.

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

@Injectable()
export class TestInterceptor<T>
  implements NestInterceptor<T, ResponseTemplate<T>>
{
  intercept(
    context: ExecutionContext,
    next: CallHandler,
  ):
    | Observable<ResponseTemplate<T>>
    | Promise<Observable<ResponseTemplate<T>>> {
    return next
      .handle()
      // 에러 발생 시 일괄적으로 NestJS BadRequestException 처리
      .pipe(catchError((err) => throwError(() => new BadRequestException())));
  }
}

요청 시간 제한 인터셉터

다음 예제는, 요청 반환까지 걸리는 시간이 5초가 넘는 경우, 일괄적으로 Timeout 처리를 진행하는 예제이다.

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), // 5000ms의 대기 후 TimeoutError를 던짐
      catchError((err) => {
        if (err instanceof TimeoutError) { // 만약 에러가 TimeoutError라면 RequestTimeoutException을 던짐
          return throwError(() => new RequestTimeoutException());
        }
        return throwError(() => err);
      }),
    );
  }
}

캐싱 인터셉터

마지막은 요청이 메인 비즈니스 로직에서 처리되기 전, 캐싱 데이터가 있다면 곧바로 요청을 처리하는 인터셉터이다.

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();
  }
}

위 코드는 단순 예시에 불과하며, 실제 코드에서는 isCached 부분에 실제 캐싱 여부를 확인하는 로직이 포함되어야 한다. 만약 캐싱이 되어있는 경우 of()를 통해 생성된 새로운 스트림을 곧바로 클라이언트에 반환하고, 컨트롤러 로직은 처리되지 않는다.