# 中间件（Middleware）

-   [介绍](#introduction)
-   [定义中间件](#defining-middleware)
-   [注册中间件](#registering-middleware)
    -   [全局中间件](#global-middleware)
    -   [将中间件分配给路由](#assigning-middleware-to-routes)
    -   [中间件组](#middleware-groups)
    -   [中间件别名](#middleware-aliases)
    -   [中间件排序](#sorting-middleware)
-   [中间件参数](#middleware-parameters)
-   [可终止中间件](#terminable-middleware)

## 介绍

中间件提供了一种便捷的机制，用于检查和过滤进入应用程序的 HTTP 请求。例如，Laravel 内置了一个用于验证用户是否已通过身份认证的中间件。如果用户未通过身份认证，中间件会将用户重定向到应用程序的登录页面。然而，如果用户已经通过认证，中间件将允许请求继续深入应用程序进行处理。

除了身份认证之外，还可以编写额外的中间件来执行各种任务。例如，日志中间件可以记录所有进入应用程序的请求。Laravel 内置了多种中间件，包括身份认证和 CSRF 防护等中间件；不过，所有用户自定义的中间件通常位于应用程序的 `app/Http/Middleware` 目录中。

## 定义中间件

要创建一个新的中间件，可以使用 `make:middleware` Artisan 命令：

```shell
php artisan make:middleware EnsureTokenIsValid
```

此命令会在 `app/Http/Middleware` 目录中创建一个新的 `EnsureTokenIsValid` 类。在这个中间件中，我们仅允许当传入的 `token` 参数与指定值匹配时访问该路由。否则，我们会将用户重定向回 `/home` URI：

```php
<?php

namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;
use Symfony\Component\HttpFoundation\Response;

class EnsureTokenIsValid
{
    /**
     * 处理传入的请求。
     *
     * @param  \Closure(\Illuminate\Http\Request): (\Symfony\Component\HttpFoundation\Response)  $next
     */
    public function handle(Request $request, Closure $next): Response
    {
        if ($request->input('token') !== 'my-secret-token') {
            return redirect('/home');
        }

        return $next($request);
    }
}
```



正如你所看到的，如果给定的 `token` 与我们的密钥 token 不匹配，中间件将向客户端返回一个 HTTP 重定向；否则，请求将被继续传递到应用程序的更深层。为了让请求继续深入应用程序（即允许中间件“放行”请求），你应该使用 `$request` 调用 `$next` 回调。

最好将中间件想象成 HTTP 请求在到达应用程序之前必须通过的一系列“层（layers）”。每一层都可以检查请求，甚至可以完全拒绝该请求。

> [!注意]
> 所有中间件都通过[服务容器](/docs/laravel/12.x/container)进行解析，因此你可以在中间件的构造函数中使用类型提示（type-hint）注入任何所需的依赖。

#### 中间件与响应（Middleware and Responses）

当然，中间件既可以在请求继续深入应用程序之前执行任务，也可以在之后执行任务。例如，下面的中间件会在请求被应用程序处理**之前**执行某些操作：

```php
<?php

namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;
use Symfony\Component\HttpFoundation\Response;

class BeforeMiddleware
{
    public function handle(Request $request, Closure $next): Response
    {
        // 执行操作

        return $next($request);
    }
}
```

然而，下面这个中间件会在请求被应用程序处理**之后**执行其任务：

```php
<?php

namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;
use Symfony\Component\HttpFoundation\Response;

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

        // 执行操作

        return $response;
    }
}
```
## 注册中间件

### 全局中间件

如果你希望某个中间件在应用程序的每一个 HTTP 请求期间都运行，你可以将其添加到应用程序 `bootstrap/app.php` 文件中的全局中间件栈：

```php
use App\Http\Middleware\EnsureTokenIsValid;

->withMiddleware(function (Middleware $middleware): void {
     $middleware->append(EnsureTokenIsValid::class);
})
```



`withMiddleware` 闭包中提供的 `$middleware` 对象是 `Illuminate\Foundation\Configuration\Middleware` 的一个实例，它负责管理分配给应用程序路由的中间件。`append` 方法会将中间件添加到全局中间件列表的末尾。如果你希望将中间件添加到列表的开头，应使用 `prepend` 方法。

#### 手动管理 Laravel 默认的全局中间件

如果你希望手动管理 Laravel 的全局中间件栈，可以通过 `use` 方法提供 Laravel 默认的全局中间件栈。然后，你可以根据需要调整默认中间件栈：

```php
->withMiddleware(function (Middleware $middleware): void {
    $middleware->use([
        \Illuminate\Foundation\Http\Middleware\InvokeDeferredCallbacks::class,
        // \Illuminate\Http\Middleware\TrustHosts::class,
        \Illuminate\Http\Middleware\TrustProxies::class,
        \Illuminate\Http\Middleware\HandleCors::class,
        \Illuminate\Foundation\Http\Middleware\PreventRequestsDuringMaintenance::class,
        \Illuminate\Http\Middleware\ValidatePostSize::class,
        \Illuminate\Foundation\Http\Middleware\TrimStrings::class,
        \Illuminate\Foundation\Http\Middleware\ConvertEmptyStringsToNull::class,
    ]);
})
```

### 将中间件分配给路由

如果你希望将中间件分配给特定路由，可以在定义路由时调用 `middleware` 方法：

```php
use App\Http\Middleware\EnsureTokenIsValid;

Route::get('/profile', function () {
    // ...
})->middleware(EnsureTokenIsValid::class);
```

你也可以通过向 `middleware` 方法传递一个中间件名称数组，为路由分配多个中间件：

```php
Route::get('/', function () {
    // ...
})->middleware([First::class, Second::class]);
```

#### 排除中间件

在将中间件分配给一组路由时，有时你可能需要阻止某个中间件应用于组中的某一条特定路由。你可以使用 `withoutMiddleware` 方法来实现：

```php
use App\Http\Middleware\EnsureTokenIsValid;

Route::middleware([EnsureTokenIsValid::class])->group(function () {
    Route::get('/', function () {
        // ...
    });

    Route::get('/profile', function () {
        // ...
    })->withoutMiddleware([EnsureTokenIsValid::class]);
});
```



你还可以将指定的一组中间件从整个[路由组](/docs/laravel/12.x/routing#route-groups)定义中排除：
```php
use App\Http\Middleware\EnsureTokenIsValid;

Route::withoutMiddleware([EnsureTokenIsValid::class])->group(function () {
    Route::get('/profile', function () {
        // ...
    });
});
```

`withoutMiddleware` 方法只能移除**路由中间件（route middleware）**，而不适用于[全局中间件](#global-middleware)。

### 中间件组

有时，你可能希望将多个中间件归为一个单独的键（key），以便更轻松地将它们分配给路由。你可以在应用程序的 `bootstrap/app.php` 文件中使用 `appendToGroup` 方法来实现：

```php
use App\Http\Middleware\First;
use App\Http\Middleware\Second;

->withMiddleware(function (Middleware $middleware): void {
    $middleware->appendToGroup('group-name', [
        First::class,
        Second::class,
    ]);

    $middleware->prependToGroup('group-name', [
        First::class,
        Second::class,
    ]);
})
```

中间件组可以像单个中间件一样，使用相同的语法分配给路由和控制器操作：

```php
Route::get('/', function () {
    // ...
})->middleware('group-name');

Route::middleware(['group-name'])->group(function () {
    // ...
});
```

#### Laravel 默认的中间件组

Laravel 内置了预定义的 `web` 和 `api` 中间件组，其中包含了一些常见中间件，这些中间件通常会应用于 Web 路由和 API 路由。请记住，Laravel 会自动将这些中间件组应用到对应的 `routes/web.php` 和 `routes/api.php` 文件：

<div class="overflow-auto">

| web 中间件组                            |
| --------------------------------------------------------- |
| `Illuminate\Cookie\Middleware\EncryptCookies`             |
| `Illuminate\Cookie\Middleware\AddQueuedCookiesToResponse` |
| `Illuminate\Session\Middleware\StartSession`              |
| `Illuminate\View\Middleware\ShareErrorsFromSession`       |
| `Illuminate\Foundation\Http\Middleware\PreventRequestForgery` |
| `Illuminate\Routing\Middleware\SubstituteBindings`        |

</div>

<div class="overflow-auto">

| api 中间件组                      |
| -------------------------------------------------- |
| `Illuminate\Routing\Middleware\SubstituteBindings` |

</div>



如果你想向这些中间件组追加（append）或前置（prepend）中间件，可以在应用程序的 `bootstrap/app.php` 文件中使用 `web` 和 `api` 方法。`web` 和 `api` 方法是 `appendToGroup` 方法的便捷替代方案：

```php
use App\Http\Middleware\EnsureTokenIsValid;
use App\Http\Middleware\EnsureUserIsSubscribed;

->withMiddleware(function (Middleware $middleware): void {
    $middleware->web(append: [
        EnsureUserIsSubscribed::class,
    ]);

    $middleware->api(prepend: [
        EnsureTokenIsValid::class,
    ]);
})
```

你甚至可以使用自定义中间件替换 Laravel 默认中间件组中的某个中间件：

```php
use App\Http\Middleware\StartCustomSession;
use Illuminate\Session\Middleware\StartSession;

$middleware->web(replace: [
    StartSession::class => StartCustomSession::class,
]);
```

或者，你也可以完全移除某个中间件：

```php
$middleware->web(remove: [
    StartSession::class,
]);
```

#### 手动管理 Laravel 默认中间件组

如果你希望手动管理 Laravel 默认 `web` 和 `api` 中间件组中的所有中间件，可以完全重新定义这些中间件组。下面的示例将使用它们的默认中间件来定义 `web` 和 `api` 中间件组，同时允许你根据需要进行自定义：

```php
->withMiddleware(function (Middleware $middleware): void {
    $middleware->group('web', [
        \Illuminate\Cookie\Middleware\EncryptCookies::class,
        \Illuminate\Cookie\Middleware\AddQueuedCookiesToResponse::class,
        \Illuminate\Session\Middleware\StartSession::class,
        \Illuminate\View\Middleware\ShareErrorsFromSession::class,
        \Illuminate\Foundation\Http\Middleware\PreventRequestForgery::class,
        \Illuminate\Routing\Middleware\SubstituteBindings::class,
        // \Illuminate\Session\Middleware\AuthenticateSession::class,
    ]);

    $middleware->group('api', [
        // \Laravel\Sanctum\Http\Middleware\EnsureFrontendRequestsAreStateful::class,
        // 'throttle:api',
        \Illuminate\Routing\Middleware\SubstituteBindings::class,
    ]);
})
```

> [!注意]
> 默认情况下，`web` 和 `api` 中间件组会由 `bootstrap/app.php` 文件自动应用到应用程序对应的 `routes/web.php` 和 `routes/api.php` 文件中。



### 中间件别名

你可以在应用程序的 `bootstrap/app.php` 文件中为中间件分配别名（alias）。中间件别名允许你为某个中间件类定义一个简短的别名，这对于类名较长的中间件尤其有用：

```php
use App\Http\Middleware\EnsureUserIsSubscribed;

->withMiddleware(function (Middleware $middleware): void {
    $middleware->alias([
        'subscribed' => EnsureUserIsSubscribed::class
    ]);
})
```

一旦在应用程序的 `bootstrap/app.php` 文件中定义了中间件别名，你就可以在将中间件分配给路由时使用该别名：

```php
Route::get('/profile', function () {
    // ...
})->middleware('subscribed');
```

为了方便，Laravel 的一些内置中间件默认已经设置了别名。例如，`auth` 中间件实际上是 `Illuminate\Auth\Middleware\Authenticate` 中间件的别名。以下是默认中间件别名列表：

<div class="overflow-auto">

| Alias              | Middleware                                                                                                    |
| ------------------ | ------------------------------------------------------------------------------------------------------------- |
| `auth`             | `Illuminate\Auth\Middleware\Authenticate`                                                                     |
| `auth.basic`       | `Illuminate\Auth\Middleware\AuthenticateWithBasicAuth`                                                        |
| `auth.session`     | `Illuminate\Session\Middleware\AuthenticateSession`                                                           |
| `cache.headers`    | `Illuminate\Http\Middleware\SetCacheHeaders`                                                                  |
| `can`              | `Illuminate\Auth\Middleware\Authorize`                                                                        |
| `guest`            | `Illuminate\Auth\Middleware\RedirectIfAuthenticated`                                                          |
| `password.confirm` | `Illuminate\Auth\Middleware\RequirePassword`                                                                  |
| `precognitive`     | `Illuminate\Foundation\Http\Middleware\HandlePrecognitiveRequests`                                            |
| `signed`           | `Illuminate\Routing\Middleware\ValidateSignature`                                                             |
| `subscribed`       | `\Spark\Http\Middleware\VerifyBillableIsSubscribed`                                                           |
| `throttle`         | `Illuminate\Routing\Middleware\ThrottleRequests` or `Illuminate\Routing\Middleware\ThrottleRequestsWithRedis` |
| `verified`         | `Illuminate\Auth\Middleware\EnsureEmailIsVerified`                                                            |

</div>

### 中间件排序

在少数情况下，你可能需要让中间件按照特定顺序执行，但却无法控制它们在路由中被分配的顺序。在这种情况下，你可以在应用程序的 `bootstrap/app.php` 文件中使用 `priority` 方法来指定中间件的执行优先级：

```php
->withMiddleware(function (Middleware $middleware): void {
    $middleware->priority([
        \Illuminate\Foundation\Http\Middleware\HandlePrecognitiveRequests::class,
        \Illuminate\Cookie\Middleware\EncryptCookies::class,
        \Illuminate\Cookie\Middleware\AddQueuedCookiesToResponse::class,
        \Illuminate\Session\Middleware\StartSession::class,
        \Illuminate\View\Middleware\ShareErrorsFromSession::class,
        \Illuminate\Foundation\Http\Middleware\PreventRequestForgery::class,
        \Laravel\Sanctum\Http\Middleware\EnsureFrontendRequestsAreStateful::class,
        \Illuminate\Routing\Middleware\ThrottleRequests::class,
        \Illuminate\Routing\Middleware\ThrottleRequestsWithRedis::class,
        \Illuminate\Routing\Middleware\SubstituteBindings::class,
        \Illuminate\Contracts\Auth\Middleware\AuthenticatesRequests::class,
        \Illuminate\Auth\Middleware\Authorize::class,
    ]);
})
```



## 中间件参数

中间件也可以接收额外参数。例如，如果你的应用程序需要在执行某个操作之前验证已认证用户是否拥有指定的“角色（role）”，你可以创建一个 `EnsureUserHasRole` 中间件，并接收角色名称作为额外参数。

额外的中间件参数会在 `$next` 参数之后传递给中间件：

```php
<?php

namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;
use Symfony\Component\HttpFoundation\Response;

class EnsureUserHasRole
{
    /**
     * 处理传入的请求。
     *
     * @param  \Closure(\Illuminate\Http\Request): (\Symfony\Component\HttpFoundation\Response)  $next
     */
    public function handle(Request $request, Closure $next, string $role): Response
    {
        if (! $request->user()->hasRole($role)) {
            // 重定向...
        }

        return $next($request);
    }
}
```

在定义路由时，可以通过 `:` 分隔中间件名称和参数来指定中间件参数：

```php
use App\Http\Middleware\EnsureUserHasRole;

Route::put('/post/{id}', function (string $id) {
    // ...
})->middleware(EnsureUserHasRole::class.':editor');
```

多个参数可以使用逗号 `,` 分隔：

```php
Route::put('/post/{id}', function (string $id) {
    // ...
})->middleware(EnsureUserHasRole::class.':editor,publisher');
```

## 可终止中间件

有时候，中间件可能需要在 HTTP 响应已经发送到浏览器之后再执行一些任务。如果你在中间件中定义了 `terminate` 方法，并且你的 Web 服务器使用的是 FastCGI ，那么在响应发送到浏览器后，`terminate` 方法会被自动调用：

```php
<?php

namespace Illuminate\Session\Middleware;

use Closure;
use Illuminate\Http\Request;
use Symfony\Component\HttpFoundation\Response;

class TerminatingMiddleware
{
    /**
     * 处理传入的请求。
     *
     * @param  \Closure(\Illuminate\Http\Request): (\Symfony\Component\HttpFoundation\Response)  $next
     */
    public function handle(Request $request, Closure $next): Response
    {
        return $next($request);
    }

    /**
     * 在响应发送到浏览器之后处理任务。
     */
    public function terminate(Request $request, Response $response): void
    {
        // ...
    }
}
```



`terminate` 方法应该同时接收请求（request）和响应（response）对象。在定义好一个可终止中间件（terminable middleware）之后，你应该将它添加到应用程序 `bootstrap/app.php` 文件中的路由中间件列表或全局中间件列表中。

当 Laravel 调用中间件的 `terminate` 方法时，它会从 Laravel Service Container 中解析（resolve）一个全新的中间件实例。

如果你希望在调用 `handle` 和 `terminate` 方法时使用同一个中间件实例，你可以通过容器的 `singleton` 方法将该中间件注册为单例（singleton）。通常，这应该在你的 `AppServiceProvider` 的 `register` 方法中完成：

```php
use App\Http\Middleware\TerminatingMiddleware;

/**
 * 注册应用程序服务。
 */
public function register(): void
{
    $this->app->singleton(TerminatingMiddleware::class);
}
```