[Nest.js] Overview - Middleware, Exception filters

미들웨어

미들웨어 (Middleware)는 라우트 핸들러가 호출되기 전에 실행되는 함수입니다. 미들웨어 함수는 요청 (request) 객체, 응답 (response) 객체, 그리고 애플리케이션의 요청-응답 사이클 내에서 다음 미들웨어 함수 (next)에 접근할 수 있습니다. 이 next 함수는 일반적으로 next라는 이름의 변수로 표현됩니다.

 

Nest 미들웨어는 기본적으로 Express 미들웨어와 동일한 방식으로 동작합니다. 다음은 공식 Express 문서에서 설명한 미들웨어의 기능입니다:

미들웨어 함수는 다음과 같은 작업을 수행할 수 있습니다:
- 어떤 코드든 실행할 수 있다.
- 요청 (request) 및 응답 (response) 객체를 수정할 수 있다.
- 요청-응답 사이클을 종료할 수 있다.
- 스택 내 다음 미들웨어 함수를 호출할 수 있다.
- 만약 현재 미들웨어 함수가 요청-응답 사이클을 종료하지 않는다면, next()를 반드시 호출해야 하며, 그렇지 않으면 요청이 처리되지 않은 채 멈춰 있게 됩니다.

 

Nest에서 커스텀 미들웨어는 함수 형태 또는 @Injectable() 데코레이터가 붙은 클래스 형태로 구현할 수 있습니다. 클래스 방식에서는 NestMiddleware 인터페이스를 구현해야 합니다. 함수 방식은 특별한 요구사항 없이 일반 함수로 정의하면 됩니다. 우선, 클래스 기반으로 간단한 미들웨어 기능을 구현해 보겠습니다.

경고
Express와 Fastify는 미들웨어를 처리하는 방식이 다르며, 메서드 시그니처 또한 서로 다릅니다. 자세한 내용은 여기에서 확인하세요.

import { Injectable, NestMiddleware } from '@nestjs/common';
import { Request, Response, NextFunction } from 'express';

@Injectable()
export class LoggerMiddleware implements NestMiddleware {
  use(req: Request, res: Response, next: NextFunction) {
    console.log('Request...');
    next();
  }
}

의존성 주입

Nest의 미들웨어는 의존성 주입 (Dependendy Injection)을 완벽하게 지원합니다. 프로바이더나 컨트롤러와 마찬가지로, 미들웨어도 같은 모듈 내에 등록된 의존성들을 주입받을 수 있습니다. 이 역시 일반적으로 생성자 (constructor)를 통해 수행됩니다.

미들웨어 적용

@Module() 데코레이터 안에는 미들웨어를 설정하는 항목이 없습니다. 대신, 미들웨어는 모듈 클래스의 configure() 메서드 안에서 설정합니다. 미들웨어를 포함하는 모듈은 NestModule 인터페이스를 구현해야 하며, 여기서는 AppModule에서 LoggerMiddleware를 설정해 보겠습니다.

import { Module, NestModule, MiddlewareConsumer } from '@nestjs/common';
import { LoggerMiddleware } from './common/middleware/logger.middleware';
import { CatsModule } from './cats/cats.module';

@Module({
  imports: [CatsModule],
})
export class AppModule implements NestModule {
  configure(consumer: MiddlewareConsumer) {
    consumer
      .apply(LoggerMiddleware)
      .forRoutes('cats');
  }
}

 

위 예시에서는 LoggerMiddleware를 이전에 정의한 CatsController의 /cats 라우트 핸들러에 설정했습니다. 또한 미들웨어를 특정 HTTP 요청 메서드에만 제한하고 싶을 경우, forRoutes() 메서드에 경로 (path)와 함께 요청 메서드 (request method)를 포함한 객체를 전달하여 설정할 수 있습니다. 아래 예제처럼 요청 메서드를 지정하려면 RequestMethod 열거형 (enum)을 import 해야 합니다.

import { Module, NestModule, RequestMethod, MiddlewareConsumer } from '@nestjs/common';
import { LoggerMiddleware } from './common/middleware/logger.middleware';
import { CatsModule } from './cats/cats.module';

