NestJS Request Lifecycle (5) - Exception Filter

이전 글

• 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
• 2022.12.26 - [Backend/NestJS] - NestJS Request Lifecycle (3) - Interceptor
• 2022.12.29 - [Backend/NestJS] - NestJS Request Lifecycle (4) - Pipe

---

예외 필터

NestJS에서 예외 필터란 비즈니스 로직 레벨에서 처리되지 않은 모든 예외를 사용자 친화적인 방식으로 처리하는 역할을 한다. 따라서 예외 필터를 이용하면 프로그래머가 예상치 못한 에러가 발생하더라도 서버가 죽지 않고, 또한 로깅 등의 작업을 함께 수행할 수 있다. 

NestJS 애플리케이션 생성 시 기본적으로 NestJS 기본 예외 필터가 내장된다.

 

NestJS의 예외

NestJS 기본 제공 예외

NestJS에서는 기본적으로 HttpException이라는 기본 예외를 제공하며, 이를 상속한 수많은 내장 예외가 존재한다.

• BadRequestException
• UnauthorizedException
• NotFoundException
• ForbiddenException
• NotAcceptableException
• RequestTimeoutException

위에 작성한 예시들은 HttpException을 상속한 기본 내장 예외들의 일부분이다. 애플리케이션 내에서 위의 예시들을 던지도록 로직을 작성하면, NestJS의 기본 내장 예외 필터가 이를 캐치하여 사용자에게 각 예외에 대한 반환을 수행한다.

Custom 예외 작성

다양한 예외 상황에 대처하기 위해 HttpException의 생성자에 하드코딩을 할 수도 있지만 재사용성, 유지보수성을 위해서 HttpException을 상속하여 따로 객체로 관리하는 것을 추천한다. 

예시를 하나 들어보자. 사용자의 회원가입 요청에서 이미 존재하는 이메일을 사용할 경우 사용자에게 예외 처리를 해야한다면 다음과 같이 코드를 작성할 수 있다.

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

export class DuplicateEmailSignupException extends BadRequestException {
  constructor() {
    super('The email you inputed is duplicated.');
  }
}

이 때 HttpException을 상속하는 것이 아닌 그의 자식 클래스인 BadRequestException을 상속했는데, 결국 이 또한 HttpException의 하위 클래스이기 때문에 잘 작동한다.

이를 사용하기 위해서는 DB 내 중복 이메일이 존재할 때 그저 위 클래스의 인스턴스를 던져주기만 하면 된다. 아래는 그의 예시이다.

  async signup({ email, password }: SignupDto): Promise<boolean> {
    const duplicatedUser = await this.userRepository.findOneBy({
      email,
      deletedAt: null,
    });
    
    // 예외 처리
    if (duplicatedUser) {
      throw new DuplicateEmailSignupException();
    }
    ...
  }

 

예외 필터 작성

NestJS에는 이미 기본 내장 예외 필터가 존재하기 때문에 따로 로직 작성이 필요없지만, 기본 내장 필터의 기능을 확장하기 위해서는 Custom 예외 필터의 작성이 필요하다.

Custom 예외 필터 작성

NestJS에서 Custom 예외 필터를 작성하기 위한 방법은 크게 2가지가 존재한다.

• ExceptionFilter 인터페이스를 상속(implements)하여 catch 메서드 직접 구현
• BaseExceptionFilter 클래스를 상속(extends)하여 기능 추가

인터페이스 상속을 통한 예외 필터 생성

해당 방식은 예외 필터로서 필요한 인터페이스를 가져온 뒤 내부 구현은 새로하는 방식이다. 예시는 아래와 같다.

import { ExceptionFilter, Catch, ArgumentsHost, HttpException } from '@nestjs/common';
import { Request, Response } from 'express';

// HttpException 에러를 처리
@Catch(HttpException)
export class HttpExceptionFilter implements ExceptionFilter {
  catch(exception: HttpException, host: ArgumentsHost) {
    const ctx = host.switchToHttp();
    const response = ctx.getResponse<Response>();
    const request = ctx.getRequest<Request>();
    const status = exception.getStatus();

    response
      .status(status)
      .json({
        statusCode: status,
        timestamp: new Date().toISOString(),
        path: request.url,
      });
  }
}

이 때 @Catch 데코레이터는 해당 필터가 어떤 종류의 Exception을 처리하는지에 대한 메타데이터를 제공한다. 만약 모든 종류의 예외를 처리하고 싶다면, 인자를 추가하지 않으면 된다.

catch 메서드의 exception 인자는 해당 필터가 처리하는 예외이다. 해당 예시에서는 HttpException만을 처리하고 있기 때문에 exception의 타입은 HttpException이 된다. 

