SuperAPI AI 工具集

laravel-workflows

编程与开发

查看项目

更新于 10-30 21:05

技能介绍

Laravel Workflows 通过一份技能说明,约定 Laravel 项目中长时间运行流程的编写方式。其运行时基础是 Durable Workflow(durable-workflow/workflow ^2.0,取代已弃用的 laravel-workflow/laravel-workflow)。

用途与定位

工作流用于描述一个长时间运行的过程:它只负责编排,即决定接下来运行哪个步骤、等待多长时间、等待哪个信号,不承担其他职责。它会等待外部信号或按天计算的计时器时才适合使用;如果步骤只需按顺序运行、能自行重试或报告进度,应改用作业链或作业批次,并让每个作业调用对应的 action。

主要能力与规则

工作流本身只做编排,从不写状态、从不读取数据库来选择下一步,也不判定结果。写入和决策属于它调用的 action;在事件溯源下则属于聚合,使业务规则无论由哪条路径触发都集中在一处。每个真正干活的步骤都是一个 activity,且只调用一个 action,与控制器会调用的 action 相同。activity 的 handle() 先接收工作流参数,再接收以其类名命名的 action,由容器解析 action。工作流与 activity 的参数均为普通值,例如模型的公开 id,如 handle(string $invoiceUuid);Durable Workflow 2.5 的编解码器会以 unsupported_value_type 拒绝模型参数,尽管其文档称模型可按标识符传递。工作流本身从不加载模型,因为那属于数据库读取;由 activity 加载模型,因此每个步骤都作用于当前行。

事件溯源集成

在事件溯源下,由 reactor 启动工作流和向工作流发送信号:监听开始流程的已存储事件的 reactor 启动工作流;监听等待中的工作流所需事件的 reactor 向其发送信号。启动或发信号属于副作用,副作用应放在 reactor 中,重放不会重复运行 reactor。

引擎机制

计时器、信号以及启动或加载工作流的具体机制以该包文档为准(durable-workflow.com)。v2 API 位于 Workflow\V2 命名空间下,为旧包编写的示例不适用。

示例

工作流发送提醒、等待七天、再发出最终通知:

<?php

declare(strict_types=1);

namespace App\Workflows;

use App\Workflows\Activities\IssueFinalNoticeActivity; use App\Workflows\Activities\RemindInvoiceActivity; use Workflow\V2\Workflow;

use function Workflow\V2\activity; use function Workflow\V2\days;

class CollectInvoicePaymentWorkflow extends Workflow { public function handle(string $invoiceUuid): void { activity(RemindInvoiceActivity::class, $invoiceUuid);

    days(7);

    activity(IssueFinalNoticeActivity::class, $invoiceUuid);
}

}

每个 activity 加载发票并调用与其同名的 action:

<?php

declare(strict_types=1);

namespace App\Workflows\Activities;

use App\Actions\Invoice\RemindInvoiceAction; use App\Models\Invoice; use Workflow\V2\Activity;

class RemindInvoiceActivity extends Activity { public function handle(string $invoiceUuid, RemindInvoiceAction $remindInvoiceAction): void { $remindInvoiceAction(Invoice::query()->where('uuid', $invoiceUuid)->firstOrFail()); } }

当发票被开具时,一个 reactor 启动工作流:

<?php

declare(strict_types=1);

namespace App\Reactors;

use App\Events\Invoice\InvoiceIssued; use App\Workflows\CollectInvoicePaymentWorkflow; use Spatie\EventSourcing\EventHandlers\Reactors\Reactor; use Workflow\V2\WorkflowStub;

class InvoiceIssuedReactor extends Reactor { public function onInvoiceIssued(InvoiceIssued $event): void { WorkflowStub::make(CollectInvoicePaymentWorkflow::class)->start($event->aggregateRootUuid()); } }

幂等处理

当某步骤或 reactor 的副作用不能运行两次时使用幂等。activity 失败后会重试,排队的 reactor 可能被重新投递,因此两者背后的工作都可能再次运行。可用 leeovery/laravel-idempotency 为副作用设置键。数据库内的工作(如记录事件或启动工作流)放入 Idempotency::once():它在一个事务中认领键并执行工作,若键已被认领则跳过执行。

class InvoiceIssuedReactor extends Reactor { public function onInvoiceIssued(InvoiceIssued $event): void { $invoiceUuid = $event->aggregateRootUuid();

    Idempotency::once("invoice:{$invoiceUuid}:collect-payment", function () use ($invoiceUuid): void {
        WorkflowStub::make(CollectInvoicePaymentWorkflow::class)->start($invoiceUuid);
    });
}

}

不可逆的外部副作用(如发送)不能放在事务中,因此绝不放入 once()。先检查 Idempotency::completed($key),执行工作,再调用 Idempotency::complete($key)。两次调用之间崩溃会在重试时重复发送,而不是丢失。

反模式

在工作流的 handle() 中加载发票以检查 isPaid():最终通知是否仍适用应由 action 判定。在工作流中、activity 之外执行写入、查询或调用服务。activity 做超出加载模型并调用 action 的事。把模型作为工作流或 activity 参数,引擎会拒绝。为从不等待的步骤使用工作流,应改用作业链。在 Idempotency::once() 中执行发送或其他外部调用,回滚无法撤回它。

相关技能

laravel-event-sourcing 涉及聚合、事件以及启动工作流的 reactor;laravel-actions 是 activity 调用的操作;laravel-jobs 用于不等待的流程的作业链与批次;leeovery/laravel-idempotency 为可能运行两次的副作用提供幂等键。

限制与说明

该技能只记录到目前为止的决策,未涉及之处应遵循项目自身约定。引擎的具体机制以 Durable Workflow 文档为准,v2 API 位于 Workflow\V2 下,旧包示例不适用。