Slim全局中间件过滤请求教程

本文深入解析了 Slim 4 中全局中间件的正确注册方式与核心实践要点，强调必须在 App 实例创建后、run() 调用前通过 $app->add() 显式挂载，严格遵循 __invoke 方法的类型提示签名，并借助容器工厂模式安全注入依赖；同时澄清常见误区——如误将中间件写在顶层、沿用 Slim 3 的 $next 调用方式、或试图在中间件内手动路径过滤导致请求链断裂，并指出路由组（group）才是实现路径级作用域的官方推荐方案；对于从 Slim 3 迁移或初次上手的开发者，这是一份直击执行静默失败、类型错误和依赖混乱等高频痛点的实战避坑指南。

怎么在 Slim 4 中注册全局中间件

Slim 4 的中间件必须通过 add() 方法显式添加到应用实例或路由组，没有“自动扫描”或“全局配置文件”机制。漏掉这一步，中间件根本不会执行。

常见错误是把中间件函数直接传给 run() 或写在 index.php 顶层——这些位置不构成中间件链，只是普通 PHP 代码。

• 正确做法：在创建 App 实例后、调用 run() 前，用 $app->add(...) 注册
• 全局中间件对所有 HTTP 请求生效（包括 404），但不作用于 CLI 调用
• 顺序很重要：add() 越早调用，越靠近请求入口；比如身份验证中间件应放在日志中间件之前

$app = new \Slim\App();
$app->add(MyAuthMiddleware::class); // ← 这里才真正挂载
$app->add(MyLoggingMiddleware::class);
$app->run();

中间件类必须实现 __invoke 方法

Slim 4 只接受可调用对象（callable），且要求参数签名严格匹配 __invoke(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface。少一个类型提示、多一个参数，都会触发 TypeError。

容易踩的坑是沿用 Slim 3 的写法，比如用 function ($request, $response, $next)，或者忘记返回 ResponseInterface 实例。

• 不能用闭包直接写逻辑（除非完整满足签名并返回 Response）
• 不要在 __invoke 里调用 $next($request) —— Slim 4 用的是 $handler->handle($request)
• 如果中间件要终止请求（如鉴权失败），必须手动构造并返回 Response，不能只 return 或 exit

class MyAuthMiddleware
{
    public function __invoke(
        ServerRequestInterface $request,
        RequestHandlerInterface $handler
    ): ResponseInterface {
        if (! $this->isValidToken($request)) {
            return new JsonResponse(['error' => 'Unauthorized'], 401);
        }
        return $handler->handle($request); // ← 必须返回
    }
}

如何让中间件只对特定路由生效

全局中间件无法按路径条件跳过，想实现“仅 /api/* 生效”，就得用路由组（RouteGroup）配合 add()，而不是往 $app 上挂。

有人试图在中间件内部用 $request->getUri()->getPath() 做判断再跳过 $handler->handle()，这会导致后续中间件和路由处理被跳过——但响应体可能为空，且状态码易出错。

• 推荐方案：用 $app->group('/api', ...)->add(...) 明确限定作用域
• 多个前缀需重复定义 group，不能用正则路径匹配 group 前缀
• group 内注册的中间件优先级高于全局中间件（更靠近路由）

$app->group('/api', function (RouteCollectorProxy $group) {
    $group->get('/users', 'UserController:list');
})->add(ApiAuthMiddleware::class);

中间件中访问容器服务（如 PDO、Logger）

Slim 4 默认使用 ContainerInterface 管理依赖，但中间件类本身不自动注入容器。直接在 __invoke 里用 $this->get(...) 会报错——因为中间件不是从容器解析出来的，而是由 Slim 直接 new 出来的。

解决方案只有两个：要么把容器传进构造函数，要么改用容器工厂方式注册中间件。

• 构造函数注入：在 add() 前先从容器取服务，再 new 中间件实例
• 工厂方式（更推荐）：在容器中定义中间件为工厂，Slim 会自动调用它获取实例
• 避免在中间件里硬编码 new PDO(...)，破坏可测试性

// 容器定义示例（通常在 dependencies.php）
$container->set(MyAuthMiddleware::class, function (ContainerInterface $c) {
    return new MyAuthMiddleware($c->get(PDO::class));
});
<p>// 注册时用字符串名，Slim 自动从容器取实例
$app->add(MyAuthMiddleware::class);</p>

中间件的执行时机、参数签名、容器绑定这三个点，是 Slim 4 里最常卡住人的地方。特别是从 Slim 3 升上来的人，很容易下意识复用旧模式，结果中间件静默失效，连 debug 日志都看不到。

理论要掌握，实操不能落！以上关于《Slim全局中间件过滤请求教程》的详细介绍，大家都掌握了吧！如果想要继续提升自己的能力，那么就来关注golang学习网公众号吧！