例外フィルター（Exception Filters）とは何ですか？

Question

Accepted Answer

**例外フィルター**を使うと、エラーがどのように**キャッチされてレスポンスに変換される**かを完全に制御できます。リクエストのライフサイクルの終端に位置し、リクエストのどこで投げられた例外でもキャッチして、エラーレスポンスの形式、ステータス、ロギングをカスタマイズできます。

## 基本的な例外フィルター

```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()` デコレーターはこのフィルターが処理する例外型を指定し、`catch()` メソッドは例外とコンテキストを受け取ります。これにより、任意のレスポンスを作成できます。

## すべての例外をキャッチする（HTTP以外を含む）

```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: "..." });
  }
}
```

`@Catch()` を引数なしで指定したフィルターは、すべての例外を処理します。予期しないエラーをログに記録し、HTTP以外のエラーでも、スタックトレースをクライアントに漏らさない安全でクリーンなレスポンスが返るようにできます。

## フィルターの適用

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

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

フィルターは通常、API全体で一貫したエラーフォーマットを強制するために**グローバル**に適用されます。

## なぜ重要なのか

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

## フィルター vs 例外を投げる

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

## なぜそれが重要なのか

例外フィルターは、**一貫した、制御されたエラーハンドリング**を備えた堅牢でプロフェッショナルな API を構築するための重要な NestJS 機能です。

NestJS の組み込み例外レイヤーは既に投げられた例外を HTTP レスポンスに変換していますが、例外フィルターはその動作をカスタマイズするための完全な制御を提供します。これは実際のいくつかの懸念事項に対して重要です。すべてのエンドポイント全体で**一貫したエラーレスポンスの形状**を強制する（クライアントが常に同じフォーマットでエラーを受け取る）こと、**エラーロギングを集約する**こと（散在した try/catch ではなく、1つの場所ですべてのエラーをキャプチャ）、予期しない HTTP 以外のエラーを安全に**処理する**こと（クラッシュしたり詳細を漏らしたりする代わりにクリーンな 500 に変換）、そして**セキュリティ**（クライアントから内部スタックトレースと機密情報を隠しながら内部的にログに記録）です。

グローバルな「全てをキャッチ」フィルターと、コード内で特定の HTTP 例外を投げることを組み合わせることが、本番級のエラーハンドリングの標準パターンです。

フィルターをいつ、どのように使うか（単に例外を投げるのではなく）を理解し、一貫性のためにそれらをグローバルに適用することは、よく構築された NestJS アプリケーションの特徴であり、エラーハンドリングという見落とされやすいが重要な懸念事項に関する成熟したバックエンドプラクティスを反映しています。