第03回: ミドルウェアパイプライン詳細 — リクエストはコントローラに届く前に何をくぐっているのか？

(Updated: )
1 min read

章: 第1章: Laravel内部と設計基盤

「認証ミドルウェアを設定したはずなのに、なぜかAPIが素通りする」「ログが二重に出力される」――こうした不具合の多くは、ミドルウェアの 順序や適用範囲の誤解 から生まれます。

Laravelのミドルウェアは「パイプライン」として動作します。リクエストは複数のミドルウェアを順番にくぐり抜け、コントローラに到達します。この流れを正確に把握すれば、認証・ロギング・レート制限の問題を素早く特定できるようになります。

なぜミドルウェアの順序が重要なのか

ミドルウェアは 登録した順番 で実行されます。たとえば、セッション開始より前に認証チェックが動いてしまうと、セッション情報が読めずに認証失敗する――という事故が起きます。

チェックポイント: グローバルミドルウェアは「全リクエストに適用」、ルートミドルウェアは「特定ルートにのみ適用」。まずこの区分を明確にすることが大切です。

グローバル vs ルートミドルウェア

種類 適用範囲 典型的な用途
グローバルミドルウェア 全リクエスト プロキシ信頼設定、CORS
ミドルウェアグループ（web） webルート全体 セッション、Cookie暗号化
ミドルウェアグループ（api） APIルート全体 レート制限、認証
ルートミドルウェア 個別ルート 権限チェック、2FA確認

実装例


<?php
// app/Http/Kernel.php（概念）
protected $middleware = [
    \App\Http\Middleware\TrustProxies::class,
    \Illuminate\Http\Middleware\HandleCors::class,
];

protected $middlewareGroups = [
    'web' => [
        \App\Http\Middleware\EncryptCookies::class,
        \Illuminate\Session\Middleware\StartSession::class,
    ],
];

カスタムミドルウェアを書くときの注意点

カスタムミドルウェアで $next($request) の前後に処理を書く場合、前処理（リクエスト変換・ガード）と後処理（レスポンス加工・ログ）を意識的に分けましょう。


<?php
public function handle(Request $request, Closure $next): Response
{
    // 前処理（リクエストに対する操作）
    $request->headers->set('X-Trace-Id', Str::uuid());

    $response = $next($request);

    // 後処理（レスポンスに対する操作）
    $response->headers->set('X-Processed-At', now()->toIso8601String());

    return $response;
}

まとめ & 次のステップ

  • ミドルウェアはパイプラインとして順番に実行される ― 順序が挙動を決める
  • グローバル・グループ・ルートの3種を使い分けると責務が明確になる
  • $next($request) の前後で「前処理」「後処理」を使い分けられる
  • 不具合調査時は php artisan route:list でミドルウェアの適用状況を確認する

次回は 第04回: ルーティング高度化（Resource/Nested） で、URL設計とコントローラ責務をきれいに揃える方法を学びます。

Related Articles