2. 动作、路由、响应
本章考察请求从浏览器到处理它的动作所经过的路径,以及该动作返回的响应。视图要到第 4 章才会讲到:在这里,动作直接返回文本或 JSON。
2.1. 示例 01:Laravel 应用的结构
第一个示例是尽可能小的 [Laravel] 应用。由 [composer create-project laravel/laravel] 创建的项目包含约五十个文件和文件夹(见简介);在这里,我们只保留应用不可缺少的那些:
| 01-structure/
├── bootstrap/
│ ├── cache/
│ └── app.php
├── public/
│ └── index.php
├── routes/
│ └── web.php
├── storage/
├── .env
├── artisan
└── composer.json
|
- [public/index.php]:应用的 入口点。所有 HTTP 请求,无论 URL 是什么,都由这个文件处理。[public] 文件夹是 Web 服务器唯一对外提供的文件夹:其中也包含静态文件(样式表、图片、脚本),并且只有这些;
- [bootstrap/app.php]:应用的构建与配置。[bootstrap/cache] 文件夹存放 [Laravel] 为加快启动而自行计算出的文件;
- [routes/web.php]:路由表,将每个 URL 与处理它的动作关联起来;
- [storage]:应用在运行期间写入的文件:错误日志([storage/logs])、会话、缓存和编译后的视图([storage/framework]);
- [.env]:应用配置,采用 [NAME=value] 键值对的形式;
- [artisan]:[Laravel] 的命令行工具;
- [composer.json]:[Composer] 的项目描述文件。
2.1.1. 入口点:public/index.php
| <?php
// public/index.php:所有 HTTP 请求的入口点
use Illuminate\Http\Request;
// Composer 的类加载器(examples/vendor 文件夹,共享)
require __DIR__.'/../../vendor/autoload.php';
// 由 bootstrap/app.php 构建的应用程序处理当前请求
$app = require_once __DIR__.'/../bootstrap/app.php';
$app->handleRequest(Request::capture());
|
- 第 1 行:[PHP] 文件以 [<?php] 标签开头。其后的一切都是 [PHP] 代码;只包含代码的文件不需要关闭该标签;
- 第 2 行:注释,从 [//] 到行尾([/* ... */] 用于界定多行注释);
- 第 4 行:语句 [use] 导入一个类名。[PHP] 中类的完整名称包含其 命名空间 (*namespace*),相当于 [Java] 中的包:[Illuminate\Http\Request] 是命名空间 [Request] 中的类 [Illuminate\Http]。在 [use] 之后,文件中可以直接把它称为 [Request]。[Illuminate] 是 [Laravel] 各组件的代号;
- 第 7 行:[require] 执行另一个 [PHP] 文件。[__DIR__] 是当前文件所在的目录(此处为 [public]);运算符 [.] 用于连接 两个字符串。文件 [vendor/autoload.php] 由 [Composer] 写入,它安装 类加载器:第一次使用某个类时,它会找到并加载定义该类的文件。多亏了这一点,我们永远不必为类编写 [require] 语句。[vendor] 文件夹就是 [examples] 文件夹中的那个,由所有示例共享(见简介):因此路径中有两个 [..] 目录;
- 第 10 行:由 [require] 执行的文件可以使用指令 [return] 返回一个值:[bootstrap/app.php] 返回 应用——一个类为 [Illuminate\Foundation\Application] 的对象——并存放在变量 [$app] 中。在 [PHP] 中,变量名总是以 [$] 开头。[require_once] 在文件已经执行过的情况下什么也不会做;
- 第 11 行:[Request::capture()] 调用类 [Request] 的 静态方法 [capture] (运算符 [::] 引用类的成员,而运算符 [->] 引用 对象的成员)。它根据 [PHP] 收到的 HTTP 请求创建一个 [Request] 对象。[$app->handleRequest(...)] 让应用处理这个请求,并把响应发送给浏览器。
这个文件对所有示例都相同,并且——除了两个 [..] 目录之外——与标准 [Laravel] 项目中的文件相同。它凸显了 [PHP] 的一个独特之处,这一点很好地解释了 [Laravel] 的许多行为:应用在每次请求时都会重新构建。Web 服务器对收到的每个请求都会从头到尾执行 [public/index.php] :加载类、构建应用、处理请求、发送响应,然后忘记一切。没有任何对象能在两次请求之间存活。在数据 作用域一章中,我们将看到这种行为的后果,它与 [Java]、[C#] 或 [Python] 恰好相反,后者的应用在两次请求之间一直驻留在内存中。
2.1.2. 应用结构:bootstrap/app.php
| <?php
// bootstrap/app.php:应用程序的构建与配置
use Illuminate\Foundation\Application;
// 本示例的类(App\ 命名空间)位于其 app/ 文件夹中
(require __DIR__.'/../../vendor/autoload.php')->addPsr4('App\\', __DIR__.'/../app/');
return Application::configure(basePath: dirname(__DIR__))
// 应用程序的路由由 routes/web.php 文件描述
->withRouting(web: __DIR__.'/../routes/web.php')
// 中间件与异常处理:使用默认设置
->withMiddleware()
->withExceptions()
->create();
|
- 第 7 行:[Composer] 的类加载器认识位于 [vendor] 文件夹中各个库的类。它还必须认识应用自己的类,按惯例这些类存放在 [app] 文件夹中,位于 [App] 命名空间下。在标准项目中,[Composer] 从项目的 [composer.json] 文件中获得这一信息。我们的示例共用一个名为 [vendor] 的文件夹,但每个示例都有自己的名为 [app] 的文件夹:因此每个示例都要自己通过加载器的 [addPsr4] 方法向它声明([PSR-4] 标准将命名空间映射到文件夹:类 [App\Http\Controllers\FirstController] 位于 [app/Http/Controllers/FirstController.php] 文件中)。[require] 返回被执行文件的值;[vendor/autoload.php] 返回加载器(即使执行两次,它也只安装一次)。在单引号括起的字符串中,[\\] 表示单个字符 [\]。这个示例还没有 [app] 文件:这一行是为后续示例准备的;
- 第 9 行:应用的构造。[Application::configure(...)] 返回一个 构建器对象(*builder*),它的每个方法配置应用的一个方面并返回构建器本身,从而允许链式调用;[create()] 最后构建出应用。参数 [basePath: dirname(__DIR__)] 是一个 命名参数:值通过名称而不是位置与参数 [basePath] 相关联。[dirname(__DIR__)] 是 [bootstrap] 的父文件夹——也就是示例所在的文件夹:[Laravel] 正是以这个文件夹为基准定位其他所有文件夹([routes]、[storage] 等);
- 第 11 行:应用的路由就是 [routes/web.php] 文件中的那些。名称 [web] 很有意义:这些路由会接收 [web] 组的 中间件(会话、加密 Cookie、CSRF 防护等),适合生成 HTML 页面的应用。我们将在各章中不断遇到它们;
- 第 13–14 行:中间件和异常处理,使用其默认设置。我们将在后面的示例中展开讲解。
2.1.3. 路由表:routes/web.php
| <?php
// routes/web.php:最小的 Laravel 应用程序,只有一个路由
use Illuminate\Support\Facades\Route;
// 一个操作:处理 GET / 请求时调用的函数
Route::get('/', function () {
// 函数返回的值就是发送给浏览器的响应
return 'Hello from Laravel!';
});
|
- 第 4 行:导入 [Route] 类。这是 [Laravel] 的一个 门面:这个类的静态方法([Route::get])会把调用转发给应用中的某个对象,此处是 路由器。门面是 [Laravel] 的标志性特征之一:它们让你无需获取提供服务的对象,就能快速访问应用的服务;
- 第 7–10 行:[Route::get] 声明一条 路由:对 [GET /] 的请求将由作为第二个参数指定的函数处理。这就是 路由。这个函数没有名字:它是一个 匿名函数——与其他任何值一样,可以作为参数传递。与路由关联的函数就是一个 动作。此外还有 [Route::post]、[Route::put]、[Route::delete] 等;
- 第 9 行:动作返回一个字符串。动作返回的值 就是 发送给浏览器的响应:[Laravel] 把它放入 HTTP 响应的正文中。用单引号括起的字符串(['...'])按原样写入;用双引号括起时(["..."]),其中包含的变量会被替换为它们的值(例如示例 02)。
2.1.4. 配置:.env
| # .env:应用程序的配置,每次安装各不相同
APP_NAME="Example 01"
# local:开发环境
APP_ENV=local
# 应用程序的密钥,由 php artisan key:generate 创建
APP_KEY=base64:g8MwuoKVJMhijOpvCTna/El25lmlLhjXCmmfqz3e3G8=
# true:显示详细的错误页面,用于开发(切勿用于生产环境)
APP_DEBUG=true
# 会话和缓存存储在文件中,位于 storage 文件夹下
SESSION_DRIVER=file
CACHE_STORE=file
|
文件 [.env] 包含应用某次具体安装所特有的设置:同一个应用,安装在开发者的机器上和安装在生产服务器上,其 [.env] 是不同的。此外,这个文件不得与源代码一起发布(它包含机密信息)。以 [#] 开头的行是注释。
- 第 2 行:应用名称。[Laravel] 会用它来给会话 Cookie 命名等([example01_session],见下文);
- 第 4 行:环境:[local] 用于开发,[production] 用于服务器;
- 第 6 行:应用的 密钥:32 个随机字节,以 base 64 编码。[Laravel] 用它来加密 Cookie 并对某些数据签名(后面还会讲到)。它由命令 [php artisan key:generate] 创建,该命令把它写入文件 [.env];每个示例都有自己的密钥。没有它,应用拒绝启动(“No application encryption key has been specified”);
- 第 8 行:调试模式:未处理的异常会显示一个详细页面(见示例 03)。此模式仅用于开发,且只能用于开发:错误页面会暴露应用的源代码和配置;
- 第 10–11 行:会话和缓存(见作用域一章)存储在 [storage] 文件夹内的文件中。默认情况下,[Laravel] 把它们存储在数据库中,而我们目前还没有数据库。
凡是 [Laravel] 在 [.env] 中找不到的设置都保持其默认值。这些默认值由框架的配置文件定义([vendor/laravel/framework/config/*.php]);标准项目在其 [config] 文件夹中有这些文件的副本,可以修改。我们的示例不用它们:[.env] 中的几行就足够了。
2.1.5. artisan 工具和 composer.json 文件
[artisan] 文件是一个 [PHP] 脚本,它与 [public/index.php] 一样构建应用,但目的是执行一条 命令 ,而不是处理请求:
| #!/usr/bin/env php
<?php
// artisan:Laravel 的命令行工具(php artisan serve、php artisan route:list...)
use Symfony\Component\Console\Input\ArgvInput;
// Composer 的类加载器:vendor 文件夹是 examples 文件夹的 vendor,
// 由所有示例共享
require __DIR__.'/../vendor/autoload.php';
// 由 bootstrap/app.php 构建的应用程序运行所请求的命令
$app = require_once __DIR__.'/bootstrap/app.php';
exit($app->handleCommand(new ArgvInput));
|
- 第 1 行:在 [Linux] 和 [macOS] 中,这一行使文件可以被直接执行([./artisan]);在 [Windows] 中,则始终输入 [php artisan];
- 第 13 行:[ArgvInput] 表示命令行参数([serve]、[route:list] 等);[handleCommand] 执行命令并返回其退出码。
[php artisan list] 显示可用命令的列表:约一百条,我们只会用到其中几条。最后,文件 [composer.json] 描述该示例:
| {
"name": "examples/01-structure",
"description": "Example 01: the structure of a Laravel application",
"autoload": {
"psr-4": {
"App\\": "app/"
}
}
}
|
这是一个 JSON 文档。[Laravel] 从这个文件中读取应用的类命名空间([App\],位于 [app/] 文件夹),例如它需要据此在错误页面中区分应用的代码和框架的代码。标准项目的 [composer.json] 文件还包含其库的列表;对于这些示例,该列表位于 [examples/composer.json] 文件中(见简介)。
2.1.6. 执行
在 [01-structure] 文件夹下打开的终端窗口中,输入 [php artisan serve]。[Laravel] 显示:
| INFO Server running on [http://127.0.0.1:8000].
Press Ctrl+C to stop the server
|
命令 [serve] 启动 [PHP] 内置的 开发服务器 ([php -S]),它被配置为把所有请求转发给 [public/index.php] (对位于 [public] 文件夹中的文件的请求除外,这些文件会原样发送)。它在地址 [127.0.0.1] 的 8000 端口上监听,该地址就是本机自身的地址([localhost]):它只接受来自本机的请求,适合开发([--host=0.0.0.0] 会向网络上的其他机器开放;[--port=8001] 会更改端口)。可用 [Ctrl-C] 停止它。这个服务器只用于开发:在生产环境中,将使用 [Apache] 或 [Nginx] 之类的 Web 服务器,并与 [PHP-FPM] 配合(见案例研究)。代码更改后无需重启它:因为 [PHP] 在每次请求时都会重新读取文件,所以更改会在下一次请求时生效。只有更改文件 [.env] 才需要重启,而命令 [serve] 会自动完成重启。
用浏览器请求 URL [http://localhost:8000/] :

然后用 [curl] 请求。[-i] 选项还会显示响应的 HTTP 头:
| curl -i http://localhost:8000/
|
| HTTP/1.1 200 OK
Host: localhost:8000
Connection: close
X-Powered-By: PHP/8.4.21
Content-Type: text/html; charset=utf-8
Cache-Control: no-cache, private
Date: Sat, 26 Sep 2026 15:49:59 GMT
Set-Cookie: XSRF-TOKEN=eyJpdiI6IjE4SzFkNE01dXZUOFhF...; expires=Sat, 26 Sep 2026 17:49:59 GMT; Max-Age=7200; path=/; samesite=lax
Set-Cookie: example01_session=eyJpdiI6IlpXcUdEaVkrTUFT...; expires=Sat, 26 Sep 2026 17:49:59 GMT; Max-Age=7200; path=/; httponly; samesite=lax
Hello from Laravel!
|
响应的第一行是协议版本、状态码(200)及其标签([OK])。接下来是各个头:所请求的主机、[Connection: close] (开发服务器在每次响应之后关闭连接)、[PHP] 的版本、内容 类型、缓存指令、日期以及两个 Cookie。一个空行把头与响应正文隔开。在本文档的其余部分,我们不再重复列出 [Host]、[Connection]、[X-Powered-By]、[Cache-Control] 和 [Date] 这些头——它们不会变化——也不再列出 Cookie,除非它们正是该示例的主题。
头 [Content-Type: text/html; charset=utf-8] 表明响应是 HTML,其字符以 UTF-8 编码。这是 [Laravel] 对动作返回的任何字符串所用的默认编码:因此浏览器把该字符串解释为 HTML(此处由于没有标签,会按原样显示)。示例 03 将说明如何指定其他类型。
这两个 Cookie 可能会让人意外:应用并没有请求其中任何一个。它们由 [web] 组中的两个中间件组件设置(见 [bootstrap/app.php]):[example01_session] 标识用户的 会话,而 [XSRF-TOKEN] 包含 CSRF 防护令牌。它们的值已 加密 ,密钥为 [APP_KEY]。我们将在示例 20 和 21 中考察它们。
对于每个请求,服务器控制台都会显示一条 日志:日期、所请求的路径和处理时间。
| 2026-09-26 17:49:51 / ............................................ ~ 0.09ms
|
2.2. 示例 02:路由
路由把 URL 和 HTTP 方法(GET、POST 等)与某个动作关联起来。如果把所有动作都以匿名函数的形式写在 [routes/web.php] 中,很快就会变得难以阅读;因此要把它们组织成类——即 控制器。示例 02 有两个控制器:
| 02-routing/
├── app/
│ └── Http/
│ └── Controllers/
│ ├── HomeController.php
│ └── FirstController.php
├── bootstrap/
│ └── app.php
├── routes/
│ └── web.php
└── ...
|
文件 [artisan]、[public/index.php]、[composer.json] 和 [.env],以及文件夹 [bootstrap/cache] 和 [storage],都与示例 01 中的相同:我们不再提及它们(只有示例名称和密钥会变化)。每个控制器都是 [App\Http\Controllers] 命名空间中的一个类,位于 [app/Http/Controllers] 文件夹中:这是 [Laravel] 的约定,标准 [PSR-4] 把二者对应起来(示例 01)。
2.2.1. 控制器 HomeController
| <?php
// app/Http/Controllers/HomeController.php:主页
namespace App\Http\Controllers;
class HomeController
{
// GET /:一个包含指向其他操作的链接的 HTML 页面。
// 操作返回的字符串以 text/html 类型发送
public function index(): string
{
return <<<'HTML'
<h2>Example 02 - routing</h2>
<ul>
<li><a href="/first">/first</a></li>
<li><a href="/first/action01">/first/action01</a></li>
<li><a href="/first/products/17">/first/products/17</a></li>
<li><a href="/first/products/17/reviews/3">/first/products/17/reviews/3</a></li>
<li><a href="/first/files/images/logo.png">/first/files/images/logo.png</a></li>
<li><a href="/first/products/abc">/first/products/abc</a></li>
<li><a href="/unknown">/unknown</a></li>
</ul>
HTML;
}
}
|
- 第 4 行:类的命名空间。因此它的完整名称是 [App\Http\Controllers\HomeController];
- 第 6 行:类。按照惯例,类名中每个单词的首字母大写([HomeController]),而方法名或变量名以小写字母开头([action01Post])。在 [Laravel] 中,控制器不需要继承任何类;
- 第 10 行:动作 [index],它是类的一个 public 方法(路由器只能调用 public 方法)。[: string] 声明返回值的类型:字符串。类型在 [PHP] 中是可选的,但一旦指定,[PHP] 就会在运行时检查它们;
- 第 12–23 行:多行字符串。语法 [<<<'HTML'] ... [HTML] (*nowdoc*)界定按原样书写的文本,位于包含同一个单词的两行之间,此处是 [HTML];结束行的缩进会从所有行中去除。该动作返回 HTML,以类型 [text/html] 发送(见示例 01)。
因此,动作 [index] 返回一个 HTML 页面,其中包含指向另一个控制器各动作的链接:

2.2.2. 控制器 FirstController
| <?php
// app/Http/Controllers/FirstController.php:/first/... URL 的操作
namespace App\Http\Controllers;
class FirstController
{
// GET /first
public function index(): string
{
return 'Action [index] of the [FirstController] controller';
}
// GET /first/action01
public function action01(): string
{
return 'Action [action01] of the [FirstController] controller, GET request';
}
// POST /first/action01
public function action01Post(): string
{
return 'Action [action01Post] of the [FirstController] controller, POST request';
}
// GET /first/products/17:路由参数 {id} 被传递给操作的
// $id 参数;int 类型将其转换为整数
public function product(int $id): string
{
return "Product no. $id";
}
// GET /first/products/17/reviews/3:两个路由参数
public function review(int $id, int $number): string
{
return "Review no. $number of product no. $id";
}
// GET /first/files/images/logo.png
public function file(string $path): string
{
return "Requested file: $path";
}
}
|
- 第 9–11 行:与另一个控制器中相同的 [index] 方法:不会冲突,因为每个控制器都是不同的类;
- 第 21–23 行:对应请求 [POST /first/action01] 的动作。动作的名称可以是任意的;是路由表把它与 URL 和 HTTP 方法关联起来;
- 第 28–30 行:动作的参数 [$id] 接收 路由参数 [{id}] 的值(见 [routes/web.php]):对于 URL [/first/products/17],它是 17。参数类型 [int] 指示 [PHP] 把该值(从 URL 中提取的字符串)转换为整数。这就是 数据绑定,下一章将详细讨论。在用引号括起的字符串 ["Product no. $id"] 中,变量 [$id] 被替换为它的值:这就是 插值;
- 第 34–36 行:两个路由参数,传给动作的两个参数。[Laravel] 按 名称将它们关联起来:动作参数的顺序无关紧要;
- 第 40–42 行:包含 [/] 的路由参数。
2.2.3. 路由表:routes/web.php
| <?php
// routes/web.php:示例 02 的路由表
use App\Http\Controllers\HomeController;
use App\Http\Controllers\FirstController;
use Illuminate\Support\Facades\Route;
// GET /:HomeController 类的 [index] 操作
Route::get('/', [HomeController::class, 'index']);
// 一组路由:/first 前缀和控制器由组内所有路由共享
Route::prefix('first')->controller(FirstController::class)->group(function () {
// GET /first:该组的 '/' 路由指的是前缀本身
Route::get('/', 'index');
// GET /first/action01
Route::get('action01', 'action01');
// POST /first/action01:路径相同,HTTP 方法不同,操作也不同
Route::post('action01', 'action01Post');
// GET /first/products/17:{id} 是路由参数;whereNumber
// 只接受数字
Route::get('products/{id}', 'product')->whereNumber('id');
// GET /first/products/17/reviews/3:两个路由参数
Route::get('products/{id}/reviews/{number}', 'review')->whereNumber(['id', 'number']);
// GET /first/files/...:.* 表达式接受任意路径结尾,
// 包括斜杠
Route::get('files/{path}', 'file')->where('path', '.*');
});
|
- 第 4–5 行:导入两个控制器;
- 第 9 行:动作不再是匿名函数,而是一个包含两个元素的数组:控制器类和方法名。[HomeController::class] 是类的完整名称,以字符串形式表示(['App\Http\Controllers\HomeController'])。对于每个 [GET /] 请求,[Laravel] 都会创建一个 [HomeController] 对象并调用它的方法 [index];
- 第 12 行:路由 组:在传给 [group] 的函数中声明的路由共享该组的设置。[prefix('first')] 在它们的路径前加上 [/first] ;[controller(FirstController::class)] 为它们指定控制器,于是每条路由只需写出其方法名。动作的 URL 是组前缀与其路由路径的拼接;
- 第 14 行:路由 ['/'] 指向前缀本身:[GET /first];
- 第 16–18 行:同一个 HTTP 路径对应两种方法:[GET] 和 [POST],它们由两个不同的动作处理。此外还有 [Route::match(['get', 'post'], ...)],用于处理多种方法的动作,以及 [Route::any],用于处理所有方法;
- 第 21 行:[{id}] 是一个 路由参数:URL 的这一段可以取多个值。默认情况下,参数接受任何不含斜杠的文本;[whereNumber('id')] 将 该参数限制为只能包含数字:否则路由不匹配。此外还有 [whereAlpha] (字母)、[whereUuid]、[whereIn('id', [...])] (值列表),以及 [where],它接受正则表达式;
- 第 23 行:两个路由参数,均受到约束([whereNumber] 接受一个名称数组)。在 [PHP] 中,[[a, b]] 是一个 数组 (*array*);
- 第 26 行:约束 [where('path', '.*')] 是一个正则表达式:[.] 表示任意字符,而 [*] 表示 其重复。因此该参数接受 URL 的任何结尾部分,包括 [/]。
2.2.4. 配置:bootstrap/app.php
| <?php
// bootstrap/app.php:示例 02 的应用程序
use Illuminate\Foundation\Application;
use Illuminate\Foundation\Configuration\Middleware;
(require __DIR__.'/../../vendor/autoload.php')->addPsr4('App\\', __DIR__.'/../app/');
return Application::configure(basePath: dirname(__DIR__))
->withRouting(web: __DIR__.'/../routes/web.php')
->withMiddleware(function (Middleware $middleware): void {
// 防 CSRF 保护(示例 21)会拒绝 curl 发送的 POST 请求
// :我们对 /first/... URL 排除该保护
$middleware->preventRequestForgery(except: ['first/*']);
})
->withExceptions()
->create();
|
- 第 11–15 行:这一次 [withMiddleware] 方法接收的是一个函数,[Laravel] 调用它时会传入描述应用中间件的 [$middleware] 对象。[: void] 表示该函数不返回任何内容。我们用它来为 URL 绕过 CSRF 防护 [/first/...]:这项防护(我们将在示例 21 中考察)会拒绝任何并非来自应用表单的 POST 请求——包括我们用 [curl] 发送的那些。名为 [except] 的参数指定要排除的路径列表,其中 [*] 代表任意字符序列。没有这一行,来自 [curl] 的 POST 请求会收到 419 错误响应(*Page Expired*)。
2.2.5. 执行
下面是几个请求的响应:
| curl -i http://localhost:8000/first
|
| HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
Action [index] of the [FirstController] controller
|
| curl -i http://localhost:8000/first/products/17/reviews/3
|
| HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
Review no. 3 of product no. 17
|
| curl -i http://localhost:8000/first/files/images/logo.png
|
| HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
Requested file: images/logo.png
|
要发送 POST 请求,请使用 [-X POST] 选项,它属于 [curl]:
| curl -i -X POST http://localhost:8000/first/action01
|
| HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
Action [action01Post] of the [FirstController] controller, POST request
|
如果没有任何动作处理该路径的这种 HTTP 方法,就会产生 405 错误([Method Not Allowed])。[allow] 头列出了可接受的方法;[Laravel] 还会添加 [HEAD] (与 GET 相同的请求,但没有响应正文),对任何 GET 路由它都会自行处理:
| curl -i -X PUT http://localhost:8000/first/action01
|
| HTTP/1.1 405 Method Not Allowed
allow: GET, HEAD, POST
Content-Type: text/html; charset=utf-8
<!DOCTYPE html>
<html lang="en">
<head>
...
<title>Example 02</title>
...
|
在调试模式下,响应正文是 [Laravel] 的详细错误页面,我们将在示例 03 中看到:它说明该路由不支持 PUT 方法(“The PUT method is not supported for route first/action01.” Supported methods: GET, HEAD, POST.”)。
最后,没有任何路由处理的 URL 会产生 404 错误。对于不是数字的标识符也是如此:约束 [whereNumber] 使路由无法匹配 [/first/products/abc]。
| curl -i http://localhost:8000/first/products/abc
|
| HTTP/1.1 404 Not Found
Content-Type: text/html; charset=utf-8
<!DOCTYPE html>
<html lang="en">
<head>
...
<title>Not Found</title>
...
|
响应是 [Laravel] 的错误页面,为英文。在浏览器中:

第 7 章将说明如何用应用专属的页面来替换它。还要注意,[Laravel] 不区分 [/first] 和 [/first/]:路由器会忽略末尾的斜杠,两种 URL 输入都会通向同一个动作。
在示例目录中运行命令 [php artisan route:list],会列出应用中的所有路由:
| GET|HEAD / ............................................................... HomeController@index
GET|HEAD first .......................................................... FirstController@index
GET|HEAD first/action01 .............................................. FirstController@action01
POST first/action01 .......................................... FirstController@action01Post
GET|HEAD first/files/{path} .............................................. FirstController@file
GET|HEAD first/products/{id} .......................................... FirstController@product
GET|HEAD first/products/{id}/reviews/{number} .......................... FirstController@review
GET|HEAD storage/{path} storage.local › .../vendor/laravel/framework/...
PUT storage/{path} storage.local.upload › .../vendor/laravel/framework/...
Showing [9] routes
|
每一行列出 HTTP 方法、路径和动作([Controller@method])。最后两条路由名为 [storage.local] 和 [storage.local.upload],由 [Laravel] 自己创建:它们提供应用存放在 [storage/app] 文件夹中的文件,前提是附带签名(签名 URL,只有应用知道如何生成)。我们不会使用它们。
2.3. 示例 03:动作的响应
动作返回什么决定了 HTTP 响应是什么。示例 03 回顾了主要的几种情况:
| 03-responses/
├── app/
│ ├── Http/
│ │ ├── Controllers/
│ │ │ └── ResponsesController.php
│ │ └── Middleware/
│ │ └── ReadableJson.php
│ └── Models/
│ └── Person.php
├── bootstrap/
│ └── app.php
├── routes/
│ └── web.php
└── ...
|
路由表把每个 URL [/responses/xxx] 映射到控制器动作 [xxx]:
| <?php
// routes/web.php:示例 03 的路由
use App\Http\Controllers\ResponsesController;
use Illuminate\Support\Facades\Route;
// Route::controller(...)->group(...):该组的所有路由都由
// 同一个控制器处理;只需给出操作的名称
Route::prefix('responses')->controller(ResponsesController::class)->group(function () {
Route::get('text', 'text');
Route::get('html', 'html');
Route::get('json', 'json');
Route::get('array', 'array');
Route::get('list', 'list');
Route::get('collection', 'collection');
Route::get('created', 'created');
Route::get('empty', 'empty');
Route::get('not-found', 'notFound');
Route::get('abort', 'abort');
Route::get('error', 'unexpectedError');
});
|
控制器 [ResponsesController]:
| <?php
// app/Http/Controllers/ResponsesController.php:操作的各种响应
namespace App\Http\Controllers;
use App\Models\Person;
use Illuminate\Http\JsonResponse;
use Illuminate\Http\Response;
use Illuminate\Support\Collection;
use RuntimeException;
class ResponsesController
{
// 一个声明为纯文本的字符串:浏览器原样显示。
// response():由操作自己构建的完整响应
public function text(): Response
{
return response('<h1>Action [text]</h1>')
->header('Content-Type', 'text/plain; charset=utf-8');
}
// 单独一个字符串:Laravel 以 text/html 类型发送;浏览器会解释它
public function html(): string
{
return '<h1>Action [html]</h1>';
}
// 一个对象:response()->json 将其序列化为 JSON,类型为 [application/json]
public function json(): JsonResponse
{
return response()->json(new Person('Martin', 'Jean', 42));
}
// 直接返回的关联数组:Laravel 自己将其序列化为 JSON
public function array(): array
{
return ['lastName' => 'Martin', 'firstName' => 'Jean', 'age' => 42];
}
// 索引数组:序列化为 JSON 数组
public function list(): array
{
return ['Mme', 'Melle', 'Mr'];
}
// Laravel 集合:同样会被序列化为 JSON
public function collection(): Collection
{
return collect([3, 1, 2])->sort()->values()->map(fn (int $n) => $n * 10);
}
// 使用 201 状态码(Created)而不是 200(OK)
public function created(): JsonResponse
{
return response()->json(['message' => 'resource created'], 201);
}
// 无响应:204 状态码(No Content)表示「没有要显示的内容」
public function empty(): Response
{
return response()->noContent();
}
// 一个「预期的」错误:状态码为 404 的 JSON 响应
public function notFound(): JsonResponse
{
return response()->json(['message' => 'This resource does not exist'], 404);
}
// 同样的效果,使用 abort:一个 HTTP 异常,Laravel 将其转换为 404 响应
public function abort(): never
{
abort(404, 'This resource does not exist either');
}
// 一个「意外的」错误:未处理的异常会产生 500 响应
public function unexpectedError(): never
{
throw new RuntimeException('An unexpected error');
}
}
|
我们来解读这段代码:
- 第 16–19 行:函数 [response] 构造一个完整的 HTTP 响应,它是一个 [Illuminate\Http\Response] 对象,其第一个参数是正文。[Laravel] 提供了许多这类随处可用的函数,称为 “辅助函数”:[response]、[redirect]、[abort]、[view]、[collect] 等。[header] 方法设置响应头——此处是它的类型:[text/plain] (纯文本)。浏览器不会解释其中的标签。[header] 返回响应本身:因此调用可以一个接一个地链式书写;
- 第 23–25 行:同样的字符串,单独作为响应返回:[Laravel] 以类型 [text/html] 发送它,浏览器会解释它;
- 第 29–31 行:[response()] 不带任何参数调用时,返回一个响应 工厂,其方法 [json] 把参数转换为 JSON,并生成类型为 [application/json] 的响应(一个 [JsonResponse] 对象)。转换由 [json_encode] 函数完成,该函数属于 [PHP]:对象会变成一个 JSON 对象,其字段就是该对象的 public 属性。[Person] 类将在下面介绍;
- 第 35–37 行:更简单的做法:返回 数组 的动作会产生 JSON 响应,而无需调用 [response()->json]。[PHP] 数组是一种通用结构:[['lastName' => 'Martin', ...]] 是一个 关联数组,其中每个元素都有一个键(此处是 ['lastName']);它会变成一个 JSON 对象。而普通对象则无法单独作为响应:[Laravel] 会尝试把它转换为字符串,操作会失败(“Object of class App\Models\Person could not be converted to string”);它必须通过 [response()->json] 处理;
- 第 41–43 行:带有隐式键(0、1、2)的数组是一个 列表;它会变成 JSON 数组;
- 第 47–49 行:函数 [collect] 创建一个 [Laravel] 集合——一个包装数组的对象,提供约一百个用于转换数组的方法——这些方法随后可以链式调用:[sort] 对元素排序,[values] 从 0 开始重新为键编号,而 [map] 对每个元素应用一个函数。[fn (int $n) => $n * 10] 是一个 箭头函数:精简为一个表达式的匿名函数,它返回该表达式的值。动作返回的集合同样会变成 JSON 数组。我们将在第 9 章结合数据库再来讨论集合;
- 第 53–55 行:[json] 的第二个参数是 状态码:201([Created])取代 200。可选的第三个参数用于提供头:[['X-Example' => '03']];
- 第 59–61 行:状态码 204([No Content])表示“没有可显示的内容”:响应没有正文;
- 第 65–67 行:一个“预期内”的错误:404 响应([Not Found]),其正文(JSON)由动作选择;
- 第 71–73 行:同样的错误,由函数 [abort] 生成。[abort] 不返回任何内容:它 抛出一个异常 ([NotFoundHttpException],对应状态码 404),从而终止动作;[Laravel] 把它转换为错误响应。类型 [never] 表示该方法永远不会正常结束。这是因错误而终止动作最常见的方式,即使是在被动作调用的函数深处;
- 第 77–79 行:一个“意外”的错误——没有人处理的异常——会产生 500 响应([Internal Server Error])。语句 [throw] 抛出一个异常;[RuntimeException] 是 [PHP] 标准库中的异常类,与其他任何类一样通过 [use](第 10 行)导入。这个动作没有像课程其他版本那样命名为 [exception]:因为对 [Laravel] 来说,名为 ['exception'] 的动作会指向 [Exception] 类,即 [PHP] 的类(类名不区分大小写),路由会被拒绝。
类 [Person]:
| <?php
// app/Models/Person.php:一个人
namespace App\Models;
// 属性在构造函数中声明的类(构造器属性提升);
// readonly:属性在构造之后不能再更改
readonly class Person
{
public function __construct(
public string $lastName,
public string $firstName,
public int $age,
) {
}
}
|
- 第 8 行:[readonly] 使类的所有属性在初始化之后都不可修改:[Person] 对象是 不可变的;
- 第 10–14 行:[__construct] 是类的 构造器,由 [new Person('Martin', 'Jean', 42)] 调用。它的参数前面带有 [public],是 提升的:每个参数都声明一个同名属性,并由该参数初始化。这种语法避免了先声明属性、再在构造器体内逐个赋值(此处构造器体为空)。这些属性是 public 的:[json_encode] 可以访问它们。
最后还剩下文件 [bootstrap/app.php]:
| <?php
// bootstrap/app.php:示例 03 的应用程序
use App\Http\Middleware\ReadableJson;
use Illuminate\Foundation\Application;
use Illuminate\Foundation\Configuration\Middleware;
(require __DIR__.'/../../vendor/autoload.php')->addPsr4('App\\', __DIR__.'/../app/');
return Application::configure(basePath: dirname(__DIR__))
->withRouting(web: __DIR__.'/../routes/web.php')
->withMiddleware(function (Middleware $middleware): void {
// 所有 JSON 响应都经过 ReadableJson 中间件:
// 保留重音字符,缩进排版
$middleware->append(ReadableJson::class);
})
->withExceptions()
->create();
|
- 第 15 行:向应用添加一个 中间件组件 :[ReadableJson] 类,如下所示。
| <?php
// app/Http/Middleware/ReadableJson.php:人类可读的 JSON
namespace App\Http\Middleware;
use Closure;
use Illuminate\Http\JsonResponse;
use Illuminate\Http\Request;
use Symfony\Component\HttpFoundation\Response;
class ReadableJson
{
// 一个中间件:其 handle 方法会在每个请求时被调用的类;
// $next($request) 让操作处理请求,并返回响应
public function handle(Request $request, Closure $next): Response
{
$response = $next($request);
if ($response instanceof JsonResponse) {
// 用 "é" 而不是 "é",用 "/" 而不是 "\/",
// 并且缩进排版,分多行显示
$response->setEncodingOptions(JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES
| JSON_PRETTY_PRINT);
}
return $response;
}
}
|
默认情况下,[Laravel] 生成紧凑的单行 JSON,其中非 ASCII 字符被写成转义序列:[créée] 变成 [cr\u00e9\u00e9e],这是有效的 JSON,但可读性不佳。在本课程的示例中,我们希望得到可读的 JSON。中间件是一个类,其方法 [handle]*** 会在每个请求时被调用,它 *包裹 在动作外层:[$next($request)] 把请求传给应用的其余部分(其他中间件,然后是动作),并返回响应(第 17 行)。随后中间件可以修改它:如果它是 JSON 响应([instanceof] 运算符检查对象的类),就更改其编码选项:非 ASCII 字符和斜杠按原样写出,并对输出进行缩进(第 21 行)。[|] 运算符把这三个选项组合起来,它们是 [PHP] 的常量。请求生命周期一章将详细考察中间件;示例 05 至 12 会复用这个中间件。
在浏览器中,可以看到 [text/plain] 与 [text/html] 的区别:


下面是其他动作的响应:
| curl -i http://localhost:8000/responses/json
|
| HTTP/1.1 200 OK
Content-Type: application/json
{
"lastName": "Martin",
"firstName": "Jean",
"age": 42
}
|
对象被转换为 JSON 对象,每个 public 属性对应一个字段。[/responses/array] 动作产生完全相同的响应。
| curl -i http://localhost:8000/responses/list
curl http://localhost:8000/responses/collection
|
| HTTP/1.1 200 OK
Content-Type: application/json
[
"Mme",
"Melle",
"Mr"
]
[
10,
20,
30
]
|
| curl -i http://localhost:8000/responses/created
|
| HTTP/1.1 201 Created
Content-Type: application/json
{
"message": "resource created"
}
|
| curl -i http://localhost:8000/responses/empty
|
| curl -i http://localhost:8000/responses/not-found
|
| HTTP/1.1 404 Not Found
Content-Type: application/json
{
"message": "This resource does not exist"
}
|
| curl -i http://localhost:8000/responses/abort
|
| HTTP/1.1 404 Not Found
Content-Type: text/html; charset=utf-8
<!DOCTYPE html>
<html lang="en">
...
<title>Not Found</title>
...
|
[abort] 的响应是 [Laravel] 标准的 404 错误页面,如示例 02 所示。我们的消息没有出现在其中:标准页面只显示状态码及其标签。不过,当客户端通过 [Accept: application/json] 头([curl] 的 [-H] 选项)请求 JSON 响应时,消息就会出现:[Laravel] 随后会调整其错误响应,使其变成 JSON 文档:
| curl -i -H "Accept: application/json" http://localhost:8000/responses/abort
|
| HTTP/1.1 404 Not Found
Content-Type: application/json
{
"message": "This resource does not exist either",
"exception": "Symfony\\Component\\HttpKernel\\Exception\\NotFoundHttpException",
"file": ".../vendor/laravel/framework/src/Illuminate/Foundation/Application.php",
"line": 1444,
"trace": [
...
]
}
|
在调试模式下,JSON 文档还包含异常的名称、抛出异常的文件和行,以及 调用栈 (出错时正在执行的函数列表)。在非调试模式下,它只包含消息。第 7 章将说明如何在自定义错误页面上显示消息。
最后是未处理的异常。在调试模式下,浏览器会显示 [Laravel] 的错误页面:异常的类型和消息、抛出异常的文件和行,然后是调用栈——从最近到最早——并为每一项显示相关的代码行:

栈中的第一项是我们的动作 [unexpectedError],位于文件 [ResponsesController.php] 的第 79 行。再往下,页面显示请求(其头和参数)以及应用(路由和设置):这就是为什么调试模式 绝不能 在他人可访问的服务器上启用。“Copy as Markdown”按钮会复制错误描述,可直接粘贴到向 AI 提的问题中。错误还会写入应用的 日志,即文件 [storage/logs/laravel.log] (这里只显示开头部分):
| [2026-09-26 15:51:36] local.ERROR: An unexpected error {"exception":"[object] (RuntimeException(code: 0): An unexpected error at .../examples/03-responses/app/Http/Controllers/ResponsesController.php:79)
[stacktrace]
#0 .../vendor/laravel/framework/src/Illuminate/Routing/ControllerDispatcher.php(46): App\\Http\\Controllers\\ResponsesController->unexpectedError()
...
|
在非调试模式下([.env] 中为 [APP_DEBUG=false] ),同样的请求会产生一个简短的错误页面“500 | Server Error”,它不会泄露任何有关代码的信息;错误只在日志中描述。第 7 章将说明如何显示应用专属的错误页面。
2.4. 示例 04:重定向
重定向 是一种响应,它指示浏览器去获取另一个 URL:一个 3xx 状态码以及包含新地址的 [Location] 头。浏览器会立即向该地址发送第二个请求。控制器 [RedirectsController]:
| <?php
// app/Http/Controllers/RedirectsController.php:重定向
namespace App\Http\Controllers;
use Illuminate\Http\RedirectResponse;
class RedirectsController
{
// 永久重定向(301):页面的地址已永久改变
public function oldPage(): RedirectResponse
{
return redirect('/new', 301);
}
public function newPage(): string
{
return 'You are on the [new] page';
}
// 临时重定向(302,默认状态码),目标地址通过
// 拼接文本片段计算得出
public function go(string $destination): RedirectResponse
{
return redirect('/page/'.$destination);
}
// route() 构建由名称指定的路由的地址:
// [name] 参数会针对 URL 被正确编码
public function toRoute(string $destination): RedirectResponse
{
return redirect()->route('page', ['name' => $destination]);
}
public function page(string $name): string
{
return "You are on the [$name] page";
}
// 重定向到另一个站点
public function documentation(): RedirectResponse
{
return redirect()->away('https://laravel.com/docs');
}
}
|
- 第 11–13 行:函数 [redirect] 生成一个指向指定地址的重定向响应(一个 [RedirectResponse] 对象)。状态码 301([Moved Permanently])表示页面的地址已 永久 更改:浏览器(和搜索引擎)可以记住新地址;
- 第 23–25 行:没有第二个参数时,[redirect] 生成状态码为 302 的 临时 重定向([Found])。URL 通过拼接文本片段([.] 运算符)构造,这会带来问题,我们稍后会看到;
- 第 30–32 行:不带参数调用时,[redirect()] 返回一个对象,其 [route] 方法创建指向某条 路由的重定向,该路由通过其 名称 (['page'])而不是路径来标识。关联数组提供路由参数(此处是 [name]),并针对 URL 正确地进行 编码。如果以后更改了路由 [page] 的路径,指向它的重定向会自动更新;
- 第 41–43 行:重定向到另一个站点。[away] 方法按原样使用该地址。
在路由表中为它指定了路由名称:
| <?php
// routes/web.php:示例 04 的路由
use App\Http\Controllers\RedirectsController;
use Illuminate\Support\Facades\Route;
Route::controller(RedirectsController::class)->group(function () {
Route::get('old', 'oldPage');
Route::get('new', 'newPage');
Route::get('go/{destination}', 'go');
Route::get('to-route/{destination}', 'toRoute');
// name:路由的名称,可用于构建其 URL(route 函数)
Route::get('page/{name}', 'page')->name('page');
Route::get('documentation', 'documentation');
});
|
- 第 7 行:一组没有前缀的路由,它们只共享控制器(示例 02);
- 第 13 行:[name] 方法为路由指定名称。随处可用的 [route] 函数为具名路由生成 URL:[route('page', ['name' => 'a?b'])] 得到 [http://localhost:8000/page/a%3Fb]。
使用 [curl] (不带选项时它不会跟随重定向)得到的结果:
| curl -i http://localhost:8000/old
|
| HTTP/1.1 301 Moved Permanently
Location: http://localhost:8000/new
Content-Type: text/html; charset=utf-8
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8" />
<meta http-equiv="refresh" content="0;url='http://localhost:8000/new'" />
<title>Redirecting to http://localhost:8000/new</title>
</head>
<body>
Redirecting to <a href="http://localhost:8000/new">http://localhost:8000/new</a>.
</body>
</html>
|
[Laravel] 把地址 [/new] 转换成了 绝对 地址(包含协议、主机和端口),它是根据收到的请求计算出来的。响应还包含一小段 HTML 正文,供不跟随重定向的客户端使用。[curl] 的选项 [-L] 会像浏览器那样跟随重定向:
| curl -L http://localhost:8000/old
|
| You are on the [new] page
|
现在来比较这两个计算得出的重定向,其目标包含一个问号,在 URL 中编码为 [%3F] (未编码的 [?] 会开始 URL 的参数):
| curl -i http://localhost:8000/go/a%3Fb
curl -i http://localhost:8000/to-route/a%3Fb
|
| HTTP/1.1 302 Found
Location: http://localhost:8000/page/a?b
...
HTTP/1.1 302 Found
Location: http://localhost:8000/page/a%3Fb
...
|
[Laravel] 在处理路由参数之前先对其解码:[$destination] 等于 [a?b]。第一个动作把它按原样重新插入地址:[/page/a?b],浏览器会把它解释为路径 [/page/a] 后面跟着参数 [b]。第二个动作使用具名路由,其参数会被重新编码:[/page/a%3Fb]。跟随重定向:
| curl -L http://localhost:8000/go/a%3Fb
curl -L http://localhost:8000/to-route/a%3Fb
|
| You are on the [a] page
You are on the [a?b] page
|
只有第二个会通向正确的页面。因此有这样的规则:包含变量值的地址要用 [route] 构造,绝不能通过拼接字符串来构造。在浏览器中只能看到最终的页面;地址栏显示新的 URL:

还有另外两个重定向状态码:303([See Other])和 307([Temporary Redirect]),可以通过 [redirect($url, 303)] 获得。在 POST 请求之后,状态码 302 和 303 会使浏览器向新地址发送 GET 请求,而 307(以及它的永久版本 308)会使浏览器重复 POST 请求。示例 20 将使用 POST 之后的重定向。
2.5. 示例 05:请求和响应对象
到目前为止,动作只接收路由参数,并返回一个由 [Laravel] 转换为响应的值。动作也可以访问当前的 请求 ,并自己构造 响应。控制器 [HttpController]:
| <?php
// app/Http/Controllers/HttpController.php:请求对象和响应对象
namespace App\Http\Controllers;
use Illuminate\Http\Request;
use Illuminate\Http\Response;
use RuntimeException;
use Symfony\Component\HttpFoundation\StreamedResponse;
class HttpController
{
// 请求:方法、路径、参数、头部……
// Laravel 将当前请求的 Request 对象注入到带类型的 $request 参数中
public function requestInfo(Request $request): array
{
return [
'method' => $request->method(),
'path' => $request->path(),
'url' => $request->fullUrl(),
'parameters' => $request->getQueryString(),
'browser' => $request->userAgent(),
'ip' => $request->ip(),
];
}
// 响应:response() 构建响应对象;我们为其添加一个头部
public function header(): Response
{
return response('Response with an added header')
->header('X-Example', '05-request-response');
}
// 「手工」构建的响应:正文、状态码、头部
public function response(): Response
{
return new Response('Response built by [new Response(...)]', 200,
['Content-Type' => 'text/plain; charset=utf-8']);
}
// 分块发送的响应:状态码和头部随
// 第一个数据块一起发出,之后不能再更改
public function stream(): StreamedResponse
{
return response()->stream(function () {
echo 'Start of the response... ';
// 该数据块立即发送给浏览器
flush();
sleep(1);
// 现在才宣告错误已经太晚:200 状态码已经发出
throw new RuntimeException('error in the middle of the response');
}, 200, ['Content-Type' => 'text/plain; charset=utf-8']);
}
}
|
- 第 15 行:动作有一个类型为 [Request] 的参数。这个参数并非来自 URL:[Laravel] 检测到它的 类型 ,并向它提供当前请求的 [Request] 对象。这就是 依赖注入,下一个示例将详细说明:动作通过参数的类型声明它所需要的对象,由 [Laravel] 提供这些对象。参数的顺序无关紧要:动作可以同时接收请求和路由参数;
- 第 17–24 行:请求的一些方法:它的 HTTP 方法、路径(不含开头的斜杠)、完整 URL、原始参数(URL 中跟在 [?] 之后的部分)、[User-Agent] 头(即浏览器;[$request->header('User-Agent')] 是更简短的写法),以及客户端的 IP 地址。类 [Illuminate\Http\Request] 继承自类 [Request],后者又继承自 [Symfony]——另一个 [PHP] 框架,[Laravel] 就是基于它的组件构建的。下一章将逐个讨论这些参数。返回的类型 [array] 会产生 JSON 响应(示例 03);
- 第 28–31 行:由 [response] 生成的响应带有一个头 [X-Example] (按惯例,应用专有的头通常以 [X-] 开头);
- 第 35–38 行:由运算符 [new] “手工”构建的响应:正文、状态码和头;
- 第 43–52 行:一个 分块 发送的响应(*streaming*)。[response()->stream] 接收一个函数,由该函数自己通过 [echo] ([PHP] 中写入响应的指令)写出响应正文;[flush()] 会立即把已写入的内容发送给浏览器。响应的长度事先未知:服务器先发送状态码和头,然后在每个块生成后立即发送它。这对逐步生成的超长响应很有用。但是第一个块一旦发出,状态码就不能再改变:这里,函数在第一个块之后抛出了异常。这是需要避免的错误:已经开始的响应无法再变成错误响应。
路由表和 [bootstrap/app.php] 中没有新内容([bootstrap/app.php] 添加了示例 03 中的 [ReadableJson] 中间件)。响应如下:
| curl -i "http://localhost:8000/http/request?name=martin&age=42"
|
| HTTP/1.1 200 OK
Content-Type: application/json
{
"method": "GET",
"path": "http/request",
"url": "http://localhost:8000/http/request?age=42&name=martin",
"parameters": "age=42&name=martin",
"browser": "curl/8.5.0",
"ip": "127.0.0.1"
}
|
"URL" 两侧的引号可以防止终端解释字符 "[&]"。请注意,参数已按字母顺序 排序 :[getQueryString] 和 [fullUrl] 会生成参数字符串的 规范化 形式,这使得可以比较两个 URL 的值(这在例如缓存中很有用)。在浏览器中,头 [User-Agent] 就是浏览器自己的头。
| curl -i http://localhost:8000/http/header
|
| HTTP/1.1 200 OK
X-Example: 05-request-response
Content-Type: text/html; charset=utf-8
Response with an added header
|
| curl -i http://localhost:8000/http/response
|
| HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
Response built by [new Response(...)]
|
| curl -i http://localhost:8000/http/stream
|
| HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
Start of the response...
|
一秒钟后,响应中断:[curl] 收到了状态码 200 和被截断的正文,无从得知发生了错误。只有应用日志通过两个错误指出了这一点:我们的异常,以及随后 [Laravel] 的失败——它试图在头已经发送之后再发送错误页面:
| [2026-09-26 15:52:11] local.ERROR: error in the middle of the response {"exception":"[object] (RuntimeException(code: 0): error in the middle of the response at .../HttpController.php:51)
...
[2026-09-26 15:52:11] local.ERROR: Uncaught ErrorException: Cannot modify header information - headers already sent in .../vendor/symfony/http-foundation/Response.php:328
|
2.6. 示例 06:共享服务与依赖注入
动作不应该包含应用逻辑本身;它把逻辑委托给 服务——知道如何完成某项特定任务的对象(读取商品、计算购物车等)。多个动作往往使用同一个服务。[Laravel] 与 [Spring] 或 [ASP.NET Core] 一样,有一个 服务容器:一个创建服务并 自动把它们提供给需要它们的对象的对象。这就是 依赖注入,我们在示例 05 中已经就 [Request] 对象遇到过它。示例 06 按领域(商品、客户)而不是按类型(控制器、模型)来组织代码:
| 06-services/
├── app/
│ ├── Clients/
│ │ └── ClientsController.php
│ ├── Http/
│ │ └── Middleware/
│ │ └── ReadableJson.php
│ └── Products/
│ ├── Product.php
│ ├── ProductsController.php
│ ├── ProductsService.php
│ └── InMemoryProductsService.php
├── bootstrap/
│ └── app.php
├── routes/
│ └── web.php
└── ...
|
并不要求把控制器放在 [app/Http/Controllers] 中:[Laravel] 使用 [PSR-4] 标准,根据完整名称定位类(类 [App\Products\ProductsController] 位于文件 [app/Products/ProductsController.php] 中)。
2.6.1. 商品
| <?php
// app/Products/Product.php:一个产品
namespace App\Products;
use Brick\Math\BigDecimal;
// readonly:对象是不可变的(其属性由构造函数设置)
readonly class Product
{
public function __construct(
public int $id,
public string $name,
// BigDecimal:精确的十进制数(没有二进制舍入)
public BigDecimal $price,
) {
}
}
|
- 第 9 行:一个不可变类(见示例 03)。不可变对象可以安全地在代码的多个部分之间共享;
- 第 12–15 行:由构造器提升的属性及其类型。价格是 [BigDecimal],一种 精确的 十进制数,由 [brick/math] 库提供(随 [Laravel] 一同安装,Laravel 自己也使用它)。[PHP] 没有十进制类型:类型为 [float] 的浮点数是以 二进制表示的,无法精确表示 0.1 或 3.2(在二进制中,这些数有无限多位):以 [float] 计算的价格总和可能得到 5.500000000000001。
2.6.2. 服务契约:ProductsService.php
| <?php
// app/Products/ProductsService.php:服务的契约,说明它能做什么,而不说明如何做
namespace App\Products;
interface ProductsService
{
/** @return list<Product> */
public function findAll(): array;
// ?Product:一个产品,如果不存在则为 null
public function findById(int $id): ?Product;
}
|
- 第 6 行:服务 契约:它能做什么,而不指定怎么做。在 [PHP] 中,与在 [Java] 或 [C#] 中一样,契约由 接口定义:一组没有方法体的方法列表,所有这些方法都必须由 实现 该接口的类来实现;
- 第 8 行:文档注释([/** ... */])。类型 [array] 并未说明数组中包含什么;注解 [@return list<Product>]——[PHP] 会忽略它——向代码编辑器说明了这一点:一个商品列表;
- 第 11 行:[?Product]:一个商品,或者在它不存在时为 [null] 。
2.6.3. 实现:InMemoryProductsService.php
| <?php
// app/Products/InMemoryProductsService.php:契约的一个实现,使用内存中的数据
namespace App\Products;
use Brick\Math\BigDecimal;
class InMemoryProductsService implements ProductsService
{
/** @var list<Product> */
private array $products;
public function __construct()
{
$this->products = [
new Product(1, 'pen', BigDecimal::of('1.5')),
new Product(2, 'notebook', BigDecimal::of('3.2')),
new Product(3, 'eraser', BigDecimal::of('0.8')),
];
}
public function findAll(): array
{
// PHP 数组在传递时会被复制:调用者收到的是一个副本
return $this->products;
}
public function findById(int $id): ?Product
{
// array_find:函数返回 true 的第一个元素,否则为 null
return array_find($this->products, fn (Product $p) => $p->id === $id);
}
}
|
- 第 8 行:该类实现契约并定义它的两个方法;
- 第 11 行:一个 private 属性:只有该类的代码可以使用它;
- 第 13–19 行:构造器把商品存储在由 [$this->products] ([$this] 是当前对象)指定的属性中。[BigDecimal::of('1.5')] 根据字符串构造十进制数:如果由 [float] 1.5 构造,就会继承它的不精确性;
- 第 22–25 行:该方法返回商品数组。在 [PHP] 中,数组是一种 值 ,传递时会被复制:调用者收到的是一个副本,可以随意修改而不影响服务的数据(而 [Product] 对象则不会被复制,但它们是不可变的);
- 第 28–30 行:函数 [array_find] ([PHP] 8.4)返回数组中第一个使给定函数返回 [true] 的元素,如果没有则返回 [null] 。[===] 表示 严格 相等:值相同且类型相同。
2.6.4. 商品控制器:ProductsController.php
| <?php
// app/Products/ProductsController.php:/products 的操作
namespace App\Products;
use Illuminate\Http\JsonResponse;
class ProductsController
{
// 服务由 Laravel 注入到构造函数中:控制器
// 只知道契约(接口),不知道其实现
public function __construct(private ProductsService $service)
{
}
public function listAll(): array
{
return $this->service->findAll();
}
public function oneProduct(int $id): JsonResponse
{
$product = $this->service->findById($id);
if ($product === null) {
return response()->json(['message' => "Product no. $id not found"], 404);
}
return response()->json($product);
}
}
|
- 第 12–14 行:控制器需要这个服务;它把服务声明为其 构造器的参数。当 [Laravel] 创建控制器(以处理请求)时,它会检查构造器各参数的类型,向容器请求每种类型的对象,并把它们传给 构造器:这就是 构造器注入。带有前缀 [private] 的参数会被提升为私有属性(见示例 03):动作通过 [$this->service] 使用它。控制器只知道服务的 契约 (接口),不知道它的实现:它并不知道商品存放在内存中;
- 第 16–18 行:动作把工作委托给服务。返回的商品数组会变成 JSON 数组(示例 03):每个 [Product] 都变成一个 JSON 对象(它的属性是 public 的);
- 第 21–27 行:未知的商品返回 404 响应,并带有 JSON 格式的消息。单独的 [Product] 对象必须经过 [response()->json] (示例 03)。
2.6.5. 客户控制器:ClientsController.php
| <?php
// app/Clients/ClientsController.php:第二个控制器,使用同一个服务
namespace App\Clients;
use App\Products\Product;
use App\Products\ProductsService;
use Brick\Math\BigDecimal;
class ClientsController
{
// 这次服务被注入到操作的参数中
public function cart(ProductsService $service): array
{
$products = $service->findAll();
// 价格之和:从零开始累加 BigDecimal 值
$total = array_reduce($products,
fn (BigDecimal $sum, Product $p) => $sum->plus($p->price), BigDecimal::zero());
return ['client' => 'Jean Martin', 'items' => count($products), 'total' => $total];
}
}
|
- 第 13 行:这个控制器使用与商品控制器 相同的 服务。这一次,它把服务作为 动作的参数来接收:[Laravel] 也会注入动作的参数,就像示例 05 中的请求那样。通过构造器注入适用于所有动作都需要的服务;通过动作注入适用于只有某个动作需要的服务;
- 第 17–18 行:[array_reduce] 把 数组归约为单个值:函数接收累加值([$sum])和当前元素,并返回新的累加值;第三个参数是起始值,即为零的 [BigDecimal]。[plus] 把两个十进制数相加并返回一个新的十进制数([BigDecimal] 是不可变的);
- 第 19 行:[count] 返回数组中元素的个数。
2.6.6. 服务声明:bootstrap/app.php
| <?php
// bootstrap/app.php:示例 06 的应用程序
use App\Http\Middleware\ReadableJson;
use App\Products\ProductsService;
use App\Products\InMemoryProductsService;
use Illuminate\Foundation\Application;
use Illuminate\Foundation\Configuration\Middleware;
(require __DIR__.'/../../vendor/autoload.php')->addPsr4('App\\', __DIR__.'/../app/');
return Application::configure(basePath: dirname(__DIR__))
->withRouting(web: __DIR__.'/../routes/web.php')
->withMiddleware(function (Middleware $middleware): void {
$middleware->append(ReadableJson::class);
})
->withExceptions()
// 服务:当某个类请求 ProductsService 时,Laravel 的
// 容器会给它一个 InMemoryProductsService,且只创建一次(单例)
->withSingletons([
ProductsService::class => InMemoryProductsService::class,
])
->create();
|
- 第 20–22 行:服务的 实现 正是在这里,也只在这里选定。数组把被请求的类型(接口)与提供它的类关联起来。当某个类请求 [ProductsService] 时,容器会创建一个 [InMemoryProductsService];[withSingletons] 表示它只创建 一次:之后任何请求 [ProductsService] 的对象都会得到同一个对象。这就是 单例。要切换到从数据库读取的实现,只需修改这一行:只了解契约的控制器将保持不变。这就是依赖注入的全部意义所在:应用的每个部分都依赖于契约,而由唯一的一处决定实现。
具体类(不是接口)甚至不需要声明:容器知道如何通过向构造器注入参数来自行创建它。它就是这样创建控制器的。而接口则必须与某个实现关联;否则容器会失败(“Target [App\Products\ProductsService] is not instantiable”)。这种关联也可以使用 属性 ([PHP] 中的一种注解)直接声明在接口上:[#[Bind(InMemoryProductsService::class)]] 位于 [interface ProductsService] 之上,而 [#[Singleton]] 位于实现类之上。我们仍将声明保留在 [bootstrap/app.php] 中,它把应用的所有选择集中在一处;案例研究会把它们归入一个 服务提供者,即 [Laravel] 为此提供的类。
最后谈谈这个单例的生命周期。正如示例 01 中所见:在 [PHP] 中,应用在每次请求时都会重新构建。因此,该单例只在 单次请求内唯一:在处理某个请求期间请求它的所有类都会收到同一个对象,但下一个请求会收到一个新的对象。对于只读取静态数据的服务(比如这个),这没有区别。对于数据会变化的服务(示例 20 中的任务列表),这些数据必须存放在对象之外的地方:文件、数据库或 [Laravel] 的缓存中。另一方面,[PHP] 服务不会被两个请求同时使用:每个请求都有自己的服务。在 [Java]、[C#] 或 [Python] 中,为被多个并发请求共享的服务所需采取的预防措施(尤其是锁)在这里是不必要的。
路由表:
| <?php
// routes/web.php:示例 06 的路由
use App\Clients\ClientsController;
use App\Products\ProductsController;
use Illuminate\Support\Facades\Route;
Route::get('products', [ProductsController::class, 'listAll']);
Route::get('products/{id}', [ProductsController::class, 'oneProduct'])->whereNumber('id');
Route::get('clients/cart', [ClientsController::class, 'cart']);
|
2.6.7. 执行
| curl -i http://localhost:8000/products
|
| HTTP/1.1 200 OK
Content-Type: application/json
[
{
"id": 1,
"name": "pen",
"price": "1.5"
},
{
"id": 2,
"name": "notebook",
"price": "3.2"
},
{
"id": 3,
"name": "eraser",
"price": "0.8"
}
]
|
价格变成了 字符串 (["1.5"]):JSON 只有一种数值类型,大多数程序把它读作浮点数;因此 [BigDecimal] 被转换为字符串,以免丢失任何精度([BigDecimal] 类实现了 [JsonSerializable] 接口,该接口来自 [PHP],这使它可以自行选择其 JSON 形式)。
| curl -i http://localhost:8000/products/9
|
| HTTP/1.1 404 Not Found
Content-Type: application/json
{
"message": "Product no. 9 not found"
}
|
| curl -i http://localhost:8000/clients/cart
|
| HTTP/1.1 200 OK
Content-Type: application/json
{
"client": "Jean Martin",
"items": 3,
"total": "5.5"
}
|