Skip to content

7. 请求的生命周期

从请求到达到响应发出之间,[Laravel] 会经历多个阶段,应用程序可以在每个阶段进行干预。我们已经遇到过其中几个:中间件(示例 03、12、16、22)、路由参数绑定(示例 12)以及异常处理程序(示例 08 和 12)。本章将它们汇集在一个示例中,该示例在每个步骤向控制台输出一条消息,以便你观察它们的顺序:

  • 1 和 7. 全局中间件,对所有请求执行,甚至早于路由。中间件组件包裹其余的处理过程:它在请求之前看到请求经过,在响应之后看到响应经过(示例 03)。[Laravel] 默认安装了若干个全局中间件(空字符串变为 [null]、维护模式、请求变为 CORS 等),按全局中间件列表的顺序执行;
  • 路由。[Laravel] 查找与 URL 和方法匹配的路由。如果没有匹配的路由,则抛出 [NotFoundHttpException] 异常(404);
  • 组中间件和路由中间件,按顺序执行:先是 [web] 组的中间件(Cookie、会话、表单错误、防 CSRF 保护、参数绑定),然后是路由自身的中间件。其中之一 [SubstituteBindings] 负责绑定路由参数(2,示例 12)。路由中间件(3 和 4)是执行特定于某些动作的检查的合适位置:下一章中的 [auth] 中间件就是这样工作的。如果其中之一在不调用 [$next] 的情况下返回了响应(或抛出了异常),处理就在此停止:动作不会被调用;
  • 5. 动作,以及它生成的视图;
  • 6. 中间件链的结束,按相反的顺序:每个组件从 [$next] 接收响应,可以修改它(添加头或 Cookie),并且必须将其返回;
  • 8. [terminate] 方法,由拥有该方法的中间件组件提供,在响应发送到浏览器之后执行。它们不能再修改响应:它们用于处理可以稍后进行的任务(写日志、发送统计信息等),而不让用户等待;
  • x. 异常处理程序:中间件组件、动作或视图抛出的异常,会被传给为其类注册的处理程序([render],位于 [bootstrap/app.php] 中),由它构造一个错误响应。然后,该响应会像普通响应一样,沿着中间件组件逐层传回。

这相当于 [Java] 中的过滤器、[Spring MVC] 中的拦截器、[ASP.NET Core MVC] 中的动作过滤器,以及 [Flask] 中的函数 [before_request] / [after_request]。[Laravel] 的独特之处在于,其中几乎一切都是中间件:同一个概念被用来处理所有请求(全局中间件)、一族路由(组)或少数几个路由。

7.1. 示例 24:处理请求的各个步骤

24-lifecycle/
├── app/
│   └── Http/
│       ├── Controllers/
│       │   └── CalcController.php
│       └── Middleware/
│           ├── Block.php
│           ├── Timing.php
│           └── Logger.php
├── bootstrap/
│   └── app.php
├── resources/
│   └── views/
│       ├── calc/
│       │   └── result.blade.php
│       ├── error.blade.php
│       └── layout.blade.php
├── routes/
│   └── web.php
└── ...

该应用程序只有一个动作,用于计算整数的平方:[/square/7]。根据 URL 的不同,它会成功,或以各种方式失败。消息由 [error_log] 函数(来自 [PHP])写入服务器控制台,该控制台由 [php artisan serve] 命令显示。

7.1.1. 全局中间件:app/Http/Middleware/Logger.php

<?php
// app/Http/Middleware/Logger.php:全局中间件,是所有中间件中的第一个:
// 它在应用程序其余部分之前看到每个请求经过,并在之后看到响应

namespace App\Http\Middleware;

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

class Logger
{
    public function handle(Request $request, Closure $next): Response
    {
        // error_log:开发服务器控制台中的一条消息
        error_log('--- '.$request->method().' '.$request->getRequestUri());
        error_log('1. global middleware Logger (before)');
        // 其余所有部分:其他中间件、路由、操作、视图
        $response = $next($request);
        error_log('7. global middleware Logger (after: code '.$response->getStatusCode().')');
        return $response;
    }
}
  • 第 16–17 行:中间件显示请求([getRequestUri()]:路径和参数)。这是第 1 号消息:此时 [Laravel] 中还什么都没有发生,甚至还没有进行路由;
  • 第 19 行:其余的处理都在这次调用之内进行;
  • 第 20 行:第 7 号消息,在其他一切都完成之后。[getStatusCode()] 是响应代码。

