Download the PHP package kode/middleware without Composer

Kode\Middleware

轻量、可重入、协程安全的 PSR-15 中间件管道，显式串联「路由前 / 路由后 / 调度」三段式生命周期，原生融合 多进程 / 多线程 / Fiber 协程 与 分布式链路透传。

Kode\Middleware 是 kode 生态的「管道底座」：它只负责中间件如何被组织与执行，不实现具体的 CORS / 限流 / 鉴权等业务中间件（这些留给 kode/http 与你的业务层）。它的核心改进点，是针对 kode/http 已有 MiddlewarePipeline 的可变 $index 竞态缺陷，用 不可变管道 + 可重入游标 重构，使管道可以在多进程、多线程、Fiber 协程之间安全共享、可重试、可重入。

核心特性

• 🧷 不可变（Immutable）：add() / withXxx() 一律返回新实例。构建完成的管道作为只读对象，可在 Worker、线程、协程之间共享，无需加锁、无需每请求重建。
• 🔁 可重入（Reentrant）：执行状态全部下沉到不可变 Cursor，管道对象在处理期间零写入。同一实例可同时服务任意多个并发请求，中间件可安全地多次调用 $handler->handle() 实现重试 / 分支。
• 🧩 可嵌套（Composable）：Pipeline 自身实现 MiddlewareInterface，可直接作为另一条管道里的一个中间件——路由分组、模块级中间件由此自然导出。
• 🧭 三段式生命周期：beforeRoute（路由前全局）→ RouteMiddleware（路由匹配）→ afterRoute（路由后，可读路由元数据）→ DispatchMiddleware（路由级中间件 + 控制器）。
• ⚡ 四级并发运行器：Sync → Fiber → Thread → Process 自动探测与降级，业务代码零分支。
• 🌐 分布式链路透传：W3C traceparent 标准 + kode/context 上下文隔离，跨进程 / 跨节点不串号。
• 📦 蓝图下发：Blueprint 把中间件编排序列化为 JSON，一份配置全集群 Worker 一致。
• 🔌 软依赖优雅降级：kode/context、kode/di、kode/fibers、kode/parallel、kode/process 均为 suggest，未安装时静默降级。
• 🧅 框架集成洋葱模式：Kernel 在洋葱之外再包一层「启动 / 请求钩子 / 响应钩子 / 兜底 / 收尾」生命周期；ErrorBoundaryMiddleware（最外层异常边界）与 ProfilerMiddleware（分层耗时剖析）让洋葱真正「可兜底、可观测」。

环境要求

可选扩展（启用对应能力时）

注意：本包不内置 PSR-7 消息实现，运行测试与示例时需引入 nyholm/psr7 或其它实现。

安装

快速开始

三段式管道（推荐用 Pipe 门面）

Pipe 把一次请求的生命周期显式拆成三段，让中间件的位置一目了然：

更底层的 Pipeline

当你不需要「路由前后」分段语义时，直接用 Pipeline：

命名空间快捷函数

composer.json 已通过 files 自动加载 src/functions.php：

API 参考

Pipe（管道构建器 / 门面）

Pipe 自身可变（链式书写顺手），但 build() 产出的 Pipeline 不可变。

Pipeline（不可变管道内核）

中间件适配器（src/Adapter）

处理器（src/Handler）

路由三段式（src/Routing）

优先级约定

数字越大越靠外层（更早进入、更晚退出）。内置中间件默认优先级：

异常边界与可观测性

应用内核（src/Kernel.php）

Kernel 是框架集成的总入口：洋葱本身只负责「请求进、响应出」，而 Kernel 负责洋葱之外的生命周期——启动、请求 / 响应钩子、最终兜底、收尾。

所有 withXxx() 配置方法返回新实例，运行期配置不会被意外改写；handle() / terminate() 完全无写入，同一个 Kernel 实例可被 Swoole / Workerman / RoadRunner 的全部 Worker 与协程共享。

框架集成：洋葱模式（Onion after Framework）

Pipeline 负责「洋葱本体」，Kernel 负责「洋葱之外」。二者职责分离，互不替代：

