全局中间件（MiddlewareRegistry）

L4 链路扩展：把插件代码织入主请求链的入口/出口，做统一改写、埋点、灰度等。app\basic\MiddlewareRegistry 维护按优先级排序的 before/after 链，由 app\middleware\PluginMiddleware 在请求生命周期调度。

默认关闭

插件代码直接织入每一个请求，安全敏感。默认关闭，仅受信插件场景通过 config/plugin_extend.php 的 middleware_enabled=true 灰度开启。开关关闭时 all() 返回空链，注册无效。

注册

use app\basic\MiddlewareRegistry;
use support\Request;
use support\Response;

// 写在 boot()，owner=插件名
// ① 请求前置：可短路
MiddlewareRegistry::add(
    'before:request',
    function (Request $request): ?Response {
        // 返回 Response 则短路返回、不再进控制器；返回 null 继续链
        if ($request->header('x-block')) {
            return json(['code' => 403, 'msg' => 'forbidden'])->withStatus(403);
        }
        return null;
    },
    priority: 10,
    owner: 'am_demo'
);

// ② 响应后置：改写/追加响应
MiddlewareRegistry::add(
    'after:response',
    function (Request $request, Response $response): ?Response {
        // 返回 null 保持原响应；返回新 Response 则替换
        $response->header('x-am-demo', '1');
        return null;
    },
    priority: 10,
    owner: 'am_demo'
);

签名约定

时机	$when	签名	返回语义
入口前置	before:request	fn(Request): ?Response	返 Response 短路；返 null 继续
出口后置	after:response	fn(Request, Response): ?Response	返 null 保持原响应；返 Response 替换

• priority 越大越先执行；同优先级按注册先后。
• 未知 $when 静默忽略，不污染链。

判定与清理

方法	作用
all($type)	取某类中间件（按优先级降序），开关关时返回空
has($type)	是否有注册（诊断/冒烟用，不受开关影响）
enabled()	当前开关状态
forgetByOwner($owner)	禁用/卸载时清理（基座自动调用）

进程级

add() 一律写在 boot()，传 owner。详见生命周期。