全局中间件不知道所选的路由,因为路由尚未进行。它用于适用于所有请求的处理:日志记录、压缩,以及处理代理([TrustProxies] 中间件,来自 [Laravel] ,当应用程序位于代理服务器之后时,它会校正客户端的地址;案例研究在涉及客户端 IP 地址时会讨论这一点)。

7.1.2. 参数映射:routes/web.php

<?php
// routes/web.php:示例 24 的路由

use App\Http\Controllers\CalcController;
use App\Http\Middleware\Block;
use App\Http\Middleware\Timing;
use Illuminate\Support\Facades\Route;

// 参数绑定:任何名为 {integer} 的路由参数在传给操作之前
// 都会由此函数转换:转换为整数,如果不是整数则为 null
// (此时由操作来决定)
Route::bind('integer', function (string $value) {
    error_log("2. binding of the parameter (received value: \"$value\")");
    $n = filter_var($value, FILTER_VALIDATE_INT);
    return $n === false ? null : $n;
});

// 路由:两个路由中间件,按此顺序在操作之前执行
Route::get('square/{integer}', [CalcController::class, 'square'])->name('square')
    ->middleware([Block::class, Timing::class]);
  • 第 12–16 行:[Route::bind] 注册一个显式绑定:任何名为 [{integer}] 的路由参数都会经过这个函数,它接收来自 URL 的文本,并返回动作将接收到的值。它接受任何文本并将其转换为整数,如果不是整数则转换为 [null] :与 [whereNumber] (示例 02)不同,后者对于 [/square/abc] 会返回 404 页面,而这里由动作来决定。它显示第 2 号消息。这是示例 12 中路由绑定的另一种形式,那个示例将参数绑定到一个类([UrlRoutable]);
  • 第 19–20 行:名为 [square] 的路由有两个路由中间件,它们将按此顺序执行,位于 [web] 组的中间件之后。

7.1.3. 路由中间件:Block.php 和 Timing.php

<?php
// app/Http/Middleware/Block.php:路由中间件,只对请求它的
// 路由执行

namespace App\Http\Middleware;

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

class Block
{
    public function handle(Request $request, Closure $next): Response
    {
        // $request->route():路由选中的路由;getName():其名称
        error_log('3. middleware Block (route: '.$request->route()->getName().')');
        if ($request->has('block')) {
            // 一个异常:其余部分(Timing、操作)不会执行
            abort(403);
        }
        return $next($request);
    }
}
  • 第 16 行:第 3 号消息。路由中间件知道所选的路由:[$request->route()] 返回该路由,而 [getName()] 返回它的名称;
  • 第 17–19 行:URL 的参数 [?block] ([has] 检查它是否存在)会引发 403 错误(*Forbidden*,拒绝访问):[abort] 抛出一个异常,从而中断处理。
<?php
// app/Http/Middleware/Timing.php:路由中间件,在操作之前和之后起作用,
// 然后在响应发送之后最后再起一次作用(terminate)

namespace App\Http\Middleware;

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

class Timing
{
    public function handle(Request $request, Closure $next): Response
    {
        error_log('4. middleware Timing (before)');
        // 开始时间(hrtime:精确的时钟,以纳秒计),存储
        // 在请求的属性中(请求作用域,见示例 12)
        $request->attributes->set('start', hrtime(true));
        $response = $next($request);
        error_log('6. middleware Timing (after: code '.$response->getStatusCode().')');
        return $response;
    }

    // terminate:在最后调用,即响应发送给浏览器之后;
    // 它不能再更改响应
    public function terminate(Request $request, Response $response): void
    {
        $start = $request->attributes->get('start');
        // 如果请求在此中间件之前就被阻止,测量就没有开始
        if ($start !== null) {
            $ms = round((hrtime(true) - $start) / 1e6);
            error_log("8. terminate Timing (end, $ms ms)");
        }
    }
}
  • 第 15–18 行:第 4 号消息,以及开始时间,存储在请求的属性中(示例 12)。[hrtime(true)] 是一个以纳秒为单位的精确时钟,专为测量持续时间而设计;
  • 第 20 行:第 6 号消息,在动作之后,附带响应代码;
  • 第 26–34 行:[terminate] 方法,由 [Laravel] 在响应发送之后调用,参数为请求和响应:第 8 号消息,附带自第 4 号消息以来经过的时间。[Laravel] 会对路由中的所有中间件组件调用它,即使它们没有被执行(当前面的某个中间件组件中断了处理时):第 30 行的检查用于验证计时是否已经开始。