为什么洋葱之外还需要一层？PSR-15 只定义了「请求进、响应出」，但一个真实框架的请求生命周期更长。中间件无法兜住「洋葱最外层中间件自己抛异常」的情况，而内核可以——这是 ErrorBoundaryMiddleware 与 Kernel::withExceptionHandler 构成的双层防线：

完整链路（含「框架洋葱」三段式顺序、控制器异常被边界兜住）由 tests/Unit/OnionTest.php 覆盖。

分组 · 嵌套 · 路由集成（Group · Nest · Router）

「可分组、结合 router、可嵌套」三者其实是同一件事的不同切面：本包用一个机制把它们统一起来——分组名在运行期被解析器展开成一条嵌套子管道。

1. 命名分组（Registry）

分组是一个"中间件别名列表"，可引用实例、类名、别名，甚至可以递归引用其它分组：

解析器遇到分组名时会就地展开为嵌套 Pipeline，因此分组内部仍是标准的洋葱嵌套关系。需要构建期确定性摊平（调试、序列化前校验）时，用 Registry::expand()——它带深度上限与环检测，且对合法的菱形依赖（A→B,C；B→D；C→D）不会误报成环：

2. 嵌套组合（Pipe）

Pipeline 自身实现了 MiddlewareInterface，因此天然可作为另一条管道里的一个洋葱层。Pipe 门面提供两种显式写法：

嵌套层对外层完全透明：它有自己的优先级排序，内部请求自外向内、响应自内向外，最内层终点接到主管道的下游处理器。terminate() 收尾会沿嵌套层级自动级联。

3. 路由集成（Router）

Routing\Router 是零依赖的模式路由收集器，把"路径模式 → 处理器 + 路由级中间件"登记起来，并产出 RouteResult 接入 Pipe::router()。路由级中间件可以是命名分组名，经 Pipe 与 DispatchMiddleware 共享的 Resolver 在运行期展开：

Router 支持 {name}（[^/]+）与 {name:regex} 占位符、方法约束（不满足方法返回 405）、未命中返回 404。分组 + 路由 + 嵌套在此自然咬合。

4. 路由嵌套分组（Router::group）

路由收集器原生支持带前缀与共享中间件的嵌套分组，闭包内登记的路由会自动带上累积前缀与分组共享中间件（外层 → 内层 → 路由自身）：

Pipe::router() 直接接受 Router 实例，无需再包一层 matcher()：

5. 一站式路由（Pipe::route / Pipe::routeGroup）

不想先 new Router() 再绑定的话，直接用 Pipe 逐条登记即可——内部惰性创建 Router 并自动绑定路由槽位：

Pipe::group(name, array) 注册的是命名中间件分组（可被路由引用），Pipe::routeGroup(prefix, mw, fn) 做的是路由前缀分组，二者职责不同，请勿混淆。

框架集成桥（Integration\FrameworkBridge）

给 kode 框架一行式接入中间件能力，屏蔽样板代码。框架只需描述业务路由，再把生命周期钩子以关联数组一次性传入，即可拿到可直接 run() 的 {@see Kernel}：

桥默认开启两项便利：

• stack（默认 true）：挂上内置中间件栈 Trace(1000) → Scope(900) → Timeout(850) → Concurrent(800)，按优先级自动排序。它们对未安装的兄弟扩展软降级，挂上即生效。
• observe（默认 true）：挂上异常边界 + 分层剖析（Server-Timing），二者声明高优先级恒落洋葱最外层。开启时必须提供 $renderer 异常渲染器（库不绑定具体 PSR-7 实现，由框架提供）。

FrameworkBridge::kernel() 与 bridge() 函数完全等价，后者只是命名空间级快捷入口。

代码生成（Codegen）

Codegen\MiddlewareGenerator 把"类名 / 优先级 / 描述"确定性地渲染成符合本包约定的 PSR-15 中间件源码，不依赖任何模板引擎，可无缝接入脚手架与 middleware-assistant 技能：