@Module({
  imports: [CatsModule],
})
export class AppModule implements NestModule {
  configure(consumer: MiddlewareConsumer) {
    consumer
      .apply(LoggerMiddleware)
      .forRoutes({ path: 'cats', method: RequestMethod.GET });
  }
}

힌트
configure() 메서드는 async/await을 사용하여 비동기 방식으로 구현할 수 있습니다. 예를 들어, configure() 메서드 내부에서 비동기 작업의 완료를 기다릴 수 있습니다.

경고
Express 어댑터를 사용할 경우, NestJS 애플리케이션은 기본적으로 body-parser 패키지의 json 및 urlencoded 미들웨어를 등록합니다. 따라서 MiddlewareConsumer를 통해 해당 미들웨어를 커스터마이징 하려면, NestFactory.create()로 애플리케이션을 생성할 때 bodyParser 플래그를 false로 설정하여 전역 미들웨어를 비활성화해야 합니다.

라우트 와일드카드

NestJS 미들웨어는 패턴 기반 라우트를 지원합니다. 예를 들어, 이름 있는 와일드카드 (*splat)를 사용하면 경로에서 임의의 문자 조합과 매칭할 수 있습니다. 아래 예시에서는 abcd/로 시작하는 모든 경로에 대해 해당 미들웨어가 실행됩니다. 경로 뒤에 몇 글자가 오든 상관없습니다.

forRoutes({
  path: 'abcd/*splat',
  method: RequestMethod.ALL,
});

힌트
splat은 단순히 와일드카드 파라미터의 이름일 뿐이며, 특별한 의미는 없습니다. 예를 들어 *wildcard처럼 원하는 이름으로 지정할 수 있습니다.

 

'abcd/*' 경로는 abcd/1, abcd/123, abcd/abc 등과 같이 abcd/로 시작하는 모든 경로와 일치합니다. 하이픈(-)과 점(.)은 문자열 기반 경로에서 문자 그대로 해석됩니다. 그러나 abcd/와 같이 추가 문자가 없는 경로는 이 경로와 일치하지 않습니다. 이러한 경우 와일드카드를 선택적으로 만들기 위해 중괄호로 감싸야합니다.

forRoutes({
  path: 'abcd/{*splat}',
  method: RequestMethod.ALL,
});

미들웨어 소비자

미들웨어 소비자 (Middleware consumer)는 NestJS에서 미들웨어를 관리하기 위한 헬퍼 클래스입니다. 이 클래스는 여러 내장 메서드를 제공하며, 모두 fluent 스타일로 체이닝 할 수 있습니다. forRoutes() 메서드는 단일 문자열, 여러 문자열, RouteInfo 객체, 컨트롤러 클래스, 심지어 여러 컨트롤러 클래스를 받을 수 있습니다. 대부분의 경우, 단순히 쉼표로 구분된 컨트롤러 목록을 전달하는 방식을 사용할 것입니다. 아래는 단일 컨트롤러를 사용한 예시입니다:

import { Module, NestModule, MiddlewareConsumer } from '@nestjs/common';
import { LoggerMiddleware } from './common/middleware/logger.middleware';
import { CatsModule } from './cats/cats.module';
import { CatsController } from './cats/cats.controller';

@Module({
  imports: [CatsModule],
})
export class AppModule implements NestModule {
  configure(consumer: MiddlewareConsumer) {
    consumer
      .apply(LoggerMiddleware)
      .forRoutes(CatsController);
  }
}

힌트
apply() 메서드는 단일 미들웨어를 받을 수도 있고, 여러 개의 미들웨어를 지정하기 위해 여러 인수를 받을 수도 있습니다.

경로 제외하기

경우에 따라 특정 경로에는 미들웨어가 적용되지 않도록 제외하고 싶을 수 있습니다. 이는 exclude() 메서드를 사용하여 쉽게 달성할 수 있습니다. exclude() 메서드는 제외할 경로를 식별하기 위해 단일 문자열, 여러 문자열, 또는 RouteInfo 객체를 인자로 받을 수 있습니다. 다음은 이를 사용하는 예시입니다:

