Jak obsługujesz wyjątki w NestJS?

Question

Accepted Answer

NestJS posiada **wbudowaną warstwę obsługi wyjątków**, która automatycznie przechwytuje nieobsługiwane błędy i konwertuje je na prawidłowe odpowiedzi HTTP. Sygnalizujesz błędy poprzez **rzucanie wyjątków** (często wbudowanych klas wyjątków HTTP), a Nest formatuje je w ustrukturyzowane odpowiedzi JSON z odpowiednim kodem statusu.

## Rzucanie wbudowanych wyjątków 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 dostarcza klasy wyjątków mapujące się na kody statusu HTTP, a rzucenie jednego powoduje automatycznie prawidłową, ustrukturyzowaną odpowiedź:

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

## Powszechne wbudowane wyjątki HTTP

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

Istnieje klasa dla każdego powszechnego błędu HTTP — użyj odpowiedniej, aby komunikować właściwy status.

## Niestandardowe komunikaty i generyczna klasa HttpException

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

## Niestandardowe klasy wyjątków

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

## Nieobsługiwane błędy stają się 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).
```

## Filtry wyjątków dla globalnej dostosowania

```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
```

Do spójnego formatowania błędów, logowania lub obsługi błędów spoza HTTP używasz **filtrów wyjątków** (powiązaną, bardziej zaawansowaną funkcję).

## Dlaczego to ważne

Prawidłowa obsługa wyjątków jest niezbędna do budowania niezawodnych API, a wbudowana warstwa wyjątków NestJS czyni to czystą i spójną.

Rozumienie, jak **rzucać wyjątki HTTP** (`NotFoundException`, `BadRequestException` itd.), to wiedza na co dzień — to idiomatyczny sposób sygnalizowania błędów z poprawnymi kodami statusu i ustrukturyzowanymi, przyjaznym dla klienta odpowiedziami JSON, bez ręcznego konstruowania odpowiedzi błędu w każdym handlerie.

Framework automatycznie je przechwytuje i formatuje, a bezpiecznie konwertuje nieoczekiwane błędy na generyczne 500 bez ujawniania szczegółów wewnętrznych (ważne dla bezpieczeństwa).

Znajomość powszechnych klas wyjątków, jak rzucać niestandardowe komunikaty/wyjątki i wiedza, że **filtry wyjątków** istnieją do globalnego dostosowania (spójne formatowanie, logowanie), jest fundamentalna do budowania niezawodnych, profesjonalnych API NestJS.

Czysta, spójna obsługa błędów jest cechą charakterystyczną wysokiej jakości kodu back-endowego, czyniąc to kluczowym, często używanym aspektem frameworku.