PHP构建PSR-15中间件管道详解

本文深入解析了在Slim 4框架中正确构建和使用PSR-15标准中间件的关键要点：强调中间件必须是实现MiddlewareInterface的类而非闭包，process()方法需严格遵循类型约束（接收ServerRequestInterface和RequestHandlerInterface、返回ResponseInterface），并务必调用$handler->handle($request)以维持洋葱式执行管道；同时厘清了全局、路由组与单个路由三级注册方式对作用域和执行顺序的实质影响，警示常见陷阱如误将数组/字符串当响应返回、错误复用请求参数、忽视依赖注入导致的可测试性与性能问题，并给出容器服务安全获取、响应对象规范构造等实战建议——帮你避开静默失败雷区，写出健壮、标准、可维护的中间件代码。

Slim 4 的中间件必须实现 MiddlewareInterface

PSR-15 要求中间件是一个类，且必须实现 MiddlewareInterface，不能是闭包或函数。Slim 4 不再接受 function ($req, $res, $next) 这种老式写法——直接报错：TypeError: Argument 1 passed to Slim\App::add() must be an instance of Psr\Http\Server\MiddlewareInterface。

实操建议：

• 用 class MyAuthMiddleware implements MiddlewareInterface 定义中间件
• process() 方法必须接收 ServerRequestInterface 和 RequestHandlerInterface，返回 ResponseInterface
• 别忘了在 process() 中调用 $handler->handle($request) 向下传递请求，否则管道中断

如何正确注册中间件：全局、路由组、单个路由三者区别

注册位置决定作用域，也影响执行顺序。Slim 4 的中间件执行是“外层先入、内层后出”的洋葱模型，但注册点不同，包裹关系不同。

实操建议：

• 全局中间件（$app->add(new MyLoggerMiddleware())）会包裹所有路由，包括 404
• 路由组中间件（$app->group('/api', function () { ... })->add(new JwtMiddleware())）只对组内路由生效
• 单个路由中间件（$app->get('/admin', ...)->add(new AdminOnlyMiddleware())）最内层，最后执行、最先响应
• 注意：多个 add() 调用顺序就是执行顺序（从上到下），不是从下到上

RequestHandlerInterface 不是 Response，别试图直接返回数组或字符串

常见错误是把 process() 当成控制器，直接 return ['error' => 'unauthorized'] 或 echo 'forbidden'，结果抛出 TypeError: Return value of MyMiddleware::process() must be an instance of Psr\Http\Message\ResponseInterface。

实操建议：

• 必须用 $response = $responseFactory->createResponse(401) 创建响应对象（可通过依赖注入获取 ResponseFactoryInterface）
• 写 JSON 响应时，记得设置头：$response->withHeader('Content-Type', 'application/json')->getBody()->write(json_encode([...]))
• 不要复用传入的 $response 参数——它只是占位符，实际应由工厂创建新实例

中间件里拿不到 $app 或容器？用 ContainerInterface 注入

Slim 4 默认不把 $app 实例传进中间件，想访问数据库、配置或服务，不能靠全局变量或静态调用——那会破坏可测试性，也容易引发循环依赖。

实操建议：

• 在中间件构造函数中声明 public function __construct(ContainerInterface $container)
• 通过 $this->container->get('db') 或 $this->container->get(PDO::class) 获取服务
• 避免在 process() 里做容器查找，构造时查好并缓存为属性，提升性能
• 如果容器未注入成功，检查 dependencies.php 是否正确定义了该中间件的工厂或实例

以上就是《PHP构建PSR-15中间件管道详解》的详细内容，更多关于的资料请关注golang学习网公众号！