Что такое exception filters в NestJS?

Exception Filters в NestJS

Exception filters — слой обработки ошибок в NestJS, который перехватывает исключения, вылетевшие из обработчиков маршрутов, и преобразует их в структурированный HTTP-ответ. Без фильтров NestJS использует встроенный GlobalExceptionFilter, который возвращает { statusCode, message, error } для HttpException и 500 Internal Server Error для всего остального.

Как работает фильтр

Фильтр реализует интерфейс ExceptionFilter<T> и декорируется @Catch(). Метод catch(exception, host) получает выброшенное исключение и ArgumentsHost — контекст, из которого можно получить объекты Request и Response.

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

    response.status(status).json({
      statusCode: status,
      // Добавляем timestamp и path для удобства отладки
      timestamp: new Date().toISOString(),
      path: request.url,
      message:
        typeof exceptionResponse === 'string'
          ? exceptionResponse
          : (exceptionResponse as any).message,
    });
  }
}

Уровни применения

Фильтр можно подключить на трёх уровнях:

• Метод/контроллер — через @UseFilters()
• Глобальный — через app.useGlobalFilters() или провайдер APP_FILTER

// Глобально через DI (позволяет инжектировать зависимости)
@Module({
  providers: [
    {
      provide: APP_FILTER,
      useClass: AllExceptionsFilter,
    },
  ],
})
export class AppModule {}

Перехват всех исключений

@Catch() без аргументов перехватывает любое исключение — удобно для глобального логирования.

@Catch()
export class AllExceptionsFilter implements ExceptionFilter {
  constructor(private readonly logger: Logger) {}

  catch(exception: unknown, host: ArgumentsHost) {
    const ctx = host.switchToHttp();
    const response = ctx.getResponse<Response>();

    // Определяем статус: HttpException даёт свой, остальное — 500
    const status =
      exception instanceof HttpException
        ? exception.getStatus()
        : 500;

    this.logger.error(exception);

    response.status(status).json({
      statusCode: status,
      message: 'Internal server error',
    });
  }
}

Порядок выполнения в pipeline

Exception filters стоят последними в цепочке: Middleware → Guards → Interceptors → Pipes → Controller → Interceptors (после) → Exception Filter. Если исключение выброшено в guard или pipe, фильтр всё равно его поймает.

Когда использовать

• Единый формат ошибок во всём API
• Логирование ошибок с контекстом запроса
• Преобразование доменных исключений (например, Prisma NotFoundError) в HttpException
• Скрытие внутренних деталей от клиента в production