Middleware 是 PHP 微型框架中处理请求响应的函数式链，每个中间件接收 $request、$response 和 $next，可读取、修改或短路流程，必须显式返回 $response；它不是后台服务或 Laravel 式抽象层，而是闭包或可调用对象，注册顺序为栈式（后进先出），且不可在其中执行耗时操作。
Middleware 是什么，PHP 里它不等于“中间件”这个词的字面意思
在 PHP 微型框架（比如 Slim、Laminas-Expressive、或手写 Router）中，Middleware 是一种函数式处理链：每个 Middleware 接收 $request 和 $response，可读取、修改、短路，再交给下一个。它不是后台服务，也不是 Laravel 那种带容器绑定的抽象层——多数情况下就是个闭包或可调用数组。
容易踩的坑：
• 把 Middleware 当成“插件”直接 require 进来就用，结果没调用 $next($request, $response)，整个请求卡死
• 在 Middleware 里 echo 或 var_dump，破坏响应流，导致 Headers already sent
• 忘记返回 $response（PHP 7.4+ 可能静默失败，但响应体为空）
- 必须显式 return
$response，哪怕只是透传 - 短路时（如鉴权失败），直接 return 新的
$response->withStatus(401)，别调$next - 所有
Middleware必须是可调用的，支持[$obj, 'method']、function ($req, $res, $next)、new AuthMiddleware()（需实现__invoke）
怎么注册 Bullet Middleware 到 Slim v4
Bullet 是个老项目（2012 年左右），不兼容 PSR-15，也不适配现代 Slim。如果你看到文档里写 Bullet\Middleware，基本是混淆了名字——真正能用的是原生 PSR-15 兼容中间件，或自己封装一个轻量包装器。
正确做法是绕过 Bullet，用 Slim 原生方式：
立即学习“PHP免费学习笔记（深入）”；
- 定义中间件函数，参数顺序必须是
($request, $response, $next) - 注册到路由组或全局：用
$app->add(new MyAuthMiddleware())或$app->add(function ($req, $res, $next) { ... }) - 注意执行顺序：Slim 是栈式（后注册的先执行），
$app->add(A); $app->add(B);→ 实际执行是 B → A → route
示例（日志中间件）：
<pre class="brush:php;toolbar:false;">$app->add(function ($request, $response, $next) {
$start = microtime(true);
$response = $next($request, $response);
$duration = microtime(true) - $start;
error_log(sprintf('[%s] %s %.3fms', date('Y-m-d H:i:s'), $request->getUri(), $duration * 1000));
return $response;
});
为什么不要在 Middleware 里做数据库查询或文件读写
Middleware 是每个请求必经之路，性能敏感度极高。一次 file_get_contents('.env') 或 <code>new PDO(...) 放在里面，相当于每请求都重连、重解析。
常见错误现象：
• 接口平均耗时突然从 10ms 涨到 120ms
• Apache 错误日志里反复出现 PDOException: SQLSTATE[HY000] [1040] Too many connections
• $_ENV 为空，因为 .env 没被加载，但你又在 Middleware 里硬读
- 配置类、DB 连接池、缓存实例应提前初始化，注入到 Middleware 实例属性中（构造时传入）
- 需要动态查 DB 的逻辑（如权限校验），应只查必要字段，加缓存（APCu / Redis），并设好超时
- 如果必须读文件（如白名单 IP），用
file_get_contents+opcache_compile_file预热，或改用内存常量
如何调试 Middleware 不生效或顺序错乱
最常见原因是注册时机不对，或中间件本身没返回 $response。Slim 不报错，只是静默跳过后续中间件和路由。
排查步骤：
- 在第一个中间件开头加
error_log('M1 start');，结尾加error_log('M1 end');，看日志是否成对出现 - 检查是否漏写了
return $response;—— 没这句，$next根本不会被调用 - 确认注册位置：必须在
$app->run()之前，且不能放在路由定义之后（如$app->get(...)→add(...)是无效的） - 用
var_dump($app->getContainer()->get('foundHandler'))查容器状态（仅限 Slim v4 容器模式）
一个典型陷阱：$app->add($middleware)->add($another) 写成链式，实际 add() 返回的是 $app，不是中间件对象，所以第二句等价于 $app->add($another)，第一句白写了。
真正麻烦的从来不是写一个 Middleware，而是搞清它在哪一层被调用、谁持有它的生命周期、以及它和路由参数/依赖注入之间的隐式耦合。这些细节不打印日志、不翻框架源码，光看文档根本绕不出来。
