如何将 Slim 3 路由中间件无缝迁移至 Slim 4

如果您正在从 Slim 3 迁移到 Slim 4，中间件的改造是一个绕不过去的坎。不得不说，这次升级的核心变化在于：Slim 4 彻底拥抱了 PSR-15 标准，中间件的签名从传统的三参数模式，切换到了更严谨的 RequestHandler 风格。

简单来说，Slim 3 里中间件的写法是 function($request, $response, $next)，而 Slim 4 则要求接收 Request 和 RequestHandler，并且必须返回一个 ResponseInterface。原来通过 $next() 传递下去的模式，现在统一变成了 $handler->handle($request)。这个改动不仅规范了数据流，也让整个中间件栈的逻辑更清晰——每个中间件都是链条上独立的一环，只对输入和输出负责。

来看一个具体的例子。下面是一个 Slim 3 中常见的路由权限校验中间件，以及它在 Slim 4 中的等效实现：

use PsrHttpMessageServerRequestInterface as Request;use PsrHttpServerRequestHandlerInterface as RequestHandler;use PsrHttpMessageResponseInterface as Response;use SlimExceptionHttpNotFoundException;$app->add(function (Request $request, RequestHandler $handler): Response {    $publicRoutes = ['ping', 'guest', 'login', 'api-login', 'logout'];    // 确保路由解析中间件已注册，否则 route 属性可能为 null    $route = $request->getAttribute('route');    if (!$route) {        throw new HttpNotFoundException($request);    }    $routeName = $route->getName();    // 非公开路由需要校验 Token    if (!in_array($routeName, $publicRoutes, true)) {        $tokenStatus = checkTokenStatus(); // 建议后续将此逻辑提取为可注入的服务        if (!$tokenStatus) {            // 构造重定向响应：注意 $handler->handle() 返回的是 Response 对象            return $handler->handle($request)                ->withStatus(302)                ->withHeader('Location', '/login');            // 如果希望直接跳转，也可以显式构造一个全新的 Response 并返回            // return $response->withRedirect('/login'); // ❌ 错误：$response 未定义        }    }    // 放行，进入下一个中间件或路由处理器    return $handler->handle($request);});

这段代码的核心逻辑和 Slim 3 版本完全一致，但有三点需要特别留意。

首先，必须调用 $handler->handle($request)。这是整个中间件链路的“接力棒”，最终返回的 ResponseInterface 包含了下游所有中间件和路由处理器的处理结果。哪怕你想提前终止流程（比如重定向），也要确保返回值是一个 ResponseInterface 实例。

其次，重定向时不能再依赖原有的 $response 变量。Slim 4 中 Response 是不可变对象，而且中间件不再接收 $response 参数，所以需要从 $handler->handle() 的结果出发，或者直接构造一个新的 Response 来返回。经验表明，直接返回一个 withRedirect() 的结果是最简洁的方式。

再者，路由属性的可用性是有前提的。只有当 RoutingMiddleware 已经注册并执行后，$request->getAttribute('route') 才能正确取值。Slim 4 默认已启用该中间件，所以通常无需额外配置。

另外，异常处理方面也值得注意。推荐使用 Slim\Exception\HttpNotFoundException（继承自 PSR-7 兼容异常），框架会自动将其映射为 404 响应，比手动抛出响应更符合规范。

最后，关于代码结构。上面示例是函数式写法，简单直观。但在生产环境中，还是建议将逻辑封装成类，实现 MiddlewareInterface 接口。这样做的好处是便于单元测试和支持依赖注入。比如 checkTokenStatus() 这样的全局函数，如果能替换为一个注入的 Token 校验服务，代码的可维护性会高很多。

总结下来，Slim 4 的中间件迁移其实没有那么玄乎。核心就一句话：把中间件想象成一条流水线，每个节点只做一件事——接收 Request，处理它，返回 Response。理解了“请求处理器链”这个模型，再对照上面的代码示例，迁移工作就能顺利进行。这是不是比想象中要清晰多了？