7.1.4. 错误处理:bootstrap/app.php

<?php
// bootstrap/app.php:示例 24 的应用程序

use App\Http\Middleware\Logger;
use Illuminate\Foundation\Application;
use Illuminate\Foundation\Configuration\Exceptions;
use Illuminate\Foundation\Configuration\Middleware;
use Symfony\Component\HttpKernel\Exception\HttpExceptionInterface;

(require __DIR__.'/../../vendor/autoload.php')->addPsr4('App\\', __DIR__.'/../app/');

return Application::configure(basePath: dirname(__DIR__))
    ->withRouting(
        web: __DIR__.'/../routes/web.php',
        // 提供 Bootstrap 的路由(见示例 15)
        then: fn () => require __DIR__.'/../../common/bootstrap.php')
    ->withMiddleware(function (Middleware $middleware): void {
        // prepend:全局 Logger 中间件排在所有其他中间件之前
        $middleware->prepend(Logger::class);
    })
    ->withExceptions(function (Exceptions $exceptions): void {
        // 给定类型的「意外」异常:DomainException 及其子类
        $exceptions->render(function (DomainException $e) {
            error_log("x. render DomainException ({$e->getMessage()})");
            // 不使用默认错误页面,而使用我们的 [error] 视图,状态码为 500
            return response()->view('error', ['code' => 500], 500);
        });
        // HTTP 错误(abort(400)、abort(403)、未知页面 -> 404...):
        // HttpExceptionInterface 是所有 HTTP 异常的接口
        $exceptions->render(function (HttpExceptionInterface $e) {
            error_log("x. render HttpException (code {$e->getStatusCode()})");
            return response()->view('error', ['code' => $e->getStatusCode()], $e->getStatusCode());
        });
    })
    ->create();
  • 第 19 行:[prepend] 将全局中间件放在列表的最前面:它先于所有其他中间件运行,并在所有其他中间件之后看到响应;
  • 第 23–27 行:针对 [DomainException] 类(及其子类;参见示例 08)的异常处理程序:“意外”错误被转换为状态码为 500 的自定义错误页面(*Internal Server Error*)。异常消息显示在控制台中,但不显示在页面上:它可能包含与用户无关的内部细节;
  • 第 30–33 行:针对所有 HTTP 错误的处理程序。[abort(400)]、[abort(403)]、指向不存在路由的 URL(404)、被禁止的方法(405):所有这些都会抛出一个实现了 [HttpExceptionInterface] 接口(来自 [Symfony])的异常,并且该异常包含它的代码([getStatusCode()])。因此,这一个处理程序就用我们自己的页面取代了 [Laravel] 所有的英文错误页面。

[Laravel] 将异常传给第一个参数类型与之匹配的处理程序。没有处理程序的异常会变成 500 错误:在调试模式下,这是详细页面(示例 03);在非调试模式下,则是标准的 500 错误页面。还有另一种更简单的替换错误页面的方式:名为 [resources/views/errors/404.blade.php] 的视图会替换 404 错误页面,每个错误代码都同样适用(示例 26 采用这种方式)。而 [render] 处理程序则允许任何类型的处理:日志消息、JSON 响应、重定向……

7.1.5. 控制器和错误页面

<?php
// app/Http/Controllers/CalcController.php:受两个中间件保护的操作

namespace App\Http\Controllers;

use DomainException;
use Illuminate\View\View;

class CalcController
{
    // $n:路由参数 {integer},由 Route::bind 绑定(见 routes/web.php);
    // 绑定为 null 的参数不会传给操作:因此有默认值
    public function square(?int $n = null): View
    {
        error_log("5. action square($n)");
        if ($n === null) {
            abort(400);    // 400 错误:见 bootstrap/app.php
        }
        if ($n === 13) {
            throw new DomainException('13 brings bad luck');    // 一个「意外」错误
        }
        return view('calc.result', ['n' => $n, 'square' => $n * $n]);
    }
}
  • 第 13 行:参数 [$n] 接收由 [Route::bind] 绑定的值。[Laravel] 不会把绑定为 [null] 的参数传给动作:因此动作的参数带有默认值 [null],在这种情况下它就是参数的值;
  • 第 17 行:参数不是整数:400 错误;
  • 第 20 行:数字 13 会引发一个“意外”错误。[DomainException] 是 [PHP] 标准库中的一个异常类;
  • 第 22 行:正常情况。
