NestJS におけるミドルウェアとは何ですか。また、guard や interceptor とどう違いますか？

Question

Accepted Answer

**ミドルウェア（middleware）**は、リクエストオブジェクトとレスポンスオブジェクトにアクセスでき、**ルートハンドラーの前に**実行される関数です。これは Express のミドルウェアと同じ概念です。NestJS にはさらに guard、interceptor、pipe、filter があり、それぞれリクエストライフサイクルの特定の地点で実行され、明確な目的を持っています。どれを使うべきかを知ることが重要です。

## ミドルウェア — 最初に実行され、req/res を持つ

```ts
@Injectable()
export class LoggerMiddleware implements NestMiddleware {
  use(req: Request, res: Response, next: NextFunction) {
    console.log(`${req.method} ${req.url}`);   // logging, modifying req
    next();                                      // MUST call next() to continue
  }
}

// register in a module
export class AppModule implements NestModule {
  configure(consumer: MiddlewareConsumer) {
    consumer.apply(LoggerMiddleware).forRoutes("*");   // apply to routes
  }
}
```

ミドルウェアは guard／interceptor／pipe よりも前、最も早い段階で実行され、生の `req`／`res` を扱います。 logging、リクエストの変更、CORS、Express 互換の関心事に適しています。

## リクエストライフサイクルの完全な順序

```text
Request →
  1. Middleware     (req/res; runs first, Express-style)
  2. Guards         (return true/false → AUTHORIZE or block the request)
  3. Interceptors   (BEFORE the handler)
  4. Pipes          (validate/transform the handler's arguments)
  5. → Route Handler ←
  6. Interceptors   (AFTER the handler — transform the response)
  7. Exception Filters (if an error was thrown anywhere)
→ Response
```

## それぞれの役割（適切なツールの選択）

```text
Middleware  → general pre-processing with req/res (logging, CORS, raw request work)
Guards      → AUTHORIZATION — decide if a request may proceed (auth, roles)
              (return true = allow, false/throw = block)
Interceptors→ wrap the handler — transform request/response, add logging/caching/timing
              (can run logic BEFORE and AFTER the handler)
Pipes       → VALIDATE/TRANSFORM the handler's input arguments (DTO validation)
Filters     → catch and format EXCEPTIONS into responses
```

重要な区別は次のとおりです。ミドルウェアは汎用的な Express 風の前処理を担います。**guard** は特に認可（authorization）を扱います（auth をミドルウェアに詰め込むのではなく、auth のためのきれいで専用の場所です）。**interceptor** はハンドラーをラップしてレスポンスを変換したり横断的な振る舞いを追加したりします。**pipe** は入力を検証します。**filter** はエラーを処理します。

## ミドルウェア・guard・interceptor をいつ使うか

```text
Auth check?           → Guard (dedicated, has execution context, returns boolean)
Logging requests?     → Middleware OR an interceptor (interceptor sees the response too)
Transform responses?  → Interceptor (runs after the handler)
Validate a DTO?       → Pipe
Modify raw req early?  → Middleware
```

## なぜ重要なのか

ミドルウェアと、それが guard、interceptor、pipe、filter とどう異なるかを理解することは、NestJS アプリケーションを正しく構造化するために不可欠です。それぞれが特定の役割を持ち、リクエストライフサイクルの特定の地点で実行され、適切なものを使うことでクリーンで慣用的なコードにつながります。

ミドルウェアは、生の req/res を用いた汎用的な Express 風の前処理を担います。

決定的な区別は、**guard** が認可（auth／roles）のための専用かつ適切な場所であること（その目的にはミドルウェアよりはるかにクリーンです）、そして **interceptor** がハンドラーをラップしてレスポンスを変換し、ミドルウェアでは容易にできない横断的関心事（logging、caching、timing）を追加できること（ミドルウェアはハンドラーの前に実行され、レスポンスを自然には見られないため）です。

ライフサイクルの完全な順序（middleware → guards → interceptors → pipes → handler → interceptors → filters）と、各関心事にどのツールが適合するか（auth → guard、レスポンス変換 → interceptor、検証 → pipe、エラー → filter）を知っていることは NestJS の習熟度を示すものであり、ミドルウェアを何にでも誤用するというよくある間違いを防ぎます。

これはこのフレームワークにおいて、頻繁に出題され、アーキテクチャ上も重要なトピックです。