生成的类满足：declare(strict_types=1)、实现 Psr\Http\Server\MiddlewareInterface、暴露 public const PRIORITY（供 Pipeline 自动取用优先级）、process() 内给出"调用下游之前 / 响应返回之前"两处织入点注释。类名非法（含路径穿越字符）会抛 RuntimeException。

并发：多进程 / 多线程 / Fiber 协程

运行器自动降级

RunnerFactory 保证任何情况下都能返回一个可用的运行器，最差也是 SyncRunner。业务代码永远不需要写 if (extension_loaded('parallel')) 这类分支：

*自动挑选策略（driver = auto）按任务画像（`PROFILE_`）区分：**

• io（默认）：Fiber → Sync。I/O 密集用协程最划算，无需跨进程序列化。
• cpu：Thread → Process → Sync。CPU 密集必须真并行，线程优于进程。
• isolate：Process → Thread → Sync。强调故障隔离时进程优先。

RunnerInterface 统一方法：run($task) / all(array $tasks, ?float $timeout) / supported(): bool / close(): void。

在控制器里并发

通过 ConcurrentMiddleware 把运行器注入请求属性，下游直接取用：

相关类：ConcurrentMiddleware（优先级 800，ATTRIBUTE = kode.runner，静态 runnerOf($req)）、TimeoutMiddleware（优先级 850，deadline propagation，ON_TIMEOUT_HEADER / ON_TIMEOUT_THROW 策略，静态 remaining($req, $default)）、ScopeMiddleware（优先级 900，依赖 kode/context 做上下文隔离）。

分布式：链路追踪与节点标识

链路以 W3C Trace Context（traceparent 头）为基准，可直接被 Jaeger / SkyWalking / OTel Collector 识别。

注册表与别名（Registry）

让管道用短字符串书写。Registry 在构建期可变，管道运行期不可变，二者职责分离。

蓝图：跨进程 / 跨节点下发（Blueprint）

管道对象本身无法跨边界传输（闭包不可序列化、实例常持有连接等资源）。Blueprint 只保留「名字」——中间件类名与注册表别名——可 json_encode 后写入配置中心、随任务投递到 ext-parallel 线程、通过 IPC 发给 kode/process 子进程或下发集群其它节点；对端用本地容器 rebuild() 出等价管道。

与其他 kode 包集成

以上均为 composer.json 中的 suggest 软依赖，未安装时对应能力自动降级，不影响核心管道运行。

兼容性

设计要点：为什么能「协程安全、可重入、可重试」

常见的 MiddlewarePipeline（如 kode/http 早期实现）会在调度器上保存一个可变的 private int $index，靠自增推进管道。这有三个致命缺陷：

1. 不可重入：同一调度器处理第二个请求时，index 已停在末尾；
2. 协程不安全：Fiber / Swoole 协程交错时，两个请求会互相推进对方的游标，导致「串号」；
3. 无法重试：中间件想对下游做一次重试（两次调用 $handler->handle()）时，第二次会从错误位置继续。

本包改用 不可变游标 Cursor：每前进一步就构造一个 index+1 的新游标对象，自身状态构造后永不改变。于是管道对象在处理期间零写入，可并发共享、可重入、可重试，且可安全地跨 Worker 复用。

测试

当前测试覆盖（95 tests / 187 assertions）：管道不可变 / 可重入 / 协程交错不串号 / 可重试、Resolver 惰性 / 别名 / 分组 / 带参工厂 / 容器 / 条件 / 错误码、路由三段式顺序与兜底、Kernel 启动幂等 · 钩子 · 兜底 · 收尾级联 · Fiber 可重入、循环引用防护 / 惰性收尾级联 / 蓝图白名单等健壮性、异常边界 · 分层剖析 · 完整框架洋葱链路，以及分组递归展开 / Router 路由收集器 / Pipe 嵌套组合 / 路由引用命名分组 / Codegen 代码生成等能力；本轮新增 Router 嵌套分组前缀与中间件累积、 Pipe::router(Router) 直接接入、 Pipe::route / routeGroup 一站式登记、 FrameworkBridge 框架集成桥（stack / observe / 一行式内核） 的集成测试。

许可证

MIT