Exception filter'lar (istisna filtreleri) nedir?

Question

Accepted Answer

**Exception filter'lar (istisna filtreleri)**, hataların nasıl **yakalanıp yanıtlara dönüştürüleceği** üzerinde tam kontrol sağlar. İstek yaşam döngüsünün sonunda yer alır, istek içinde herhangi bir yerde fırlatılan istisnaları yakalar ve hata yanıtının biçimini, durum kodunu ve loglamayı özelleştirmenize olanak tanır.

## Temel bir exception filter

```ts
import { ExceptionFilter, Catch, ArgumentsHost, HttpException } from "@nestjs/common";

@Catch(HttpException)                    // catch HttpExceptions specifically
export class HttpExceptionFilter implements ExceptionFilter {
  catch(exception: HttpException, host: ArgumentsHost) {
    const ctx = host.switchToHttp();
    const response = ctx.getResponse();
    const request = ctx.getRequest();
    const status = exception.getStatus();

// build a CUSTOM error response shape
    response.status(status).json({
      statusCode: status,
      timestamp: new Date().toISOString(),
      path: request.url,
      message: exception.message,
    });
  }
}
```

`@Catch()` decorator'ı bu filtrenin hangi istisna türlerini ele alacağını belirtir ve `catch()` metodu istisnayı ve bağlamı (context) alır — böylece istediğiniz herhangi bir yanıtı oluşturabilirsiniz.

## TÜM istisnaları yakalama (HTTP olmayanlar dahil)

```ts
@Catch()                                 // no argument = catch EVERYTHING
export class AllExceptionsFilter implements ExceptionFilter {
  catch(exception: unknown, host: ArgumentsHost) {
    const ctx = host.switchToHttp();
    const status = exception instanceof HttpException
      ? exception.getStatus()
      : 500;                              // unknown errors → 500
    // log the full error internally, return a safe message to the client
    this.logger.error(exception);
    ctx.getResponse().status(status).json({ statusCode: status, message: "..." });
  }
}
```

Argümansız `@Catch()` kullanan bir filtre her istisnayı ele alır — beklenmeyen hataları loglamak ve HTTP olmayan hataların bile temiz, güvenli bir yanıt döndürmesini sağlamak için ideal yerdir (yığın izlerini (stack trace) istemcilere sızdırmadan).

## Filtreleri uygulama

```ts
@UseFilters(HttpExceptionFilter)         // method or controller level
export class UsersController {}

app.useGlobalFilters(new AllExceptionsFilter());   // GLOBAL — app-wide, most common
```

Filtreler genellikle tüm API genelinde tutarlı bir hata biçimini dayatmak için **global** olarak uygulanır.

## Neden exception filter kullanılır?

```text
✓ Consistent error response format across ALL endpoints (a standard shape)
✓ Centralized error LOGGING (log every error in one place)
✓ Handle non-HTTP errors safely (turn unexpected errors into clean 500s)
✓ Hide internal details from clients (no leaked stack traces — security)
✓ Add context (request path, timestamp, correlation IDs) to error responses
```

## Filtreler ile istisna fırlatma karşılaştırması

```text
Throwing exceptions (NotFoundException, etc.) → SIGNALS an error with a status
Exception filters → control HOW those errors are FORMATTED/logged into responses
→ You throw exceptions in your code; filters customize the resulting response globally.
```

## Neden önemli

Exception filter'lar, **tutarlı ve kontrollü hata yönetimi** ile sağlam, profesyonel API'ler oluşturmak için önemli bir NestJS özelliğidir.

NestJS'in yerleşik istisna katmanı, fırlatılan istisnaları zaten HTTP yanıtlarına dönüştürse de, exception filter'lar bu davranışı özelleştirmeniz için size tam kontrol sağlar — ki bu birçok gerçek ihtiyaç açısından önemlidir: her endpoint genelinde **tutarlı bir hata yanıtı biçimi** dayatmak (böylece istemciler hataları her zaman aynı formatta alır), **hata loglamayı merkezileştirmek** (her hatayı dağınık try/catch yerine tek bir yerde yakalamak), beklenmeyen HTTP olmayan hataları güvenli bir şekilde **ele almak** (çökmek veya ayrıntı sızdırmak yerine onları temiz 500'lere dönüştürmek) ve **güvenlik** (dahili yığın izlerini ve hassas ayrıntıları istemcilerden gizlerken bunları dahili olarak loglamak).

Global bir "hepsini yakala" filtresinin, kodunuzda belirli HTTP istisnaları fırlatmakla birleştirilmesi, üretim düzeyinde hata yönetimi için standart kalıptır.

Filtrelerin ne zaman ve nasıl kullanılacağını (yalnızca istisna fırlatmaya kıyasla) anlamak ve tutarlılık için onları global olarak uygulamak, iyi inşa edilmiş NestJS uygulamalarının bir göstergesidir ve hata yönetimi gibi sıklıkla gözden kaçan ama kritik bir konu etrafında olgun bir back-end pratiğini yansıtır.