예외 처리와 필터

웹 애플리케이션을 개발하다 보면 다양한 예외(Exceptions) 상황을 만나게 됩니다.

예를 들어 존재하지 않는 리소스 접근, 데이터베이스 오류, 사용자 입력 유효성 검사 실패가 대표적입니다.

이런 예외를 적절히 처리하지 않으면 사용자에게 불친절한 오류 메시지가 노출되거나, 애플리케이션이 비정상 종료될 수 있습니다.

NestJS는 강력하고 유연한 예외 처리(Exception Handling) 메커니즘을 제공하여, 애플리케이션의 안정성과 사용자 경험을 향상시킬 수 있도록 돕습니다.

핵심적으로 예외 필터(Exception Filters)를 통해 이러한 예외들을 중앙 집중식으로 관리할 수 있습니다.

NestJS의 빌트인 예외 처리

NestJS는 기본적으로 표준 HTTP 예외를 처리하기 위한 빌트인(built-in) 예외 계층을 제공합니다.

이는 @nestjs/common 패키지의 HttpException 클래스와 그 하위 클래스들을 통해 구현됩니다.

예를 들어, NotFoundException, BadRequestException, UnauthorizedException 등이 있습니다.

컨트롤러나 서비스에서 특정 조건이 만족되지 않을 때, 이들 예외 클래스의 인스턴스를 throw하면 NestJS가 이를 자동으로 감지하여 적절한 HTTP 응답(상태 코드, 메시지 등)을 클라이언트에 반환합니다.

import { Controller, Get, Param, NotFoundException } from '@nestjs/common';
import { ItemsService } from './items.service';

@Controller('items')
export class ItemsController {
  constructor(private readonly itemsService: ItemsService) {}

  @Get(':id')
  findOne(@Param('id') id: string) {
    const item = this.itemsService.findItemById(id); // 예를 들어, 서비스에서 아이템을 찾는다고 가정
    if (!item) {
      // 아이템이 없는 경우 NotFoundException을 발생시킵니다.
      throw new NotFoundException(`Item with ID "${id}" not found.`);
    }
    return item;
  }
}

위 코드에서 findOne 메서드는 특정 id를 가진 아이템을 찾고, 만약 아이템이 존재하지 않으면 NotFoundException을 throw합니다.

NestJS는 이 예외를 가로채서 클라이언트에게 404 Not Found 상태 코드와 함께 지정된 메시지를 반환합니다.

이는 개발자가 일일이 res.status(404).json(...)과 같은 코드를 작성할 필요 없이, 선언적으로 예외를 처리할 수 있게 해줍니다.

이 예제를 따라 실행하려면 생략된 ItemsService.findItemById()가 동기적으로 항목 또는 undefined를 반환해야 하며, 컨트롤러와 서비스도 같은 모듈에서 사용할 수 있게 등록되어 있어야 합니다. 예를 들어 ID '1'에서는 { id: '1', name: 'Notebook' }, 다른 ID에서는 undefined를 반환하도록 준비하면 정상 조회와 404를 비교할 수 있습니다. DB 조회처럼 Promise를 반환하는 서비스로 바꿀 때는 핸들러도 async로 바꾸고 결과를 await한 뒤 검사해야 합니다. 아직 완료되지 않은 Promise를 if (!item)으로 검사하면 누락된 항목을 판별할 수 없습니다.

예외 필터: 커스텀 예외 처리

빌트인 예외 처리만으로 충분하지 않은 경우, 즉 특정 예외에 대해 사용자 정의 응답 형식을 제공하거나, 추가적인 로깅을 수행하는 등 더 세밀한 제어가 필요할 때는 예외 필터를 사용할 수 있습니다.

이 절의 HTTP 예외 필터는 요청 처리 경로에서 처리되지 않은 예외에 응답 로직을 적용합니다. 컨트롤러·서비스에서 반환하거나 await한 Promise의 실패도 이 경로에 포함됩니다. 요청과 분리해서 시작한 비동기 작업이나 타이머의 오류까지 모두 잡아 주는 프로세스 전체 오류 처리기는 아닙니다.

