Come gestisci le eccezioni in NestJS?

Question

Accepted Answer

NestJS ha un **livello di eccezione integrato** che cattura automaticamente gli errori non gestiti e li trasforma in risposte HTTP corrette. Segnali gli errori **lanciando eccezioni** (spesso classi di eccezione HTTP integrate), e Nest le formatta in risposte JSON strutturate con il codice di stato corretto.

## Lanciare eccezioni HTTP integrate

```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 fornisce classi di eccezione mappate ai codici di stato HTTP, e lanciarne una produce una risposta corretta e strutturata automaticamente:

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

## Eccezioni HTTP integrate comuni

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

Esiste una classe per ogni errore HTTP comune — usa quella appropriata per comunicare lo stato corretto.

## Messaggi personalizzati e HttpException generica

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

## Classi di eccezione personalizzate

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

## Gli errori non gestiti diventano 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).
```

## Filtri di eccezione per la personalizzazione globale

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

Per la formattazione coerente degli errori, il logging o la gestione degli errori non HTTP, usi i **filtri di eccezione** (una funzionalità correlata e più avanzata).

## Perché è importante

La gestione corretta delle eccezioni è essenziale per costruire API affidabili, e il livello di eccezione integrato di NestJS lo rende pulito e coerente.

Capire come **lanciare eccezioni HTTP** (`NotFoundException`, `BadRequestException`, ecc.) è una conoscenza quotidiana — è il modo idiomatico per segnalare errori con i codici di stato corretti e risposte JSON strutturate e user-friendly, senza costruire manualmente risposte di errore in ogni handler.

Il framework cattura automaticamente questi e li formatta, e converte in sicurezza gli errori inaspettati in 500 generici senza esporre dettagli interni (importante per la sicurezza).

Conoscere le classi di eccezione comuni, come lanciare messaggi/eccezioni personalizzati, e che i **filtri di eccezione** esistono per la personalizzazione globale (formattazione coerente, logging) è fondamentale per costruire API NestJS robuste e professionali.

La gestione degli errori pulita e coerente è un segno distintivo del codice back-end di qualità, rendendo questo un aspetto centrale e frequentemente utilizzato del framework.