インターセプターとは何ですか？

Question

インターセプターとは何ですか？

Accepted Answer

**インターセプター**はルートハンドラーの実行をラップし、実行**前後に**ロジックを実行したり、リクエストやレスポンスを変換できます。アスペクト指向プログラミングにインスピレーションを受けており、ロギング、レスポンス変換、キャッシング、タイミング計測などのクロスカッティングコンサーン（横断的関心事）に最適です。

## 構造：RxJSを使った前後処理

```ts
@Injectable()
export class LoggingInterceptor implements NestInterceptor {
  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
    console.log("Before handler");          // runs BEFORE the route handler
    const now = Date.now();

return next.handle().pipe(               // next.handle() = invoke the handler
      tap(() => console.log(`After: ${Date.now() - now}ms`)),   // runs AFTER
    );
  }
}
```

インターセプターは`intercept()`を実装します。`next.handle()`の前のコードはハンドラーの**前に**実行されます。`next.handle()`はレスポンスのRxJS`Observable`を返し、`tap`や`map`などのオペレーターを使えば、ハンドラー実行完了**後の**レスポンスに対して処理を実行できます。

## レスポンスの変換（よくあるユースケース）

```ts
@Injectable()
export class TransformInterceptor implements NestInterceptor {
  intercept(context: ExecutionContext, next: CallHandler) {
    return next.handle().pipe(
      map(data => ({ success: true, data, timestamp: new Date().toISOString() })),
      // wraps EVERY response in a consistent envelope: { success, data, timestamp }
    );
  }
}
```

`map`を使えば、インターセプターはすべてのレスポンスを再整形できます。例えば、すべてのレスポンスを標準的なエンベロープでラップする、という非常に一般的なパターンです。

## その他の強力な用途

```ts
// caching — return a cached response, skipping the handler entirely
// timeout — fail requests taking too long
return next.handle().pipe(timeout(5000));

// error mapping — transform exceptions
return next.handle().pipe(catchError(err => throwError(() => new BadGatewayException())));

// excluding fields (serialization) — ClassSerializerInterceptor strips @Exclude() fields
```

```text
Common interceptor uses:
  ✓ Logging / timing requests (before + after)
  ✓ Transforming responses (consistent envelopes, field exclusion)
  ✓ Caching responses
  ✓ Adding timeouts
  ✓ Mapping/handling errors
```

## インターセプターの適用

```ts
@UseInterceptors(LoggingInterceptor)   // method or controller level
app.useGlobalInterceptors(new TransformInterceptor());   // global
```

## インターセプター vs ミドルウェア vs ガード

```text
Middleware  → runs BEFORE everything, with raw req/res (can't easily touch the response)
Guard       → AUTHORIZATION decision (allow/block) before the handler
Interceptor → wraps the handler — runs BEFORE and AFTER, can TRANSFORM the response
```

定義的な特徴：インターセプターはハンドラーの**後に**ロジックを実行し、レスポンスを**変換する**ことができます。ミドルウェアとガードではこれを簡潔には実現できません。

## なぜ重要なのか

インターセプターはNestJSの強力な機能で、**クロスカッティングコンサーン**を優雅に扱うことができます。その特徴的な能力——ハンドラーの前後でロジックを実行し、レスポンスを変換できる——により、ミドルウェアとガードでは対応できないニーズに対する最適なツールとなります。

これを理解することが重要です。なぜなら、多くの一般的な要件がインターセプターにきれいにマップされるからです。例えば、一貫したレスポンスフォーマット（すべてのレスポンスを標準的な`{ success, data }`エンベロープでラップする）、ロギング・タイミング計測（ハンドラー実行時間を計測する）、キャッシング（キャッシュされたレスポンスを返す）、タイムアウト、エラー変換、シリアライゼーション（機密フィールドを除外する）などです。

構造（`next.handle()`Observable、および前後で処理を行う`tap`/`map`/`catchError`）、一般的なユースケース、そして特に**インターセプターがミドルウェアとガードとどう異なるのか**（レスポンスをラップして変換できる能力）を理解することは、NestJSアーキテクチャの基礎的な能力の重要な部分です。

インターセプターはクロスカッティングロジックを乾燥（DRY）で一元管理された状態にし、ハンドラー全体に重複するのを防ぎます。これにより、クリーンで保守性の高いNestJSアプリケーション構築のための、頻繁に使用される重要なツールとなります。