深入理解 Laravel Middleware：從認證到 Rate Limiting

什麼是 Middleware？

Middleware 就像是 HTTP 請求的守門員。每一個進到你應用程式的請求，都會先經過 Middleware 的檢查。常見的用途包括認證、日誌記錄、CORS 設定等。

建立自訂 Middleware

php artisan make:middleware EnsureApiKeyIsValid

// app/Http/Middleware/EnsureApiKeyIsValid.php
class EnsureApiKeyIsValid
{
    public function handle(Request $request, Closure $next): Response
    {
        if ($request->header('X-API-Key') !== config('services.api_key')) {
            return response()->json([
                'error' => 'Invalid API key',
            ], 401);
        }

        return $next($request);
    }
}

註冊 Middleware

全域 Middleware

每個請求都會執行：

// bootstrap/app.php (Laravel 11+)
->withMiddleware(function (Middleware $middleware) {
    $middleware->append(LogRequestMiddleware::class);
})

路由 Middleware

只在特定路由生效：

Route::middleware(['auth', 'verified'])->group(function () {
    Route::get('/dashboard', [DashboardController::class, 'index']);
});

常見應用場景

1. 認證檢查

Laravel 內建的 auth Middleware 是最常用的：

Route::middleware('auth:sanctum')->group(function () {
    Route::get('/user', function (Request $request) {
        return $request->user();
    });
});

2. Rate Limiting

防止 API 被濫用：

// bootstrap/app.php
RateLimiter::for('api', function (Request $request) {
    return Limit::perMinute(60)->by(
        $request->user()?->id ?: $request->ip()
    );
});

3. CORS 設定

// config/cors.php
return [
    'paths' => ['api/*'],
    'allowed_methods' => ['*'],
    'allowed_origins' => ['https://yourfrontend.com'],
    'allowed_headers' => ['*'],
    'max_age' => 86400,
];

4. 語言切換

class SetLocale
{
    public function handle(Request $request, Closure $next): Response
    {
        $locale = $request->header('Accept-Language', 'zh-TW');
        app()->setLocale($locale);

        return $next($request);
    }
}

5. 回應加入自訂 Header

Middleware 不只能處理「請求」，也能修改「回應」：

class AddSecurityHeaders
{
    public function handle(Request $request, Closure $next): Response
    {
        $response = $next($request);

        $response->headers->set('X-Content-Type-Options', 'nosniff');
        $response->headers->set('X-Frame-Options', 'DENY');
        $response->headers->set('X-XSS-Protection', '1; mode=block');

        return $response;
    }
}

Middleware 的執行順序

Middleware 像洋蔥一樣層層包裹。請求從外到內通過每個 Middleware，回應則從內到外。理解這個順序很重要，特別是在做 API 設計 時。

搭配測試

public function test_unauthenticated_user_gets_redirected()
{
    $response = $this->get('/dashboard');
    $response->assertRedirect('/login');
}

public function test_rate_limiting()
{
    for ($i = 0; $i < 61; $i++) {
        $response = $this->getJson('/api/products');
    }
    $response->assertStatus(429);
}

小結

Middleware 是 Laravel 中非常強大的功能，善用它可以讓你的程式碼更乾淨、更有組織。把橫切關注點抽到 Middleware 裡，Controller 就能專注在業務邏輯上。搭配 Docker 環境做好開發環境設定，整體開發體驗會更順暢。

如果你需要類似的系統，歡迎聯繫討論。