ThinkPHP中间件存放目录规范_全局与路由中间件管理

ThinkPHP 6+ 的中间件默认放在 app/middleware/ 目录，这是框架约定好的位置，同时也要求文件命名遵循 PSR-4 规范。全局中间件的注册在 app/middleware.php 里定义，路由中间件则在路由绑定时按需绑定。执行顺序也相对固定：全局先跑，接着跑路由中间件，最后才到控制器方法。

ThinkPHP 中间件文件该放在哪个目录

默认情况下，ThinkPHP 6+ 的中间件类必须放在 app/middleware/ 目录下，并且类名与文件路径要严格一致——这就是 PSR-4 的要求。比如 app/middleware/CheckAuth.php 对应的命名空间是 app\middleware\CheckAuth。

当然，这个路径不是硬编码死的。如果你想挪动，必须同步修改 config/middleware.php 中的 middleware_namespace 配置，否则框架加载时会直接报 Class "xxx" not found。一般不建议这么做，尤其是团队协作的时候——路径不统一很容易出现本地能跑、线上报错，连 composer dump-autoload 都可能失效。

• 千万别把中间件塞进 app/common/ 或 app/beha vior/ ——后者是 TP5 时代的“行为”机制，TP6 已经废弃。
• 子目录是允许的，比如 app/middleware/auth/LogLogin.php，对应类名 app\middleware\auth\LogLogin。只要确保自动加载规则覆盖到子目录就行（默认 composer.json 已经配置好）。
• 如果用了 Swoole 或 RoadRunner 这样的长连接模式，中间件构造函数里尽量不要写阻塞操作（比如 file_get_contents、curl），否则会影响并发能力。

全局中间件和路由中间件怎么注册才不冲突

全局中间件在 app/middleware.php 中通过数组定义，顺序就是数组索引的顺序；路由中间件则在路由定义时显式绑定，优先级更高，而且只对匹配的路由生效。两者同时存在时，执行顺序是：全局 → 路由 → 控制器方法（包括注解中间件）。

一个常见的误解是“后注册的中间件一定后执行”——其实全局中间件的顺序由数组索引决定，而路由中间件就算写在后面，也会插在全局之后、控制器之前。举个例子：

// route/app.php
Route::get('user/info', 'User/info')->middleware(['CheckAuth', 'LogRequest']);

这里的 CheckAuth 和 LogRequest 会在所有全局中间件执行完后才运行。哪怕你在 middleware.php 末尾又加了一个 DebugTrace，它仍然会比路由中间件先执行。

• 全局中间件适合做请求入口的统一处理：比如跨域头、日志记录、多语言初始化。
• 路由中间件适合做业务隔离：后台路由加 AdminAuth，API 接口加 ApiRateLimit，避免全局加载拖慢 H5 页面。
• 同一个中间件类如果同时注册为全局和路由，会执行两次——除非你在中间件内部用静态变量或 Request 属性做幂等判断。

中间件参数传递和闭包写法为什么很少用

ThinkPHP 支持用闭包形式定义中间件（直接写在路由或 middleware.php 里），比如：

Route::get('test', function () { return 'ok'; })->middleware(function ($request, $next) {
    return $next($request);
});

但这种写法没法复用、不好调试、不能被容器管理（比如依赖注入失效），而且 IDE 无法跳转，PHPStan 静态分析直接报错。官方文档虽然没禁用，但实际项目中几乎没人这么干。

更常见的参数传递方式是“中间件类构造参数 + 路由绑定时传参”的组合：

• 构造参数走容器绑定，在 app/provider.php 里配置 app\middleware\RateLimit::class => [100, 60]，适用于固定阈值。
• 路由绑定时传参用字符串数组语法：->middleware(['throttle:10,1'])，框架会解析冒号后的值并传给中间件的 handle 方法的第二个参数（$params）。
• 需要提醒的是：throttle 这种带参数的写法，要求中间件类必须实现 think\contract\MiddlewareInterface，且 handle 方法签名要写成 public function handle($request, \Closure $next, ...$params)。

中间件执行中断后响应体为啥有时是空的

最常见的原因是中间件里用了 return 但没返回 Response 实例。比如写了 return json(['code'=>401])，这在 TP6+ 里只是 PHP 数组，框架不会自动封装成 Response，最终响应体为空，状态码还是 200。

正确的做法只有两种：

• 显式返回 Response 对象：return response()->json(['code'=>401]);
• 抛出异常并配好异常处理器（如 ValidateException 自动转 JSON），靠 think\ExceptionHandle 统一兜底。

另一个隐蔽的问题是中间件里调了 exit 或 die ——这会绕过框架的响应发送逻辑，导致 Swoole 下连接卡住、Nginx 出现 502，而且日志里完全没有痕迹。务必用 response() + return 来终止流程。

稍微复杂一点的情况是：有些中间件需要根据条件跳过后续流程但又不终止请求（比如灰度路由中间件）。这时候不能直接 return，而是应该用 $request->withAttribute('skip_auth', true) 传一个标记，让下游中间件自己判断是否跳过。这类控制流设计比单纯的“中断”更难测试，也更容易漏掉边界情况。