consumer
  .apply(LoggerMiddleware)
  .exclude(
    { path: 'cats', method: RequestMethod.GET },
    { path: 'cats', method: RequestMethod.POST },
    'cats/{*splat}',
  )
  .forRoutes(CatsController);

힌트
exclude() 메서드는 path-to-regexp 패키지를 사용하여 와일드카드 파라미터를 지원합니다.

 

위 예제에서 LoggerMiddleware는 CatsController 내에 정의된 모든 라우트에 적용되지만, exclude() 메서드에 전달된 세 가지 라우트는 예외입니다.

 

이러한 방식은 특정 라우트나 라우트 패턴에 따라 미들웨어를 적용하거나 제외하는 데 유연성을 제공합니다.

함수형 미들웨어

지금까지 사용한 LoggerMiddleware 클래스는 매우 단순합니다. 멤버도 없고, 추가 메서드나 의존성도 없습니다. 그렇다면 이걸 굳이 클래스로 정의하지 않고, 간단한 함수로 정의할 수는 없을까요? 실제로 가능합니다. 이러한 유형의 미들웨어를 함수형 미들웨어 (functional middleware)라고 합니다. 다음은 클래스 기반 미들웨어를 함수형으로 변환한 예시입니다:

import { Request, Response, NextFunction } from 'express';

export function logger(req: Request, res: Response, next: NextFunction) {
  console.log(`Request...`);
  next();
};

 

그리고 AppModule 내에서 이를 사용하는 방법은 다음과 같습니다:

consumer
  .apply(logger)
  .forRoutes(CatsController);

힌트
미들웨어에 의존성이 필요하지 않다면, 더 간단한 함수형 미들웨어 방식을 사용하는 것을 고려해 보세요.

다중 미들웨어

앞서 언급한 것처럼, 순차적으로 실행되는 여러 미들웨어를 바인딩하려면 apply() 메서드 안에 쉼표로 구분된 목록을 제공하면 됩니다.

consumer.apply(cors(), helmet(), logger).forRoutes(CatsController);

전역 미들웨어

모든 등록된 라우트에 한 번에 미들웨어를 바인딩하고 싶다면, INestApplication 인스턴스가 제공하는 use() 메서드를 사용할 수 있습니다:

const app = await NestFactory.create(AppModule);
app.use(logger);
await app.listen(process.env.PORT ?? 3000);

힌트
전역 미들웨어에서 DI 컨테이너에 접근하는 것은 불가능합니다. app.use()를 사용할 경우 함수형 미들웨어 (functional middleware)를 사용하는 것이 좋습니다. 또는 클래스 기반 미들웨어를 사용하고, AppModule (또는 다른 모듈) 내에서 .forRoutes('*')로 적용할 수도 있습니다.

---

예외 필터

Nest는 애플리케이션 전반의 모든 처리되지 않은 예외를 처리하는 내장 예외 처리 계층을 제공합니다. 애플리케이션 코드에서 예외를 처리하지 않으면, 이 계층이 해당 예외를 포착하고 자동으로 적절한 사용자 친화적인 응답을 전송합니다.

기본적으로 이 동작은 전역 내장 예외 필터에 의해 수행되며, 이 필터는 HttpException 및 그 하위 클래스 타입의 예외를 처리합니다. 예외가 HttpException이 아니거나 이를 상속받은 클래스가 아닌 경우, 내장 예외 필터는 다음과 같은 기본 JSON 응답을 생성합니다:

{
  "statusCode": 500,
  "message": "Internal server error"
}

힌트
전역 예외 필터는 http-errors 라이브러리를 부분적으로 지원합니다. 기본적으로, statusCoide와 message 속성을 포함하는 예외가 발생하면, 해당 정보가 제대로 반영되어 응답으로 전송됩니다 (인식되지 않은 예외에 대해 기본적으로 사용되는 InternalServerErrorException 대신에).

표준 예외 던지기

