Как вы обрабатываете исключения в NestJS?

Question

Accepted Answer

NestJS имеет **встроенный слой обработки исключений**, который автоматически перехватывает необработанные ошибки и преобразует их в правильные HTTP-ответы. Вы сигнализируете об ошибках **выбросом исключений** (часто встроенные классы HTTP-исключений), и Nest форматирует их в структурированные JSON-ответы с правильным кодом статуса.

## Выброс встроенных HTTP-исключений

```ts
import { NotFoundException, BadRequestException, UnauthorizedException } from "@nestjs/common";

@Get(":id")
findOne(@Param("id") id: string) {
  const user = this.usersService.findOne(id);
  if (!user) {
    throw new NotFoundException("User not found");   // → 404 with a JSON error body
  }
  return user;
}
```

NestJS предоставляет классы исключений, соответствующие HTTP кодам статуса, и выброс одного из них автоматически создает правильный структурированный ответ:

```json
{ "statusCode": 404, "message": "User not found", "error": "Not Found" }
```

## Распространённые встроенные HTTP-исключения

```text
BadRequestException        → 400
UnauthorizedException      → 401
ForbiddenException         → 403
NotFoundException          → 404
ConflictException          → 409
UnprocessableEntityException → 422
InternalServerErrorException → 500
```

Для каждой распространённой HTTP-ошибки есть свой класс — используйте подходящий, чтобы передать клиенту правильный статус.

## Пользовательские сообщения и универсальный HttpException

```ts
// custom status + body via the base HttpException
throw new HttpException(
  { status: HttpStatus.FORBIDDEN, error: "custom message" },
  HttpStatus.FORBIDDEN,
);
```

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

```ts
export class UserNotFoundException extends NotFoundException {
  constructor(id: string) {
    super(`User with id ${id} not found`);   // domain-specific, reusable
  }
}
throw new UserNotFoundException(id);
```

## Необработанные ошибки становятся 500

```text
If code throws a non-HttpException error (e.g. a plain Error or an unexpected
exception), NestJS's default exception filter catches it and returns a generic
500 Internal Server Error (without leaking internal details to the client).
```

## Фильтры исключений для глобальной кастомизации

```ts
// a custom exception filter customizes how errors are formatted/logged globally
@Catch()
export class AllExceptionsFilter implements ExceptionFilter {
  catch(exception: unknown, host: ArgumentsHost) {
    // log, format the response, etc.
  }
}
app.useGlobalFilters(new AllExceptionsFilter());   // apply app-wide
```

Для согласованного форматирования ошибок, логирования или обработки не-HTTP ошибок используются **фильтры исключений** (связанная, более продвинутая функция).

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

Правильная обработка исключений необходима для создания надёжных API, а встроенный слой исключений NestJS делает это чистым и последовательным.

Понимание того, как **выбросить HTTP-исключение** (`NotFoundException`, `BadRequestException` и т.д.), — это повседневное знание — это идиоматический способ сигнализировать об ошибках с правильными кодами статуса и структурированными, удобными для клиента JSON-ответами без ручного конструирования ошибок в каждом обработчике.

Фреймворк автоматически перехватывает их и форматирует, а также безопасно преобразует неожиданные ошибки в универсальные 500 без раскрытия внутренних деталей (важно для безопасности).

Знание распространённых классов исключений, способ выброса пользовательских сообщений/исключений и того, что **фильтры исключений** существуют для глобальной кастомизации (согласованное форматирование, логирование), является фундаментальным для создания надёжных, профессиональных NestJS API.

Чистая, последовательная обработка ошибок — отличительная черта качественного back-end кода, что делает это основным, часто используемым аспектом фреймворка.