• Catch() 데코레이터: 어떤 종류의 예외를 처리할지 @Catch() 데코레이터에 지정합니다. 특정 예외 클래스를 지정하거나 여러 예외 클래스를 쉼표로 구분한 인수로 전달할 수 있으며, 인자가 없으면 모든 종류의 예외를 처리합니다.
• ExceptionFilter 인터페이스: ExceptionFilter 인터페이스를 구현하고 catch() 메서드를 오버라이드합니다. catch() 메서드는 발생한 예외 객체와 ArgumentsHost 객체를 인자로 받습니다.
• 전역, 컨트롤러, 메서드 레벨 적용: @UseFilters() 데코레이터를 사용하여 특정 컨트롤러나 메서드에 적용하거나, main.ts에서 전역으로 적용할 수 있습니다.

클라이언트에게 좀 더 상세하고 일관된 에러 응답 형식을 제공하는 예외 필터를 만들어보겠습니다.

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

@Catch(HttpException) // 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(); // 예외의 HTTP 상태 코드 가져오기

    // HttpException에 담긴 공개 응답 메시지를 가져옵니다.
    const errorResponse = exception.getResponse();
    const errorMessage = typeof errorResponse === 'string'
      ? errorResponse
      : (errorResponse as any).message || 'An unexpected error occurred.';

    response.status(status).json({
      statusCode: status,
      timestamp: new Date().toISOString(),
      path: request.url,
      message: errorMessage, // 클라이언트에게 보여줄 커스텀 메시지
      // errorCode: 'CUSTOM_ERROR_CODE', // 필요에 따라 커스텀 에러 코드 추가
    });
  }
}

위 HttpExceptionFilter는 적용 범위의 HttpException에 timestamp와 path를 더합니다. 일반 Error를 처리하는 분기는 없으며, requestId·별도 비공개 로그도 아직 구현하지 않았습니다.

응답 형식을 바꿀 때 보존되는 정보 확인하기

getResponse()는 문자열이나 객체를 돌려줄 수 있습니다. 객체의 message가 배열이면 이 코드도 배열을 그대로 응답에 넣습니다. 반면 객체에 들어 있던 errorCode나 다른 속성은 새 JSON에 복사하지 않으므로 사라집니다. 클라이언트가 message를 항상 문자열로 가정하거나 원래 오류 객체가 전부 보존된다고 가정해서는 안 됩니다. 공개 오류 코드를 유지하려면 필터의 응답 계약에 그 필드를 명시적으로 포함해야 합니다.

앞의 도식에 나온 일반 오류 분류, 비공개 진단 로그, requestId는 확장 설계입니다. 현재 필터는 그 기능을 구현하지 않습니다. 특히 DB 오류 메시지나 stack을 그대로 공개 응답으로 복사하는 대신, 클라이언트용 메시지와 운영자용 진단 정보를 구분해야 합니다. path: request.url에는 쿼리 문자열도 포함될 수 있으므로 공개 경로에 어떤 정보를 담을지도 정해야 합니다. Nest 11의 HttpException API에서 문자열·객체 응답을 구분할 수 있습니다.

예시: 같은 실패를 필터 적용 전후로 비교하기

위 서비스 준비에서 존재하지 않는 ID '9'를 조회합니다. 전역 접두사를 유지했다면 GET /api/items/9입니다. 메서드에 @UseFilters(HttpExceptionFilter)를 적용한 뒤에는 상태 404를 유지하면서 응답 본문에 statusCode: 404, 실제 요청의 path, 동적으로 생성한 timestamp, Item with ID "9" not found.라는 message가 포함됩니다. 필터는 실패를 성공으로 바꾸지 않고 오류 응답 계약을 정합니다. 처리 시각은 요청마다 달라지므로 고정 문자열로 비교하지 않습니다.

import { Controller, Get, Param, NotFoundException, UseFilters } from '@nestjs/common';
import { ItemsService } from './items.service';
import { HttpExceptionFilter } from '../common/filters/http-exception.filter';

@Controller('items')
export class ItemsController {
  constructor(private readonly itemsService: ItemsService) {}

  @UseFilters(HttpExceptionFilter) // 이 메서드에서 발생하는 HttpException에만 적용
  @Get(':id')
  findOne(@Param('id') id: string) {
    const item = this.itemsService.findItemById(id);
    if (!item) {
      throw new NotFoundException(`Item with ID "${id}" not found.`);
    }
    return item;
  }
}

import { Controller, Get, Param, NotFoundException, UseFilters } from '@nestjs/common';
import { ItemsService } from './items.service';
import { HttpExceptionFilter } from '../common/filters/http-exception.filter';

@UseFilters(HttpExceptionFilter) // 이 컨트롤러의 모든 라우트에 적용
@Controller('items')
export class ItemsController {
  // ...
}