Nest는 @nestjs/common 패키지에서 제공되는 내장 HttpException 클래스를 제공합니다. 일반적인 HTTP REST/GraphQL API 기반 애플리케이션에서는 특정 오류 조건이 발생했을 때 표준 HTTP 응답 객체를 보내는 것이 모범 사례입니다.

 

예를 들어, CatsController에 findAll() 메서드 (GET 라우트 핸들러)가 있다고 가정해 봅시다. 이 핸들러가 어떤 이유로 예외를 던진다고 가정하면, 다음과 같이 하드코딩할 수 있습니다.

@Get()
async findAll() {
  throw new HttpException('Forbidden', HttpStatus.FORBIDDEN);
}

 

힌트
여기서 사용한 HttpStatus는 @nestjs/common 패키지에서 가져온 헬퍼 enum입니다.

 

클라이언트가 이 엔드포인트를 호출하면, 응답은 다음과 같습니다.

{
  "statusCode": 403,
  "message": "Forbidden"
}

 

HttpException 생성자는 응답을 결정하는 두 개의 필수 인자를 받습니다:

• response 인자는 JSON 응답 본문을 결정하며, 문자열이나 객체가 될 수 있습니다.
• status 인자는 HTTP 상태 코드를 정의합니다.

기본적으로 JSON 응답 본문에는 두 개의 속성이 포함됩니다.

• statusCode: status 인자로 제공된 HTTP 상태 코드
• message: 해당 상태 코드에 기반한 짧은 오류 설명

message만 덮어쓰고 싶다면 response 인자에 문자열을 전달하면 됩니다. 응답 본문 전체를 덮어쓰려면 response 인자에 객체를 전달하면 되고, Nest가 이를 JSON으로 직렬화하여 응답 본문으로 반환합니다.

 

두 번째 인자인 status는 유효한 HTTP 상태 코드여야 하며, 보통 @nestjs/common에서 제공하는 HttpStatus enum을 사용하는 것이 권장됩니다.

 

선택적인 세 번째 인자인 options는 오류의 원인을 담은 cause 객체를 제공하는 데 사용할 수 있습니다. 이 cause는 응답 객체에 직렬화되진 않지만, 로깅 시 유용하게 활용할 수 있습니다. 즉, HttpException이 발생한 내부 원인에 대한 정보를 포함할 수 있습니다.

 

다음은 응답 본문 전체를 덮어쓰고 오류 원인을 제공하는 예시입니다:

@Get()
async findAll() {
  try {
    await this.service.findAll()
  } catch (error) {
    throw new HttpException({
      status: HttpStatus.FORBIDDEN,
      error: 'This is a custom message',
    }, HttpStatus.FORBIDDEN, {
      cause: error
    });
  }
}

 

위와 같이 전체 응답을 객체로 오버라이드하면, 클라이언트에게 반환되는 응답은 다음과 같습니다.

{
  "status": 403,
  "error": "This is a custom message"
}

예외 로깅

기본적으로, Nest의 예외 필터는 HttpException과 그것을 상속한 예외들과 같은 내장 예외를 로깅하지 않습니다. 이러한 예외가 발생해도 콘솔에 표시되지 않으며, 이는 일반적인 애플리케이션 흐름의 일부로 간주되기 때문입니다. 이와 동일한 동작은 WsException, RpcException 같은 다른 내장 예외에도 적용됩니다.

 

이러한 예외들은 모두 @nestjs/common 패키지에서 내보내는 IntrinsicException 기본 클래스를 상속합니다. 이 클래스는 일반적인 애플리케이션 동작의 일부인 예외와 그렇지 않은 예외를 구분하는 데 도움을 줍니다.

 

이러한 예외를 로깅하고 싶다면, 커스텀 예외 필터를 생성하면 됩니다. 다음 섹션에서 그 방법을 설명합니다.

커스텀 예외

