Nest.js에서의 예외 필터: 오류 관리의 새로운 패러다임

Nest.js는 현대적인 웹 애플리케이션 개발을 위한 강력한 프레임워크로, 그 중에서도 예외 필터는 오류 처리를 효율적으로 관리하는 데 중요한 역할을 합니다. 이번 포스트에서는 예외 필터의 개념, 주요 기능, 사용 방법, 그리고 이를 통해 얻을 수 있는 이점에 대해 자세히 살펴보겠습니다.

예외 필터의 개념

예외 필터는 애플리케이션에서 발생하는 오류를 효과적으로 관리하고, 사용자에게 적절한 응답을 제공하기 위한 중요한 구성 요소입니다. Nest.js의 예외 필터는 미들웨어와 유사한 기능을 제공하지만, 주로 예외 상황에 집중하여 설계되었습니다. 이를 통해 개발자는 코드의 복잡성을 줄이고, 일관된 오류 처리를 구현할 수 있습니다.

주요 기능

1. 예외 캡처: 특정 타입의 예외를 감지하고 이를 처리하여, 클라이언트에게 적절한 오류 메시지를 전달합니다.
2. 응답 포맷 설정: 클라이언트에게 반환되는 응답 형식을 통일성 있게 유지하여, 다양한 오류 상황에서도 일관된 사용자 경험을 제공합니다.
3. 로그 기록: 발생한 예외에 대한 로그를 남겨 문제 해결에 도움을 주며, 이를 통해 시스템의 신뢰성을 높일 수 있습니다.

사용 방법

Nest.js에서는 기본적으로 @Catch() 데코레이터를 사용하여 커스텀 예외 필터를 만들 수 있습니다. 아래는 간단한 커스텀 예외 필터 구현 사례입니다:

import { ExceptionFilter, Catch, ArgumentsHost, HttpException } from '@nestjs/common';
import { 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 status = exception.getStatus();

    const errorResponse = {
      statusCode: status,
      timestamp: new Date().toISOString(),
      path: ctx.getRequest().url,
      message: exception.message || null,
    };

    response.status(status).json(errorResponse);
  }
}

위 코드는 HTTP 관련 예외가 발생했을 때 해당 내용을 캡쳐하여 JSON 형태로 응답하는 커스텀 필터입니다. 이 필터는 클라이언트가 이해할 수 있는 형식으로 오류 정보를 제공하여, 개발자가 문제를 신속하게 파악하고 해결할 수 있도록 돕습니다.

글로벌 및 모듈별 미들웨어 적용

커스텀 필터는 전역적으로 또는 특정 모듈 내에서 사용할 수 있습니다:

1. 전역적 적용

main.ts 파일에서 전역으로 등록할 수 있습니다. 이를 통해 애플리케이션의 모든 HTTP 요청에 대해 예외 필터가 적용됩니다.

import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
import { HttpExceptionFilter } from './http-exception.filter';

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

2. 모듈별 적용

특정 컨트롤러에만 적용하려면 다음과 같이 할 수 있습니다. 이 경우, 해당 컨트롤러에서 발생하는 예외에 대해서만 필터가 작동하게 됩니다.

import { Controller, Get, UseFilters } from '@nestjs/common';

@Controller('example')
@UseFilters(HttpExceptionFilter)
export class ExampleController {
  @Get()
  getExample() {
    throw new HttpException('This is a custom error!', 400);
  }
}

이 경우 ExampleController 내에서만 HttpExceptionFilter가 작동하게 되어, 특정 상황에 맞는 오류 처리를 구현할 수 있습니다.

요약

예외 필터는 Nest.js 애플리케이션에서 오류 처리를 효율적으로 관리하는 중요한 도구입니다. 이를 통해 개발자는 보다 깔끔하고 일관된 방식으로 오류 메시지를 클라이언트에 전달할 수 있으며, 디버깅 과정에서도 유용하게 활용될 수 있습니다. 예외 필터를 적절히 활용함으로써, 애플리케이션의 신뢰성과 사용자 경험을 동시에 향상시킬 수 있습니다.