Cum gestionezi excepții în NestJS?

Question

Accepted Answer

NestJS are un **strat de excepție încorporat** care detectează automat erorile negestionate și le transformă în răspunsuri HTTP corespunzătoare. Semnalizezi erorile prin **aruncare de excepții** (adesea clase de excepție HTTP încorporate), iar Nest le formatează în răspunsuri JSON structurate cu codul de stare corect.

## Aruncarea excepțiilor HTTP încorporate

```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 oferă clase de excepție care se mapează la coduri de stare HTTP, iar aruncarea uneia produce automat un răspuns corect și structurat:

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

## Excepții HTTP comune și încorporate

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

Există o clasă pentru fiecare eroare HTTP comună — folosește cea corespunzătoare pentru a comunica codul de stare corect.

## Mesaje personalizate și HttpException generic

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

## Clase de excepție personalizate

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

## Erorile negestionate devin 500s

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

## Filtre de excepție pentru personalizare globală

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

Pentru formatarea consecventă a erorilor, înregistrare sau gestionarea erorilor non-HTTP, folosești **filtre de excepție** (o caracteristică conexă, mai avansată).

## De ce contează

Gestionarea corespunzătoare a excepțiilor este esențială pentru construirea de API-uri fiabile, iar stratul de excepție încorporat al NestJS face acest lucru curat și consecvent.

Înțelegerea modului de **aruncare a excepțiilor HTTP** (`NotFoundException`, `BadRequestException`, etc.) este cunoaștere zilnică — aceasta este modalitatea idiomatică de a semnaliza erorile cu codurile de stare corecte și răspunsuri JSON structurate, ușor de utilizat pentru client, fără a construi manual răspunsuri de eroare în fiecare handler.

Framework-ul detectează automat acestea și le formatează, și convertește în siguranță erorile neașteptate în 500s generic fără a dezvălui detalii interne (important pentru securitate).

Cunoașterea claselor de excepție comune, modalitatea de aruncare a mesajelor/excepțiilor personalizate și faptul că **filtrele de excepție** există pentru personalizare globală (formatare consecventă, înregistrare) este fundamentală pentru construirea de API-uri NestJS robuste și profesionale.

Gestionarea erorilor curată și consecventă este o caracteristică a codului backend de calitate, ceea ce face din aceasta un aspect central și frecvent utilizat al framework-ului.