catch 메서드의 host 인자는 ArgumentsHost이다. 이를 통하면 현재 실행컨텍스트에서 다양한 정보에 접근이 가능하다. (ex. Express의 Request, Response 객체; WebSocket에서 Client, Data 객체 등)

위 예시는 필터가 설정된 바운더리 내에서 발생한 HttpException에 대해, 사용자에게 상태 코드, 예외 발생일시, 예외 발생 경로를 담은 JSON을 반환하는 필터로 볼 수 있다.

기본 예외 필터 클래스를 상속하여 기능을 추가하는 방식

해당 방식은 기존의 내장 예외 필터의 기능을 유지한채 추가적인 기능을 덧붙이기 위한 방식이다. 공식문서의 예시는 아래와 같다.

import { Catch, ArgumentsHost } from '@nestjs/common';
import { BaseExceptionFilter } from '@nestjs/core';

@Catch()
export class AllExceptionsFilter extends BaseExceptionFilter {
  catch(exception: unknown, host: ArgumentsHost) {
    super.catch(exception, host);
  }
}

위 예시에서는 모든 예외를 처리하는 필터를 위해 @Catch 데코레이터에 인자를 할당하지 않았다. 또한 catch 메서드 내부에서 부모 클래스의 catch 메서드를 호출하는데, 이는 단순히 접근 방식을 보이기 위함이며 실제 구현에서는 각 상황에 맞는 비즈니스 로직이 추가될 수 있다.

공식문서에 따르면 위 방식을 컨트롤러, 메서드 범위의 필터로 사용할 경우 인스턴스를 할당하는 것이 아닌, 클래스 자체를 할당하여 NestJS에 인스턴스화를 위임해야한다.(전역 필터 설정을 위해 모듈 밖에서 useGlobalFilters 메서드를 사용한다면, 그 때에는 인스턴스를 할당해야한다.)

 

예외 필터 적용

NestJS에서 Custom 예외 필터를 적용하는 방법에는 크게 4가지가 존재한다.

1. 모듈 밖에 위치하는 전역 필터
2. 모듈 내에 위치하는 전역 필터
3. 컨트롤러 레벨에 작동하는 필터
4. 메서드(핸들러) 레벨에 작동하는 필터

모듈 밖에 위치하는 전역 필터

모듈 밖에 위치하는 전역 필터 설정을 위해서는 NestJS 애플리케이션의 useGlobalFilters 메서드를 사용해야한다. 이 때 메서드의 인자로는 클래스를 통해 생성한 인스턴스가 위치해야 한다. 해당 방식은 언제까지나 모듈 밖에 필터가 위치하기 때문에, 모듈 내에 존재하는 의존성에 대한 주입은 불가능하다. 아래는 공식문서의 예시이다.

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  // 전역 필터 설정
  app.useGlobalFilters(new HttpExceptionFilter());
  await app.listen(3000);
}
bootstrap();

모듈 내에 위치하는 전역 필터

필터를 모듈 내에 위치시키면서도, 필터를 전역으로 사용할 수 있다. 모듈 내 프로바이더에 필터를 주입 시 이는 전역 필터가 된다.

어떤 모듈에서 주입하더라도 이는 전역으로 작동하기 때문에, 필터가 작성된 모듈에서 바로 주입을 하면 된다.

해당 방식을 이용할 경우 NestJS 모듈 내의 의존성을 필터에 주입하여 이용할 수 있다는 장점이 있다. 예시는 아래와 같다.

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

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

컨트롤러 레벨에서 작동하는 필터

특정 컨트롤러에 대해서만 필터를 적용할 수도 있다. 이 때는 NestJS에서 제공하는 @UseFilters 데코레이터를 이용해야한다.

공식 문서에서는 해당 방식을 이용할 경우, 인스턴스를 인자로 할당하기보다는 클래스 자체를 할당하여 인스턴스화에 대한 책임을 NestJS에 이관하면 전반적인 메모리의 사용을 줄일 수 있다고 한다. 되도록이면 클래스 자체를 할당하자.

예시는 아래와 같다.

// NestJS의 대표적인 예시인 Cats 예시
@UseFilters(HttpExceptionFilter)
// @UseFilters(new HttpExceptionFilter()) 도 가능하나,
// 메모리 절약 측면에서 추천하지 않는 방식
export class CatsController {}

메서드(핸들러) 레벨에서 작동하는 필터

특정 컨트롤러의 메서드에 대해서만 필터를 적용할 수도 있다. 해당 방식 또한 앞서 언급한 @UseFilters 데코레이터를 이용해야하며, 컨트롤러 자체에 적용하는 것과 사용법이 다르지 않다.

예시는 아래와 같다.

@Post()
@UseFilters(HttpExceptionFilter)
async create(@Body() createCatDto: CreateCatDto) {
  throw new ForbiddenException();
}

 

Reference

https://docs.nestjs.com/exception-filters

Documentation | NestJS - A progressive Node.js framework