대부분의 경우, 커스텀 예외를 작성할 필요 없이 Nest에서 제공하는 내장 HTTP 예외를 사용할 수 있습니다. 하지만 커스텀 예외가 필요한 경우에는, HttpException 클래스를 기반으로 한 예외 계층을 직접 구현하는 것이 좋은 관행입니다. 이러한 방식으로 구현하면, Nest가 해당 예외를 인식하고 자동으로 오류 응답을 처리해 줍니다. 다음은 이러한 커스텀 예외를 구현하는 예시입니다.

export class ForbiddenException extends HttpException {
  constructor() {
    super('Forbidden', HttpStatus.FORBIDDEN);
  }
}

 

ForbiddenException은 기본 HttpException 클래스를 상속하므로, Nest의 내장 예외 처리기와 원활하게 작동합니다. 따라서 findAll() 메서드 내부에서 해당 예외를 사용할 수 있습니다.

@Get()
async findAll() {
  throw new ForbiddenException();
}

내장 HTTP 예외들

Nest는 기본 HttpException을 상속하는 표준 예외들을 제공합니다. 이 예외들은 @nestjs/common 패키지에서 제공되며, 가장 일반적인 HTTP 예외들을 표현합니다:

• BadRequestException
• UnauthorizedException
• NotFoundException
• ForbiddenException
• NotAcceptableException
• RequestTimeoutException
• ConflictException
• GoneException
• HttpVersionNotSupportedException
• PayloadTooLargeException
• UnsupportedMediaTypeException
• UnprocessableEntityException
• InternalServerErrorException
• NotImplementedException
• ImATeapotException
• MethodNotAllowedException
• BadGatewayException
• ServiceUnavailableException
• GatewayTimeoutException
• PreconditionFailedException

모든 내장 예외는 options 파라미터를 사용하여 에러 원인 (cause)과 에러 설명 (description)을 함께 제공할 수 있습니다.

throw new BadRequestException('Something bad happened', {
  cause: new Error(),
  description: 'Some error description',
});

 

위와 같이 사용하면, 응답은 다음과 같은 형태로 반환됩니다.

{
  "message": "Something bad happened",
  "error": "Some error description",
  "statusCode": 400
}

예외 필터

기본(내장) 예외 필터는 많은 경우를 자동으로 처리해 주지만, 예외 처리 계층을 완전히 제어하고 싶을 때가 있습니다. 예를 들어, 로깅을 추가하거나 동적인 조건에 따라 다른 JSON 스키마를 사용하고 싶을 수 있습니다. 예외 필터는 이러한 목적을 위해 설계되었으며, 예외 처리 흐름과 클라이언트에 반환되는 응답 내용을 직접 제어할 수 있게 해 줍니다.

 

이제 HttpException 클래스의 인스턴스를 포착하고, 그에 대한 사용자 정의 응답 로직을 구현하는 예외 필터를 만들어봅시다. 이를 위해 기본 플랫폼의 Request 및 Response 객체에 접근해야 합니다. Request 객체에서는 원래의 URL을 추출해 로깅 정보에 포함시키고, Response 객체에서는 response.json() 메서드를 통해 응답을 직접 제어합니다.

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

@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,
      });
  }
}

힌트
모든 예외 필터는 제네릭 ExceptionFilter<T> 인터페이스를 구현해야 합니다. 이 인터페이스는 catch(exception: T, host: ArgumentsHost) 메서드를 해당 시그니처로 제공해야 합니다. 여기서 T는 예외의 타입을 나타냅니다.

경고
@nestjs/platform-fastify를 사용하는 경우, response.json() 대신 response.send()를 사용할 수 있습니다. fastify에서 올바른 타입을 임포트 하는 것을 잊지 마세요.

 

@Catch(HttpException) 데코레이터는 예외 필터에 필요한 메타데이터를 바인딩하여, Nest에게 이 필터가 HttpException 타입의 예외만을 처리하도록 알려줍니다. @Catch() 데코레이터는 하나의 인자를 받을 수도 있고, 쉼표로 구분된 여러 인자를 받을 수도 있습니다. 이를 통해 여러 종류의 예외를 한 번에 처리하는 필터를 설정할 수 있습니다.

Arguments host

