Nest.js에서의 글로벌 예외 필터 설정: 안정적인 오류 관리의 기초

Nest.js는 현대적인 웹 애플리케이션 개발을 위한 강력한 프레임워크로, 예외 처리와 같은 중요한 기능을 통해 개발자에게 안정성과 일관성을 제공합니다. 이 블로그 포스트에서는 Nest.js에서 글로벌 예외 필터를 설정하는 방법과 그 중요성에 대해 자세히 알아보겠습니다.

예외 처리의 중요성

애플리케이션 개발에서 예외 처리는 필수적인 요소입니다. 예외가 발생했을 때 적절한 처리를 하지 않으면 사용자 경험이 저하되고, 시스템의 신뢰성이 떨어질 수 있습니다. Nest.js의 필터는 이러한 예외를 효과적으로 관리하여 사용자에게 유용한 정보를 제공하는 역할을 합니다.

필터의 주요 기능

1. 예외 포착 및 처리: 필터는 애플리케이션 내에서 발생하는 예외를 포착하고, 이를 적절히 처리하여 사용자에게 유용한 정보를 제공합니다.
2. 응답 포맷 통일성: 모든 예외에 대해 동일한 형식으로 응답할 수 있어 API의 일관성을 높입니다.
3. 로깅 및 모니터링: 예외 발생 시 로깅 기능을 추가하여 문제를 추적하고, 시스템의 상태를 모니터링할 수 있습니다.

글로벌 예외 필터 설정 방법

글로벌 예외 필터는 애플리케이션 전역에서 사용할 수 있는 필터로, 모든 요청에 대해 적용됩니다. 이를 통해 코드 중복을 피하고, 간편하게 에러 핸들링을 구현할 수 있습니다.

1단계: 글로벌 예외 필터 생성

먼저, ExceptionFilter 인터페이스를 구현하여 글로벌 예외 필터 클래스를 생성합니다. 아래는 HTTP 관련 예외를 처리하는 필터의 예시 코드입니다.

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

@Catch(HttpException)
export class AllExceptionsFilter implements ExceptionFilter {
    catch(exception: HttpException, host: ArgumentsHost) {
        const ctx = host.switchToHttp();
        const response = ctx.getResponse<Response>();
        const status = exception.getStatus();

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

위 코드는 HTTP 관련 예외를 포착하여 JSON 형식으로 응답합니다. 상태 코드와 타임스탬프를 포함하여 클라이언트가 오류 발생 시점과 경로를 쉽게 확인할 수 있도록 합니다.

2단계: 글로벌 등록

생성된 글로벌 예외 필터는 main.ts 파일에서 애플리케이션 초기화 시 등록해야 합니다. 아래 코드를 통해 필터가 전체 애플리케이션에 적용되도록 설정할 수 있습니다.

import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
import { AllExceptionsFilter } from './all-exceptions.filter';

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

이 코드를 통해 AllExceptionsFilter가 전체 애플리케이션에 적용되며, 모든 요청에 대해 일관된 예외 처리를 보장합니다.

실용적인 사례

예를 들어, 데이터베이스 연결 중 문제가 발생하거나 잘못된 요청이 들어올 경우, 위에서 만든 글로벌 예외 필터가 자동으로 작동하여 클라이언트에게 다음과 같은 JSON 응답을 보냅니다:

{
    "statusCode": 500,
    "timestamp": "2023-10-03T12:00:00Z",
    "path": "/api/resource",
    "message": "Internal server error"
}

이러한 방식으로 클라이언트 측에서는 어떤 문제가 발생했는지를 쉽게 이해할 수 있으며, 필요한 조치를 취할 수 있는 기회를 제공합니다. 이는 사용자 경험을 개선하고, 시스템의 신뢰성을 높이는 데 중요한 역할을 합니다.

결론

글로벌 예외 필터는 Nest.js 애플리케이션 내에서 효과적으로 오류 관리를 할 수 있도록 돕습니다. 이를 통해 개발자는 더욱 안정적이고 사용자 친화적인 시스템을 구축할 수 있으며, 다양한 상황에서도 일관된 방식으로 에러 처리를 할 수 있게 됩니다. 이러한 필터를 통해 애플리케이션의 품질을 높이고, 사용자에게 더 나은 서비스를 제공할 수 있는 기반을 마련할 수 있습니다.