Pipeline是Laravel中专用于顺序执行可复用、可插拔中间件式操作的工具，适用于请求处理、数据转换等场景，而非通用流程控制；应避免在简单逻辑中滥用。
管道（Pipeline）在 Laravel 中不是用来“流程控制”的通用机制，而是专用于按顺序执行一组中间件式操作的工具，典型场景是请求处理链、数据转换、权限校验等。它不替代路由或控制器逻辑流，也不该被当成 if/else 的替代品。
什么时候该用 Pipeline 而不是写普通方法链
当你有一组**可复用、可插拔、有统一输入输出契约**的操作，并且它们的执行顺序固定、彼此解耦时，Pipeline 才值得引入。比如：对上传文件做「验证 → 重命名 → 存储 → 生成缩略图 → 记录日志」这一串动作，每个步骤都只关心上一步的返回值，且可能在多个控制器中复用。
- 直接写方法链（如
$file->validate()->rename()->store()）更轻量，但难以动态增删步骤、无法共享前置/后置逻辑 - 用
Pipeline可以集中管理执行顺序、统一异常捕获、支持条件跳过（通过返回$passable或抛出异常）、方便单元测试 - 常见误用：在单个控制器里为一两个简单判断硬套
Pipeline，反而增加认知负担和调试难度
Pipeline 的基本用法和参数差异
核心是 Illuminate\Pipeline\Pipeline 类，Laravel 自带的 pipe() 方法接受一个闭包数组，每个闭包接收两个参数：$passable（当前传递的数据）和 $next（下一个闭包）。必须显式调用 $next($passable) 才能继续流转。
$result = app(Pipeline::class)
->send($user)
->through([
function ($user, $next) {
if (! $user->active) {
throw new Exception('User is not active');
}
return $next($user);
},
function ($user, $next) {
$user->last_accessed = now();
return $next($user);
}
])
->then(function ($user) {
return $user->toArray();
});
-
send()是初始数据，类型任意，但所有pipe闭包必须兼容它 -
through()接收数组，元素可以是闭包、类名（需实现__invoke）、或带方法名的数组（如[AuthCheck::class, 'handle']） -
then()是终值处理器，不传则返回最后一个pipe的返回值；若某个pipe没调用$next()，流程就终止，后续pipe不执行
在控制器中集成 Pipeline 的实际写法
不要在控制器方法体里直接拼 app(Pipeline::class)->send(...)。应该把 pipeline 定义抽离成独立服务或专用类，控制器只负责触发。
- 新建
app/Actions/ProcessOrder.php，构造函数注入必要依赖（如OrderRepository），定义handle(Order $order)方法，在其中组织Pipeline - 避免在
through数组里写业务逻辑，而是引用已定义好的类（如[ValidateOrder::class, FinalizePayment::class]），每个类专注一件事 - 注意异常处理：pipeline 内部抛出的异常不会被控制器的
try/catch自动捕获，需在then()外层包裹，或在每个pipe内处理 - 性能影响极小，但频繁创建 pipeline 实例（如循环内）会带来轻微开销，应复用或提前实例化
容易踩的坑：$next 忘记调用或错误返回
这是最常导致“流程静默中断”的问题。现象是 pipeline 看似执行了前几步，但没进 then()，也没有报错。
- 错误写法：
if ($user->banned) { return; }—— 这里没调用$next()，也没返回$next($user)，流程卡死 - 正确写法：
if ($user->banned) { throw new BannedException(); }或return $next($user); - 另一个陷阱：在
pipe里修改了$passable但没返回它（比如只写了$user->status = 'processed';），会导致下游收到原始未修改对象 - 调试建议：在每个
pipe开头加Log::debug('In pipe X', ['user' => $user->id]);，确认是否真正进入
真正要用好 Pipeline，关键不是语法多复杂，而是想清楚哪些逻辑真的需要“可编排、可跳过、可复用”——大多数时候，一个清晰的私有方法已经足够。
