NestJS'de istisnalar (exceptions) nasıl işlenir?

Question

Accepted Answer

NestJS **yerleşik bir istisna katmanı (exception layer)** ile gelir ve işlenmemiş hataları otomatik olarak yakalar, bunları uygun HTTP yanıtlarına dönüştürür. İstisnaları **fırlatarak (throwing exceptions)** (genellikle yerleşik HTTP istisna sınıfları kullanarak) sinyal verirsiniz ve Nest bunları doğru durum kodu (status code) ile yapılandırılmış JSON yanıtlarına biçimlendirir.

## Yerleşik HTTP istisnalarını fırlatma

```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 durum kodlarına eşleştirilmiş istisna sınıfları sağlar ve birini fırlatmak otomatik olarak doğru, yapılandırılmış bir yanıt üretir:

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

## Yaygın yerleşik HTTP istisnalar

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

Her yaygın HTTP hatası için bir sınıf vardır — doğru durum kodunu iletişim kurmak için uygun olanı kullanın.

## Özel mesajlar ve genel HttpException

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

## Özel istisna sınıfları

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

## İşlenmeyen hatalar 500 haline gelir

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

## Global özelleştirme için istisna filtreleri

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

Tutarlı hata biçimlendirmesi, günlüğe kaydetme veya HTTP olmayan hatalarla başa çıkmak için **istisna filtreleri** (daha ileri, ilişkili bir özellik) kullanırsınız.

## Neden önemli

Uygun istisna işlemesi güvenilir API'ler oluşturmak için gereklidir ve NestJS'nin yerleşik istisna katmanı bunu temiz ve tutarlı hale getirir.

**HTTP istisnalarını fırlatmayı** (`NotFoundException`, `BadRequestException`, vb.) anlamak günlük bilgidir — bu, her işleyicide hata yanıtlarını manuel olarak oluşturmadan doğru durum kodları ve yapılandırılmış, istemci dostu JSON yanıtları ile hataları sinyal vermenin deyimsel yoludur.

Kaynak, bu istisnaları otomatik olarak yakalar ve biçimlendirir ve beklenmeyen hataları, dahili ayrıntıları açığa çıkarmadan (güvenlik açısından önemli) genel 500'lere güvenle dönüştürür.

Yaygın istisna sınıflarını bilmek, özel mesajlar/istisnalar fırlatmayı ve **istisna filtrelerinin** global özelleştirme (tutarlı biçimlendirme, günlüğe kaydetme) için var olduğunu bilmek, güçlü, profesyonel NestJS API'leri oluşturmak için temeldir.

Temiz, tutarlı hata işlemesi kaliteli arka uç kodunun bir işaretidir ve bu, çerçevenin temel, sık kullanılan yönüdür.