Laravel 管道由 Illuminate\Pipeline\Pipeline 实现，基于责任链模式，通过中间件式闭包或可容器解析的类（需实现 handle 方法）串联执行；send() 输入数据，through() 指定中间件，then() 定义最终返回值，中间件必须 return $next($passable) 以确保流程贯通。
管道操作在 Laravel 里用 Pipeline 类，不是靠 PHP 8.0+ 的箭头函数或 shell 风格语法
很多人搜“Laravel 管道”第一反应是 PHP 的新特性或 Unix 风格的 |，但 Laravel 的管道机制是基于 Illuminate\Pipeline\Pipeline 实现的，本质是责任链模式。它不依赖语言级语法糖，而是靠中间件式闭包串联，适用于请求预处理、数据转换、权限校验等有明确顺序的流程。
常见错误现象：Call to undefined function pipe()（误以为是全局函数）、Argument 1 passed to Pipeline::send() must be an instance of Illuminate\Contracts\Pipeline\Hub（传参类型错）、流程中途中断没抛异常（忘记 return $passable）。
- 必须手动实例化
Pipeline或通过容器解析，不能直接调用静态方法链式调用（Pipeline::send(...)->through(...)->then(...)是可行的，但底层仍是对象实例） -
through()接收的是闭包数组或类名数组；若用类名，该类必须实现handle($passable, $next)方法 -
send()的参数是你想“流过”整个管道的数据，可以是数组、模型、DTO 实例，甚至Request - 每个中间件闭包最后必须
return $next($passable)，否则流程断掉且无提示
$result = app(Pipeline::class)
->send($order)
->through([
function ($order, $next) {
if ($order->status !== 'pending') {
throw new RuntimeException('Order already processed');
}
return $next($order);
},
function ($order, $next) {
$order->update(['status' => 'checking']);
return $next($order);
}
])
->then(function ($order) {
return $order->refresh();
});
怎么让管道支持依赖注入的中间件类
写一堆匿名函数可读性差，也难复用。Laravel 允许传入类名字符串，由容器自动解析并调用 handle 方法——但这个类不能是普通 Service 类，必须满足接口契约。
使用场景：把风控校验、库存锁定、优惠计算拆成独立类，便于单元测试和复用。
- 类必须定义
handle($passable, Closure $next)方法，且第二个参数类型提示要写全Closure - 不要在
handle里写return $next($passable)->someMethod()这种链式调用，$next()返回的是最终then()的结果，不是中间态对象 - 如果中间件需要构造参数（比如配置项），得用容器绑定时传入，或改用工厂闭包方式注册
- 注意生命周期：每次管道执行都会新建中间件实例，所以类里别存状态
// App\Pipes\ValidateInventoryPipe.php
class ValidateInventoryPipe
{
public function handle($order, Closure $next)
{
if (! $order->item->inStock($order->quantity)) {
throw new OutOfStockException();
}
return $next($order);
}
}
// 使用时
app(Pipeline::class)
->send($order)
->through([ValidateInventoryPipe::class, ApplyCouponPipe::class])
->then(fn ($o) => $o->save());
为什么 then() 里的回调有时拿不到预期返回值
这是最常被忽略的一点：管道的返回值只取决于 then() 回调的返回值，和中间件里 return $next($passable) 没有直接映射关系。中间件只是“放行”，不决定最终输出。
性能影响：如果中间件里做了 heavy work（如 DB 查询）但 then() 根本不用结果，就白跑了；反过来，如果 then() 需要中间态数据，就得靠修改 $passable（比如加属性）或用引用传递。
-
$next($passable)执行的是下一个中间件，最终落到then()回调上，所以then()是唯一出口 - 中间件之间共享数据只能靠修改传入对象（如给
$order加->validation_result属性），不能靠返回值“透传” - 如果某个中间件提前
throw，then()不会执行，需在外层 try/catch - 别在
then()里再做耗时操作，它本该是轻量终局处理（如保存、返回响应）
管道不适合替代简单 if-else 或 service method chain
当流程分支多、条件跳转复杂（比如“校验通过走 A，失败走 B，B 失败再降级走 C”），硬塞进线性管道反而难维护。管道适合“单向、确定、可预测”的步骤流。
容易踩的坑：through() 数组顺序写反、中间件里漏 return $next(...) 导致静默失败、把需要并行执行的逻辑强行串行化。
- 三步以内逻辑，直接写方法更清晰；超过五步且每步职责单一，才值得上管道
- 涉及数据库事务的步骤，别分散在多个中间件里 commit/rollback，应统一交由
then()或外层事务包裹 - 调试时别只看
then()，要用 xdebug 跟进每个handle，尤其注意$next调用前后$passable的变化
管道不是银弹，它把流程“显式化”了，但也把控制权交给了框架的执行模型。真正难的从来不是怎么写，而是判断哪段逻辑值得被管道化。
