前端同事报了一个问题:调用新建订单的接口,浏览器控制台一直是跨域错误,服务端日志里却一条请求都没有。抓包发现,浏览器先发了一个 OPTIONS 预检请求,这个请求返回 404,后面的 POST 根本没发出去。开发第一反应是「加一个 OPTIONS 路由」,结果越加越乱。
几乎同时,另一个接口偶发 500。排查下来是鉴权中间件被排在了请求体解析之前,它要从 JSON 里读 token,读到的却是一个空数组,后面按数组下标取值直接报错。两个问题看起来毫不相干,真正的位置都是同一个:请求进入框架之后、控制器执行之前的那段管线。
这篇把这段管线走一遍。先看一次请求从哪进、按什么顺序经过谁、最后怎么出去;再分别讲路由、路由模型绑定、中间件的注册和顺序、请求校验,以及 404、405、419 这几种状态码到底在说什么。看完之后,上面两个现象都能自己定位。
一次请求的完整路径
从浏览器按下回车,到 JSON 回到屏幕,中间大致经过八站。每一站都可能返回错误,而且错误的形态完全不同:
逐站说明。Nginx 决定请求是否交给 PHP-FPM,这一步出错通常是 404 或 502,应用日志为空。FPM 执行 public/index.php,它只做两件事:加载 Composer 的自动加载文件,取出 bootstrap/app.php 返回的应用实例。应用实例在启动阶段注册服务容器、配置、异常处理器和路由。
接着请求进入全局中间件栈。Laravel 12 默认的全局栈负责可信代理、CORS、维护模式拦截、请求体大小检查和字符串清理,最后是路由分发;Cookie 加密、会话启动、CSRF 校验属于 web 组,只有 Web 路由才会经过。注意「路由分发」本身就是一个中间件,它负责匹配路由并把请求交给后续的路由中间件和控制器。响应生成后,会沿着中间件栈反向返回,每一层都有机会改响应头或记录耗时。
路由匹配阶段读的是 routes/web.php、routes/api.php 这些文件里注册的路由表。匹配成功就进入该路由绑定的中间件,再进控制器;匹配失败抛 404;路径存在但方法不对抛 405。这个顺序很重要:中间件在路由之前、路由中间件在控制器之前。
路由文件、前缀与分组
路由(route)就是一张「URL 加 HTTP 方法对应哪段代码」的映射表。Laravel 把它按用途分成几个文件,注册时各自带不同的中间件组。web.php 里的路由自动套上 web 组,包含会话、CSRF、Cookie 加密,适合返回页面的场景;api.php 里的路由自动套上 api 组,默认无状态,并带一个限流中间件,适合纯 JSON 接口。这一节不需要额外依赖,路由组件随 laravel/framework 12 一起装好。
web 组
有会话、有 CSRF 校验、Cookie 自动加密。浏览器提交表单走这条。它的错误会渲染成 HTML 页面,登录过期返回 419。
api 组
无会话、无 CSRF,默认按 IP 限流,异常以 JSON 返回。移动端、前端 SPA、服务间调用走这条。
routes/api.php 里的路由会自动加上 /api 前缀,这个前缀由 bootstrap/app.php 的 withRouting(api: ...) 决定。所以文件里写 /orders,实际地址是 /api/orders。如果接口要版本化,不要改全局前缀,用分组加自己的前缀:
use App\Http\Controllers\OrderController;
Route::prefix('v1')->group(function () {
Route::get('/orders', [OrderController::class, 'index']);
Route::post('/orders', [OrderController::class, 'store']);
});
Route::apiResource('users', UserController::class);
这段注册了 /api/v1/orders 两个接口,以及 apiResource 生成的五个用户接口。apiResource 是「资源路由」的简写:它一次生成 index、store、show、update、destroy 五个动作,自动跳过 HTML 表单用的 create 和 edit。控制器方法名和 HTTP 方法的对应关系是固定的,写错方法名路由仍然注册成功,但访问时会报方法不存在。
分组还有两个常用能力。->name('api.v1.') 给路由起名前缀,代码里用 route('api.v1.orders.index') 生成地址,改 URL 时只改一处;->middleware('throttle:60,1') 给整组加限流。这两项都写在分组上,不要逐条重复。
路由写完后用 php artisan route:list 核对,加 -v 会把每条路由实际挂载的中间件列出来,这是排查「中间件到底有没有生效」最快的手段。确认无误后,用 curl 直接打:
php -S 127.0.0.1:8030 -t public
curl -i http://127.0.0.1:8030/api/v1/orders
本机实测返回 200,data 里 20 条订单,meta.total 为 137;如果返回 404,先看 route:list 里有没有这条,再看 URL 是否多了或少了 /api。
php artisan serve 报 Failed to listen,HTTP 部分改用等价的 php -S 127.0.0.1:8030 -t public 验证,路由与响应结果一致。路由模型绑定:把 ID 换成对象
路由模型绑定(route model binding)是 Laravel 的一个便利机制:路由参数名如果和控制器参数的类型提示同名,框架会自动按主键查一条记录,查不到就抛 404,不用在控制器里手写查询和判空。
Route::get('/users/{user}', [UserController::class, 'show']);
// 控制器
public function show(User $user)
{
return response()->json($user);
}
这里 {user} 和 User $user 的名字必须一致。users/12 会自动查主键为 12 的用户,找不到返回 404,而不是 500。默认按主键查,也可以显式指定别的字段:{user:slug} 表示按 slug 查;或者在模型里重写 getRouteKeyName() 返回字段名,让所有绑定都按这个字段查。
有两个细节容易踩。第一,软删除的模型默认查不到,绑定会返回 404,如果业务需要查到已删除记录,要在路由上显式允许。第二,嵌套资源要做「作用域绑定」,比如 /users/{user}/orders/{order},默认只按 order 自己的主键查,可能查到别人的订单;加上 ->scopeBindings() 之后,框架会用父级 user 约束子级查询,这是防越权的一道硬边界。
如果参数不是主键、也不是常规字段,可以在 Route::bind 里写一段解析逻辑,或者给模型实现 resolveRouteBinding。前者适合一次性规则,后者适合这个模型在所有路由上的统一规则。两种方式都要保证「查不到就返回 null」,框架会据此转成 404,而不是让异常一路冒到 500。
findOrFail 查一遍。绑定已经查过一次,再查一次等于一个请求两条同样的 SQL;更重要的是,两次查询之间记录可能被删除,第二次抛出的异常不会被当成 404,而是变成 500。中间件:注册、别名与分组
中间件(middleware)是套在请求外面的处理层,可以在控制器之前拦截、修改请求,也可以在响应返回时补充头部或记录日志。Laravel 12 里它不在 Kernel 文件里注册,而在 bootstrap/app.php 的 withMiddleware 回调中:
->withMiddleware(function (Middleware $middleware) {
$middleware->appendToGroup('api', [
\App\Http\Middleware\ForceJsonResponse::class,
\App\Http\Middleware\LogRequestId::class,
]);
$middleware->alias([
'auth.token' => \App\Http\Middleware\AuthenticateToken::class,
]);
})
三种注册方式对应三种用途。appendToGroup 和 prependToGroup 把中间件挂到 web、api 这样的组上,组内所有路由自动生效;alias 起一个短名字,路由里写 ->middleware('auth.token') 就能用;append 和 prepend 则挂到全局栈,所有请求都经过,包括没有匹配到路由的请求。
写一个最小中间件只需要实现 handle 方法,接收请求、闭包和下一个处理者。下面的例子给每个请求加一个请求 ID,方便把 Nginx 日志、应用日志和前端上报串起来:
<?php
namespace App\Http\Middleware;
use Closure;
use Illuminate\Http\Request;
use Illuminate\Support\Str;
use Symfony\Component\HttpFoundation\Response;
class LogRequestId
{
public function handle(Request $request, Closure $next): Response
{
$requestId = $request->header('X-Request-Id') ?: (string) Str::uuid();
$response = $next($request);
return $response->header('X-Request-Id', $requestId);
}
}
创建命令是 php artisan make:middleware LogRequestId,它会生成到 app/Http/Middleware/。挂到 api 组之后,任意接口的响应头里都会出现这个 ID,前端报错时把它带上,后端就能直接定位那一条日志。
顺序错了会出现什么
中间件是按注册顺序执行的,先注册的先进入请求、后处理响应,像洋葱一样一层套一层。顺序错了,现象往往不是报错,而是「逻辑偶尔不对」。
最常见的错误是把「解析 JSON 并强制返回 JSON」的中间件排在鉴权之后。鉴权要从请求体里读 token,可请求体还没被解析成数组,读到的是空值;代码如果直接取下标,就变成 500 而不是 401。正确顺序是先做请求规范化(接受头、JSON 解析、请求 ID),再做身份认证,最后做权限判断。
Laravel 允许在 withMiddleware 里调整优先级:$middleware->priority([...]) 传一个类名数组,框架会按这个顺序重排。数组里只需要列出关心的几个,其余的仍按默认顺序。改动之前先用 route:list -v 和框架默认顺序对照,不要凭感觉重排整条栈。
再回到开头的 CORS 问题。跨域预检不是给业务路由处理的,它由全局栈里的 HandleCors 中间件在路由匹配之前直接回一个 204 空响应。OPTIONS 返回 404,通常只有三种原因:这个中间件被从全局栈里移除;config/cors.php 里的 paths 没覆盖 api/*;或者请求根本没到 PHP,被 Nginx 或前面的网关拦掉了。
验证方法很直接,用 curl 模拟浏览器的预检:
curl -i -X OPTIONS http://127.0.0.1:8030/api/v1/orders \
-H "Origin: http://localhost:5173" \
-H "Access-Control-Request-Method: POST" \
-H "Access-Control-Request-Headers: content-type,authorization"
本机实测返回 204,并带上 Access-Control-Allow-Origin: *、Access-Control-Allow-Methods、Access-Control-Allow-Headers 三个头。默认配置把来源回成 *,不是请求里的 http://localhost:5173;要精确限制就改 allowed_origins。如果返回 404,先确认请求有没有进 PHP;如果返回 204 但缺头,改 config/cors.php 里的 allowed_origins 和 allowed_headers,改完记得清配置缓存。
Content-Type: application/json 的请求会触发预检,普通的表单提交不会。这就是为什么「用 Postman 能通、浏览器不通」:Postman 不发预检,浏览器发。排查跨域问题时不要用 Postman 的结论代替浏览器。FormRequest:把校验从控制器里拿出来
请求校验如果写在控制器开头,很快会变成一个几十行的 if 堆。Laravel 的做法是表单请求(FormRequest),一个类承载一个场景的规则和授权判断,控制器只负责业务。
生成命令是 php artisan make:request StoreOrderRequest,生成的文件在 app/Http/Requests/。核心是两个方法:
public function authorize(): bool
{
return true;
}
public function rules(): array
{
return [
'customer_id' => ['required', 'integer', 'exists:customers,id'],
'items' => ['required', 'array', 'min:1', 'max:50'],
'items.*.sku' => ['required', 'string', 'max:64'],
'items.*.qty' => ['required', 'integer', 'min:1', 'max:99'],
'remark' => ['nullable', 'string', 'max:200'],
];
}
控制器里把参数类型换成这个类,框架会在进入方法之前自动校验,失败直接返回错误响应,方法体一行都不会执行:
public function store(StoreOrderRequest $request)
{
$data = $request->validated();
// 只包含通过校验的字段
}
validated() 只返回规则里声明过的字段,这一点很重要:直接把 $request->all() 传给模型,用户就能顺手改掉 status、user_id 这类不该由前端决定的字段,这是批量赋值漏洞的常见来源。
authorize() 决定「这个人能不能发起这个请求」,返回 false 时框架抛 403,方法体同样不会执行。它和鉴权中间件的分工是:中间件回答「有没有登录」,authorize 回答「这个已登录的人能不能做这件事」。两者都缺,就会出现「登录了就能删任何人的订单」这种越权。
校验失败返回什么,取决于请求是否「期望 JSON」。带 Accept: application/json 的请求会得到 422 和 errors 结构;不带这个头的请求会被重定向回上一页,并把错误放进 session,这是给 HTML 表单用的。API 项目里经常出现「前端收到 302 而不是 422」,原因就是少带了 Accept 头。
要统一错误结构,可以重写 failedValidation,把响应包成项目约定的格式:
protected function failedValidation(Validator $validator)
{
throw new HttpResponseException(response()->json([
'code' => 'VALIDATION_FAILED',
'message' => '参数校验失败',
'errors' => $validator->errors(),
], 422));
}
调用示例与实测返回:
curl -i -X POST http://127.0.0.1:8030/api/v1/orders \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"customer_id":1,"items":[]}'
本机实测返回 422,状态行是 HTTP/1.1 422 Unprocessable Content,响应体为 {"message":"The items field is required.","errors":{"items":["The items field is required."]}},errors.items 说明数组至少一个元素。这里用的是 FormRequest 默认响应,没有额外包一层 code;上文自定义 Validator 的版本会多出 code 和 message 字段。
404、405、419 到底在说什么
这几种状态码经常被混着看,其实对应完全不同的层,看一眼就能缩小范围:
| 状态码 | 含义 | 典型原因 |
|---|---|---|
| 404 | 路径没有匹配到任何路由,或绑定记录不存在 | URL 拼错、前缀不对、路由文件没注册、记录被删除 |
| 405 | 路径存在,但 HTTP 方法不允许 | 用 GET 调了只注册 POST 的路由;方法写错 |
| 419 | CSRF 令牌失效或缺失 | 在 web 组里调 API;页面放置太久,会话过期 |
| 422 | 参数校验失败 | 规则不通过,响应体里有 errors |
| 429 | 触发限流 | 同一 IP 或同一用户短时间请求过多 |
405 值得单独说:它证明请求已经进到路由表,只是方法对不上。如果某个接口用 GET 能通、POST 报 405,去看路由注册的方法是不是写成了 Route::get,或者 apiResource 里是不是漏了 store。另一种情况是网关把方法改写了,这时候应用日志里根本没有这条请求。
419 几乎只出现在 web 组。API 路由没有会话也没有 CSRF,所以不会出现 419。反过来说,如果 API 报 419,先检查它是不是被误注册到了 web.php,或者前端带着 Cookie 调用了需要 CSRF 的地址。
统一异常输出可以在 bootstrap/app.php 的 withExceptions 里做:对 API 请求统一返回 code、message、trace_id 三个字段,HTTP 状态码保持原样。不要把 404 包装成 200,那会让前端和监控都失去判断依据。
现象、原因与第一步
| 现象 | 真实原因 | 第一步查什么 |
|---|---|---|
OPTIONS 预检 404 | CORS 中间件未生效,或 config/cors.php 未覆盖该路径 | 用 curl 直接发 OPTIONS,看请求是否进 PHP;查 paths |
| 接口 405 | 路由注册的方法与调用不一致 | php artisan route:list --path=orders 看方法列 |
| API 返回 419 | 路由落在了 web.php,被套上 CSRF | route:list -v 看中间件组 |
| 校验失败返回 302 | 请求没带 Accept: application/json | 看请求头;或强制 API 组返回 JSON |
| 自定义中间件不执行 | 别名拼错、组挂错,或路由没走该组 | route:list -v;在 handle 里打日志 |
| 绑定返回 404 但记录存在 | 按 slug 查但值不匹配;软删除;作用域绑定限制 | 看路由参数写法与模型查询条件 |
| 本地路由正常、线上 404 | 线上有路由缓存,新路由没进缓存 | php artisan route:clear 后重试 |
| 中间件偶发 500 | 它读了尚未解析的请求体,或依赖了请求级状态 | 调整顺序;检查是否把数据存进了单例 |
边界与代价
中间件很灵活,代价是每加一层就多一次请求和响应上的穿行。十几个中间件叠起来,单看每个都只做一点事,合起来是一次请求里可观的开销;更麻烦的是顺序耦合——两个中间件单独测试都对,组合起来就出错,而这种问题只能靠集成测试覆盖。
另一个边界是路由缓存。路由多到几百条时,route:cache 能把匹配从「遍历注册表」变成「查一张编译后的表」,启动更快;但闭包路由无法被序列化,缓存命令会直接失败。所以正式项目里的路由应该指向控制器,健康检查这类闭包路由要么改成控制器,要么在缓存前处理掉。这个细节在第 6 篇的发布流程里会再出现一次。
如果上了 Octane(用常驻进程复用框架),中间件的生命周期假设会变。请求对象和响应对象仍然每请求新建,但容器里的单例、静态属性、全局变量会跨请求存活。任何在中间件里把当前用户、当前请求 ID 存到静态属性的写法,在 FPM 下没事,在 Octane 下就会串到下一个请求。这不是配置问题,是代码假设变了。
路由分组本身也有代价。为了「整齐」把接口拆成十几个前缀分组,路由文件会变得难找;分组中间件一旦挂错,影响的是整组接口而不是一个。实际项目里比较好的平衡是:按业务模块分文件、按版本分组、公共中间件只挂在最外层,别在每一层都挂一遍。
当天能自己验证的练习
- 执行
php artisan route:list -v,对比web.php与api.php里同名路径的中间件差异,把差异项写下来。 - 用 curl 发一个带
Origin和Access-Control-Request-Method的 OPTIONS 请求,确认返回 204 和三个 CORS 头;再把config/cors.php的paths改错,观察变成 404。 - 执行
php artisan make:middleware LogRequestId,挂到 api 组,请求任意接口,确认响应头里出现X-Request-Id。 - 写一个只注册 POST 的接口,分别用 GET 和 POST 调,记录 405 与正常返回的差别,再用
route:list找到方法列。 - 用
make:request建一个校验类,故意传空数组,分别在带与不带Accept: application/json时调用,对比 422 和 302。
小结
三句话:请求的顺序是全局中间件、路由匹配、路由中间件、控制器,出错时先判断停在哪一站;API 路由靠 /api 前缀和独立的中间件组与 Web 隔离,跨域预检由全局 CORS 中间件处理,不需要自己写 OPTIONS 路由;校验放进 FormRequest,validated() 拿到的才是允许写入的字段。
下一篇讲数据访问。路由和校验解决的是「请求怎么进来、参数对不对」,请求进来之后真正花时间的地方在数据库:连接怎么复用、一次列表查询为什么变成几百条 SQL、迁移怎么做才不锁表、事务边界该划在哪里。下一篇从一个连接数被打满的故障开始。