exception filter란 무엇인가요?

Question

Accepted Answer

**Exception filter**는 오류가 **어떻게 잡히고 응답으로 변환되는지**에 대한 완전한 제어를 제공합니다. 요청 생명주기의 끝에 위치하여, 요청 어디서든 던져진 예외를 잡고 오류 응답 포맷, 상태, 로깅을 커스터마이징하게 합니다.

## 기본 exception filter

```ts
import { ExceptionFilter, Catch, ArgumentsHost, HttpException } from "@nestjs/common";

@Catch(HttpException)                    // HttpException을 특정하여 잡음
export class HttpExceptionFilter implements ExceptionFilter {
  catch(exception: HttpException, host: ArgumentsHost) {
    const ctx = host.switchToHttp();
    const response = ctx.getResponse();
    const request = ctx.getRequest();
    const status = exception.getStatus();

// 커스텀 오류 응답 형태 구성
    response.status(status).json({
      statusCode: status,
      timestamp: new Date().toISOString(),
      path: request.url,
      message: exception.message,
    });
  }
}
```

`@Catch()` decorator는 이 filter가 처리하는 예외 타입을 지정하며, `catch()` 메서드는 예외와 컨텍스트를 받아 — 원하는 어떤 응답이든 만들 수 있게 합니다.

## 모든 예외 잡기 (HTTP가 아닌 것 포함)

```ts
@Catch()                                 // 인수 없음 = 모든 것을 잡음
export class AllExceptionsFilter implements ExceptionFilter {
  catch(exception: unknown, host: ArgumentsHost) {
    const ctx = host.switchToHttp();
    const status = exception instanceof HttpException
      ? exception.getStatus()
      : 500;                              // 알 수 없는 오류 → 500
    // 전체 오류를 내부적으로 로깅, 클라이언트에는 안전한 메시지 반환
    this.logger.error(exception);
    ctx.getResponse().status(status).json({ statusCode: status, message: "..." });
  }
}
```

`@Catch()`(인수 없음)를 가진 filter는 모든 예외를 처리합니다 — 예상치 못한 오류를 로깅하고 HTTP가 아닌 오류조차 깔끔하고 안전한 응답을 반환하도록 보장하는 곳입니다(클라이언트에 스택 트레이스를 누출하지 않음).

## filter 적용하기

```ts
@UseFilters(HttpExceptionFilter)         // 메서드 또는 controller 수준
export class UsersController {}

app.useGlobalFilters(new AllExceptionsFilter());   // 전역 — 앱 전체, 가장 일반적
```

Filter는 보통 전체 API에 일관된 오류 포맷을 강제하기 위해 **전역으로** 적용됩니다.

## 왜 exception filter를 사용하나요?

```text
✓ 모든 엔드포인트에 걸쳐 일관된 오류 응답 포맷 (표준 형태)
✓ 중앙화된 오류 로깅 (모든 오류를 한 곳에서 로깅)
✓ HTTP가 아닌 오류를 안전하게 처리 (예상치 못한 오류를 깔끔한 500으로 변환)
✓ 클라이언트로부터 내부 세부 정보 숨김 (스택 트레이스 누출 없음 — 보안)
✓ 오류 응답에 컨텍스트 추가 (요청 경로, timestamp, correlation ID)
```

## filter 대 예외 던지기

```text
예외 던지기 (NotFoundException 등) → 상태와 함께 오류를 알림(SIGNAL)
Exception filter → 그 오류가 응답으로 어떻게 포맷/로깅되는지 제어
→ 코드에서 예외를 던지고; filter가 결과 응답을 전역적으로 커스터마이징합니다.
```

## 왜 중요한가

Exception filter는 **일관되고 제어된 오류 처리**로 견고하고 전문적인 API를 구축하는 중요한 NestJS 기능입니다.

NestJS의 내장 예외 계층이 이미 던져진 예외를 HTTP 응답으로 변환하지만, exception filter는 그 동작을 커스터마이징하는 완전한 제어를 제공합니다 — 이는 몇 가지 실제 관심사에 중요합니다: 모든 엔드포인트에 걸쳐 **일관된 오류 응답 형태** 강제(클라이언트가 항상 동일한 포맷으로 오류를 받도록), **오류 로깅 중앙화**(흩어진 try/catch가 아니라 한 곳에서 모든 오류 캡처), 예상치 못한 HTTP가 아닌 오류를 안전하게 **처리**(충돌하거나 세부 정보를 누출하는 대신 깔끔한 500으로 변환), 그리고 **보안**(내부 스택 트레이스와 민감한 세부 정보를 클라이언트로부터 숨기면서 내부적으로 로깅).

전역 "catch-all" filter와 코드에서 특정 HTTP 예외를 던지는 것을 결합하는 것은 프로덕션급 오류 처리의 표준 패턴입니다.

언제 그리고 어떻게 filter를 사용할지(단순히 예외를 던지는 것과 비교하여), 그리고 일관성을 위해 전역으로 적용하는 것을 이해하는 것은 잘 구축된 NestJS 애플리케이션의 특징이며, 종종 간과되지만 중요한 관심사인 오류 처리에 대한 성숙한 백엔드 실무를 반영합니다.