中间件

简介

Middleware 提供了一种便捷的机制来检查和过滤进入应用程序的 HTTP 请求。例如，Laravel 包含一个 middleware，用于验证应用程序的用户是否已通过身份验证。如果用户未通过身份验证，middleware 会将用户重定向到应用程序的登录页面。但是，如果用户已通过身份验证，middleware 将允许请求继续深入应用程序。

除了身份验证之外，还可以编写额外的 middleware 来执行各种任务。例如，日志 middleware 可以记录所有进入应用程序的请求。Laravel 中包含了各种 middleware，包括用于身份验证和 CSRF 保护的 middleware；但是，所有用户自定义的 middleware 通常位于应用程序的 app/Http/Middleware 目录中。

定义 Middleware

要创建新的 middleware，请使用 make:middleware Artisan 命令：

shell

php artisan make:middleware EnsureTokenIsValid

此命令将在 app/Http/Middleware 目录中创建一个新的 EnsureTokenIsValid 类。在这个 middleware 中，我们只允许在提供的 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 与我们的密钥不匹配，middleware 将向客户端返回 HTTP 重定向；否则，请求将被继续传递到应用程序中。要将请求传递到应用程序的更深层（允许 middleware「通过」），你应该使用 $request 调用 $next 回调。

最好将 middleware 想象为一系列「层」，HTTP 请求在到达你的应用程序之前必须通过这些层。每一层都可以检查请求，甚至完全拒绝它。

NOTE

所有 middleware 都通过服务容器解析，因此你可以在 middleware 的构造函数中类型提示所需的任何依赖项。

Middleware 与响应

当然，middleware 可以在将请求传递到应用程序更深层之前或之后执行任务。例如，以下 middleware 将在应用程序处理请求之前执行某些任务：

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);
    }
}

而以下 middleware 将在应用程序处理请求之后执行其任务：

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;
    }
}

注册 Middleware

全局 Middleware

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

php

use App\Http\Middleware\EnsureTokenIsValid;

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

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

手动管理 Laravel 的默认全局 Middleware

如果你想手动管理 Laravel 的全局 middleware 栈，可以将 Laravel 的默认全局 middleware 栈提供给 use 方法。然后，你可以根据需要调整默认的 middleware 栈：

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 分配给路由

如果你想将 middleware 分配给特定路由，可以在定义路由时调用 middleware 方法：

php

use App\Http\Middleware\EnsureTokenIsValid;

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

你可以通过向 middleware 方法传递 middleware 名称数组来为路由分配多个 middleware：

php

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

排除 Middleware

当将 middleware 分配给一组路由时，你可能偶尔需要阻止 middleware 应用于组内的某个单独路由。你可以使用 withoutMiddleware 方法来实现：

php

use App\Http\Middleware\EnsureTokenIsValid;

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

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

你也可以从整个路由定义组中排除一组给定的 middleware：

php

use App\Http\Middleware\EnsureTokenIsValid;

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

withoutMiddleware 方法只能移除路由 middleware，不适用于全局 middleware。

Middleware 组

有时你可能想将多个 middleware 归组到一个键下，以便更容易地将它们分配给路由。你可以在应用程序的 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,
    ]);
})

Middleware 组可以使用与单个 middleware 相同的语法分配给路由和控制器操作：

php

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

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

Laravel 的默认 Middleware 组

Laravel 包含预定义的 web 和 api middleware 组，其中包含你可能想要应用于 Web 和 API 路由的常见 middleware。请记住，Laravel 会自动将这些 middleware 组应用于相应的 routes/web.php 和 routes/api.php 文件：

`web` Middleware 组
`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`

`api` Middleware 组
`Illuminate\Routing\Middleware\SubstituteBindings`

如果你想向这些组追加或前置 middleware，可以在应用程序的 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,
    ]);
})

你甚至可以用自己的自定义 middleware 替换 Laravel 默认 middleware 组中的某个条目：

php

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

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

或者，你可以完全移除某个 middleware：

php

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

手动管理 Laravel 的默认 Middleware 组

如果你想手动管理 Laravel 默认 web 和 api middleware 组中的所有 middleware，可以完全重新定义这些组。以下示例将使用默认 middleware 定义 web 和 api middleware 组，允许你根据需要进行自定义：

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,
    ]);
})

NOTE

默认情况下，web 和 api middleware 组由 bootstrap/app.php 文件自动应用于应用程序对应的 routes/web.php 和 routes/api.php 文件。

Middleware 别名

你可以在应用程序的 bootstrap/app.php 文件中为 middleware 分配别名。Middleware 别名允许你为给定的 middleware 类定义一个简短的别名，这对于类名较长的 middleware 特别有用：

php

use App\Http\Middleware\EnsureUserIsSubscribed;

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

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

php

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

为了方便起见，Laravel 的一些内置 middleware 默认已设置了别名。例如，auth middleware 是 Illuminate\Auth\Middleware\Authenticate middleware 的别名。以下是默认 middleware 别名的列表：

别名	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` 或 `Illuminate\Routing\Middleware\ThrottleRequestsWithRedis`
`verified`	`Illuminate\Auth\Middleware\EnsureEmailIsVerified`

Middleware 排序

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

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,
    ]);
})

Middleware 参数

Middleware 还可以接收额外的参数。例如，如果你的应用程序需要在执行给定操作之前验证已认证用户是否具有给定的「角色」，你可以创建一个 EnsureUserHasRole middleware，接收角色名称作为额外参数。

额外的 middleware 参数将在 $next 参数之后传递给 middleware：

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);
    }
}

Middleware 参数可以在定义路由时通过使用 : 分隔 middleware 名称和参数来指定：

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');

可终止的 Middleware

有时 middleware 可能需要在 HTTP 响应发送到浏览器后执行一些工作。如果你在 middleware 上定义了 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 方法应同时接收请求和响应。一旦定义了可终止的 middleware，你应该将其添加到应用程序的 bootstrap/app.php 文件中的路由或全局 middleware 列表中。

当在 middleware 上调用 terminate 方法时，Laravel 将从服务容器中解析一个新的 middleware 实例。如果你希望在调用 handle 和 terminate 方法时使用同一个 middleware 实例，请使用容器的 singleton 方法将 middleware 注册到容器中。通常应在 AppServiceProvider 的 register 方法中完成：

php

use App\Http\Middleware\TerminatingMiddleware;

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

中间件 ​

简介 ​

定义 Middleware ​

Middleware 与响应 ​

注册 Middleware ​

全局 Middleware ​

手动管理 Laravel 的默认全局 Middleware ​

将 Middleware 分配给路由 ​

排除 Middleware ​

Middleware 组 ​

Laravel 的默认 Middleware 组 ​

手动管理 Laravel 的默认 Middleware 组 ​

Middleware 别名 ​

Middleware 排序 ​

Middleware 参数 ​

可终止的 Middleware ​

中间件

简介