catch() 메서드의 파라미터를 살펴보겠습니다. exception 파라미터는 현재 처리 중인 예외 객체이며, host 파라미터는 ArgumentsHost 객체입니다. ArgumentsHost는 매우 강력한 유틸리티 객체로, 자세한 내용은 실행 컨텍스트 챕터에서 다룹니다.

 

이 코드 예제에서는 ArgumentsHost를 사용해 예외가 발생한 컨트롤러의 원래 요청 핸들러에 전달된 Request와 Response 객체에 접근합니다. 이를 위해 ArgumentsHost에 정의된 헬퍼 메서드들을 활용합니다. ArgumentsHost에 대해 더 알아보려면 여기에서 확인하세요.

이처럼 추상화된 이유는 ArgumentsHost가 모든 실행 컨텍스트 (예: 현재 사용 중인 HTTP 서버 컨텍스트뿐 아니라 마이크로서비스나 WebSocket 컨텍스트 등)에서 작동하기 때문입니다. 실행 컨텍스트 챕터에서 우리는 ArgumentsHost와 그 헬퍼 메서드들을 통해 어떤 실행 컨텍스트에서도 적절한 인자들에 접근하는 방법을 배우게 됩니다. 이를 통해 모든 컨텍스트에서 동작하는 범용적인 예외 필터를 작성할 수 있습니다.

필터 바인딩하기

이제 우리가 만든 HttpExceptionFilter를 CatsController의 create() 메서드에 연결해 봅시다.

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

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

 

여기서 우리는 @UseFilters() 데코레이터를 사용했습니다. @Catch() 데코레이터와 마찬가지로, 단일 필터 인스턴스 또는 쉼표로 구분된 여러 필터 인스턴스를 인자로 받을 수 있습니다. 위 예시에서는 HttpExceptionFilter 인스턴스를 직접 생성해 전달했습니다. 대신 클래스 자체를 전달하여 Nest 프레임워크가 인스턴스를 생성하게 할 수도 있으며, 이 경우 의존성 주입도 가능합니다.

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

힌트
가능한 경우 필터를 인스턴스가 아닌 클래스로 적용하는 것이 좋습니다. Nest는 동일한 클래스의 인스턴스를 모듈 전체에서 재사용할 수 있기 때문에 메모리 사용량을 줄일 수 있습니다.

 

위의 예제에서는 HttpExceptionFilter가 단일 create() 라우트 핸들러에만 적용되어 메서드 범위 (method-scoped)로 작동합니다. 예외 필터는 메서드 범위 (method-scoped), 컨트롤러 범위 (controller-scoped), 또는 전역 범위 (global-scoped)로 설정할 수 있습니다. 예를 들어, 컨트롤러 범위로 필터를 설정하려면 다음과 같이 하면 됩니다:

@Controller()
@UseFilters(new HttpExceptionFilter())
export class CatsController {}

 

이 구성은 CatsController 내에 정의된 모든 라우트 핸들러에 대해 HttpExceptionFilter를 설정합니다.

 

전역 범위 (global-scoped)의 필터를 생성하려면 다음과 같이 설정하면 됩니다:

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  app.useGlobalFilters(new HttpExceptionFilter());
  await app.listen(process.env.PORT ?? 3000);
}
bootstrap();

경고
useGlobalFilters() 메서드는 게이트웨이 (gateway)나 하이브리드 애플리케이션 (hybrid applications)에는 필터를 설정하지 않습니다.

 

전역 범위 필터 (Global-scoped filters)는 애플리케이션 전체에 걸쳐 모든 컨트롤러 및 모든 라우트 핸들러에 적용됩니다. 의존성 주입 (Dependency Injection) 측면에서 보면, useGlobalFilters()를 사용해 모듈 외부에서 등록한 전역 필터는 의존성을 주입받을 수 없습니다. 이는 Nest의 모듈 컨텍스트 바깥에서 필터가 생성되기 때문입니다. 이 문제를 해결하려면, 모듈 내부에서 전역 필터를 등록해야 하며, 다음과 같이 설정할 수 있습니다.

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

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