import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
import { HttpExceptionFilter } from './common/filters/http-exception.filter'; // 필터 임포트

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

  // 전역 예외 필터 등록
  // 주의: new 키워드를 사용하면 해당 필터는 의존성 주입을 받을 수 없습니다.
  // 의존성 주입이 필요한 경우, APP_FILTER 토큰을 사용하여 모듈에서 프로바이더로 등록해야 합니다.
  app.useGlobalFilters(new HttpExceptionFilter());

  await app.listen(3000);
}
bootstrap();

import { Module } from '@nestjs/common';
import { APP_FILTER } from '@nestjs/core';
import { HttpExceptionFilter } from './common/filters/http-exception.filter';

@Module({
  providers: [
    {
      provide: APP_FILTER,
      useClass: HttpExceptionFilter,
    },
    // ... 다른 프로바이더들
  ],
  // ...
})
export class AppModule {}

사용자 정의 예외

NestJS의 HttpException을 상속받아 우리 애플리케이션의 특정 비즈니스 로직에 맞는 사용자 정의 예외를 생성할 수도 있습니다.

이는 코드의 가독성을 높이고, 특정 예외 상황을 명확하게 표현하는 데 도움을 줍니다.

import { HttpException, HttpStatus } from '@nestjs/common';

export class UserAlreadyExistsException extends HttpException {
  constructor(username: string) {
    super(`User with username "${username}" already exists.`, HttpStatus.CONFLICT); // 409 Conflict
  }
}

이제 이 사용자 정의 예외를 컨트롤러나 서비스에서 throw할 수 있으며, HttpExceptionFilter는 이를 자동으로 처리할 것입니다.

import { Injectable } from '@nestjs/common';
import { UserAlreadyExistsException } from '../common/exceptions/user-already-exists.exception';

@Injectable()
export class UsersService {
  private users: string[] = ['testuser'];

  createUser(username: string): string {
    if (this.users.includes(username)) {
      throw new UserAlreadyExistsException(username);
    }
    this.users.push(username);
    return `User ${username} created successfully.`;
  }
}

사용자 정의 예외를 쓰면 서비스 코드에는 도메인 의미가 남고, 필터는 이를 클라이언트 응답 규격으로 변환합니다.

예외 필터를 설계할 때는 예외를 잡는 것에서 끝내지 말고, 클라이언트가 재시도·로그인 이동·입력 수정 같은 복구 경로를 선택할 수 있도록 응답 형식을 정규화해야 합니다.

필터의 범위를 스스로 확인하기

앞의 HttpExceptionFilter를 전역으로 등록했습니다. 서비스가 UserAlreadyExistsException('testuser')를 던진 경우와, 일반 Error('database unavailable')를 던진 경우에 이 필터가 각각 실행되는지 설명해 보세요. 사용자 정의 오류 응답을 만든다는 이유만으로 모든 오류가 같은 경로를 쓰는지도 판단합니다.

예외 처리와 예외 필터는 NestJS 애플리케이션의 오류 응답 형식과 복구 전략을 정하는 요소입니다.

도메인 오류, 인증 오류, 시스템 오류를 구분해 일관된 응답 구조로 처리해야 합니다.

연습: 어떤 오류가 어디에서 처리되는가

1. findItemById()를 Promise<Item | undefined>로 바꿨고 결과는 undefined입니다. 기존 동기 핸들러를 그대로 두면 if (!item)이 누락된 항목을 찾을까요? 올바른 검사 순서를 적어 보세요.
2. 현재 HttpExceptionFilter가 { message: ['name is required'], errorCode: 'INVALID_NAME' }를 응답 객체로 가진 HttpException을 받습니다. 상태는 400, 요청 URL은 /users입니다. 유지되는 message, 상태와 경로, 사라지는 필드를 구분하세요.
3. 같은 HttpException을 처리하는 메서드·컨트롤러·전역 필터를 모두 등록했습니다. 메서드 필터가 응답을 완료한 다음 나머지 두 필터도 실행될까요? 핸들러가 직접 오류를 잡고 'fallback'을 반환하는 경우도 비교하세요.
4. 앞의 메모리 UsersService는 처음에 'testuser'만 보관합니다. 순서대로 'alice', 'alice', 'Alice'를 생성하면 어떤 결과인가요? 입력은 모두 문자열이며, 다른 필터는 없고 문자열 대소문자 규칙과 중복 검사 코드는 그대로입니다. 이 검사만으로 여러 서버가 공유하는 DB의 중복을 막을 수 있을까요?