Что такое фильтры исключений?

Question

Accepted Answer

**Фильтры исключений** дают вам полный контроль над тем, как ошибки **перехватываются и преобразуются в ответы**. Они находятся в конце жизненного цикла запроса, перехватывают исключения, выброшенные где угодно в запросе, и позволяют вам настроить формат ошибки, статус и логирование.

## Базовый фильтр исключений

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

@Catch(HttpException)                    // catch HttpExceptions specifically
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();

// build a CUSTOM error response shape
    response.status(status).json({
      statusCode: status,
      timestamp: new Date().toISOString(),
      path: request.url,
      message: exception.message,
    });
  }
}
```

Декоратор `@Catch()` указывает, какие типы исключений обрабатывает этот фильтр, а метод `catch()` получает исключение и контекст — позволяя вам создать любой ответ, который вы хотите.

## Перехват ВСЕ исключений (включая non-HTTP)

```ts
@Catch()                                 // no argument = catch EVERYTHING
export class AllExceptionsFilter implements ExceptionFilter {
  catch(exception: unknown, host: ArgumentsHost) {
    const ctx = host.switchToHttp();
    const status = exception instanceof HttpException
      ? exception.getStatus()
      : 500;                              // unknown errors → 500
    // log the full error internally, return a safe message to the client
    this.logger.error(exception);
    ctx.getResponse().status(status).json({ statusCode: status, message: "..." });
  }
}
```

Фильтр с `@Catch()` (без аргумента) обрабатывает каждое исключение — место для логирования неожиданных ошибок и обеспечения того, чтобы даже non-HTTP ошибки возвращали чистый, безопасный ответ (без утечки трассировок стека клиентам).

## Применение фильтров

```ts
@UseFilters(HttpExceptionFilter)         // method or controller level
export class UsersController {}

app.useGlobalFilters(new AllExceptionsFilter());   // GLOBAL — app-wide, most common
```

Фильтры обычно применяются **глобально** для обеспечения согласованного формата ошибок во всем API.

## Зачем использовать фильтры исключений?

```text
✓ Consistent error response format across ALL endpoints (a standard shape)
✓ Centralized error LOGGING (log every error in one place)
✓ Handle non-HTTP errors safely (turn unexpected errors into clean 500s)
✓ Hide internal details from clients (no leaked stack traces — security)
✓ Add context (request path, timestamp, correlation IDs) to error responses
```

## Фильтры vs выброс исключений

```text
Throwing exceptions (NotFoundException, etc.) → SIGNALS an error with a status
Exception filters → control HOW those errors are FORMATTED/logged into responses
→ You throw exceptions in your code; filters customize the resulting response globally.
```

## Почему это важно

Фильтры исключений — это важная функция NestJS для создания надежных, профессиональных API с **согласованной, контролируемой обработкой ошибок**.

Хотя встроенный уровень исключений NestJS уже преобразует выброшенные исключения в HTTP ответы, фильтры исключений дают вам полный контроль для настройки этого поведения — что важно для нескольких практических задач: обеспечение **согласованного формата ответа об ошибке** на всех endpoints (чтобы клиенты всегда получали ошибки в одном формате), **централизованное логирование ошибок** (перехват каждой ошибки в одном месте вместо разбросанных try/catch), безопасная **обработка неожиданных non-HTTP ошибок** (их преобразование в чистые 500 вместо краха или утечки деталей), и **безопасность** (скрытие внутренних трассировок стека и конфиденциальных деталей от клиентов при логировании их внутри).

Глобальный фильтр "catch-all" в сочетании с выбросом специфичных HTTP исключений в вашем коде — это стандартный паттерн для обработки ошибок production-grade.

Понимание когда и как использовать фильтры (в сравнении с просто выбросом исключений), и применение их глобально для согласованности, является отличительной чертой хорошо построенных NestJS приложений и отражает зрелую back-end практику вокруг часто упускаемого, но критически важного вопроса обработки ошибок.