힌트
이 방식으로 필터에 대한 의존성 주입을 수행할 때는, 이 구성이 어떤 모듈에서 사용되었는지와 관계없이 해당 필터는 사실상 전역 (Global)이라는 점에 유의하세요. 그렇다면 이 작업은 어디에서 수행해야 할까요? 위 예시에서처럼 HttpExceptionFilter가 정의된 모듈을 선택하세요. 또한, useClass는 커스텀 프로바이더 등록을 처리하는 유일한 방법이 아닙니다. 자세한 내용은 여기를 참고하세요.

 

이 방식으로 필터를 등록할 때는 필요한 만큼 여러 개의 필터를 등록할 수 있습니다. 단순히 각각의 필터를 providers 배열에 추가하면 됩니다.

Catch everything

모든 처리되지 않은 예외를 포착하려면, @Catch() 데코레이터의 매개변수를 비워두면 됩니다. 즉, @Catch()처럼 사용하면 됩니다.

 

아래 예시는 플랫폼에 의존하지 않는 코드로, Request나 Response 같은 플랫폼 특정 객체를 직접 사용하지 않고, Nest의 HTTP 어댑터를 통해 응답을 전달합니다.

import {
  ExceptionFilter,
  Catch,
  ArgumentsHost,
  HttpException,
  HttpStatus,
} from '@nestjs/common';
import { HttpAdapterHost } from '@nestjs/core';

@Catch()
export class CatchEverythingFilter implements ExceptionFilter {
  constructor(private readonly httpAdapterHost: HttpAdapterHost) {}

  catch(exception: unknown, host: ArgumentsHost): void {
    // 특정 상황에서는 `httpAdapter`가 생성자 메서드에서 사용 불가능할 수 있으므로,
    // 여기서 이를 해결해야 합니다.
    const { httpAdapter } = this.httpAdapterHost;

    const ctx = host.switchToHttp();

    const httpStatus =
      exception instanceof HttpException
        ? exception.getStatus()
        : HttpStatus.INTERNAL_SERVER_ERROR;

    const responseBody = {
      statusCode: httpStatus,
      timestamp: new Date().toISOString(),
      path: httpAdapter.getRequestUrl(ctx.getRequest()),
    };

    httpAdapter.reply(ctx.getResponse(), responseBody, httpStatus);
  }
}

경고
모든 예외를 포착하는 필터와 특정 타입에 바인딩된 필터를 함께 사용할 경우, "모든 예외를 포착하는" 필터를 먼저 선언해야 특정 타입에 바인딩된 필터가 해당 타입을 올바르게 처리할 수 있습니다.

상속

일반적으로는 애플리케이션 요구사항을 충족하기 위해 완전히 커스터마이징 된 예외 필터를 생성합니다. 하지만 기본 전역 예외 필터의 동작을 일부 조건에 따라 변경하고 싶을 때는 내장된 기본 예외 필터를 단순히 상속 (extend) 하는 방식이 유용할 수 있습니다.

 

예외 처리를 기본 필터에 위임하려면, BaseExceptionFilter를 확장하고 상속받은 catch() 메서드를 호출하면 됩니다.

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

경고
BaseExceptionFilter를 확장한 메서드 범위 또는 컨트롤러 범위 필터는 new 키워드로 직접 인스턴스를 생성해서는 안 됩니다. 대신 Nest 프레임워크가 자동으로 인스턴스를 생성하도록 해야 합니다.

 

전역 필터는 기본 필터를 확장할 수 있으며, 이 작업은 두 가지 방법 중 하나로 수행할 수 있습니다.

 

첫 번째 방법은 사용자 정의 전역 필터를 인스턴스화할 때 HttpAdapter 참조를 주입하는 것입니다.

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

  const { httpAdapter } = app.get(HttpAdapterHost);
  app.useGlobalFilters(new AllExceptionsFilter(httpAdapter));

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

 

두 번째 방법은 APP_FILTER 토큰을 사용하는 것입니다. 여기와 같이 설정할 수 있습니다.

Reference

• Nest.js | Middleware
• Nest.js | Exception filters