@extends('layout')
{{-- the error page; its model: the error code --}}

@section('content')
  <div class="alert alert-danger">
    <h1 class="h4">Error {{ $code }}</h1>
    <p class="mb-0">
      @switch($code)
        @case(400) Bad request. @break
        @case(403) Access denied. @break
        @case(404) Page not found. @break
        @default Internal server error.
      @endswitch
    </p>
  </div>
@endsection

错误页面接收错误代码并显示相应的消息。[@switch] 指令根据一个值选择一个代码块:[@case] 指定一个值,[@break] 结束该代码块,[@default] 处理其他值。视图 [calc/result.blade.php] 只是显示结果。

7.1.6. 执行

正常情况,[/square/7]:

Image

服务器控制台按顺序显示这八个步骤:

  --- GET /square/7
  1. global middleware Logger (before)
  2. binding of the parameter (received value: "7")
  3. middleware Block (route: square)
  4. middleware Timing (before)
  5. action square(7)
  6. middleware Timing (after: code 200)
  7. global middleware Logger (after: code 200)
  8. terminate Timing (end, 5 ms)
  2026-09-26 18:19:51 /square/7 .................................... ~ 0.35ms

最后一行是开发服务器的日志,在请求完成后写入。访问被阻止的情况,[/square/7?block]:

Image

1
2
3
4
5
6
  --- GET /square/7?block
  1. global middleware Logger (before)
  2. binding of the parameter (received value: "7")
  3. middleware Block (route: square)
  x. render HttpException (code 403)
  7. global middleware Logger (after: code 403)

第一个路由中间件抛出了异常:第二个中间件和动作都没有执行。由处理程序生成的错误响应被传回全局中间件。[terminate] 被调用了,但没有显示任何内容,因为计时没有开始。参数不是整数的情况,[/square/abc]:

Image

  --- GET /square/abc
  1. global middleware Logger (before)
  2. binding of the parameter (received value: "abc")
  3. middleware Block (route: square)
  4. middleware Timing (before)
  5. action square()
  x. render HttpException (code 400)
  6. middleware Timing (after: code 400)
  7. global middleware Logger (after: code 400)
  8. terminate Timing (end, 6 ms)

这一次,动作以 [null] 被调用(它被渲染为空字符串:[square()]),而引发 400 错误的正是这个动作。“意外”错误,[/square/13]:

Image

  --- GET /square/13
  1. global middleware Logger (before)
  2. binding of the parameter (received value: "13")
  3. middleware Block (route: square)
  4. middleware Timing (before)
  5. action square(13)
  x. render DomainException (13 brings bad luck)
  6. middleware Timing (after: code 500)
  7. global middleware Logger (after: code 500)
  8. terminate Timing (end, 3 ms)

异常由其处理程序处理:尽管调试模式已启用,用户看到的仍是“自定义”错误页面,而不是详细页面。该异常仍会记录在 [storage/logs/laravel.log] 日志中:[Laravel] 区分异常的报告(*report*,即它在日志中的条目)和它的渲染(*render*,即响应)。最后,是一个不对应任何路由的 URL,[/unknown]:

1
2
3
4
  --- GET /unknown
  1. global middleware Logger (before)
  x. render HttpException (code 404)
  7. global middleware Logger (after: code 404)

路由失败:没有连接,没有路由中间件,也没有动作。404 页面是我们自己的:

curl http://localhost:8000/unknown
1
2
3
4
5
6
7
...
        <div class="alert alert-danger">
    <h1 class="h4">Error 404</h1>
    <p class="mb-0">
       Page not found.     </p>
  </div>
...

让我们抓住要点。路由中间件是放置许多动作共有的检查的合适位置(用户是否已登录?他们是否有权访问该动作?):下一章用它来实现身份验证。异常处理程序和视图([errors/...]) 确保无论发生什么错误,用户都不会看到技术性页面:案例研究利用了这一点。