Symfony Workflow组件实战：建模复杂业务流程与状态机的应用指南

各位朋友，大家好！今天我们来深入探讨Symfony Workflow组件，并结合实际案例，详细讲解如何利用它来建模复杂的业务流程和状态机。Workflow组件是Symfony框架中一个非常强大的工具，它可以帮助我们清晰地定义和管理应用程序中的状态转换，从而提高代码的可维护性和可扩展性。

一、Workflow组件概述

在开始之前，我们需要对Workflow组件有一个基本的了解。Workflow组件的核心概念包括：

Subject (主题): 这是需要进行状态转换的对象，可以是任何PHP对象，例如订单、文章、用户等等。
Workflow (工作流): 定义了一系列状态和转换规则，描述了Subject可以经历的状态及其转换方式。
State (状态): Subject在特定时刻所处的状态，例如“草稿”、“审核中”、“已发布”。
Transition (转换): 将Subject从一个状态移动到另一个状态的操作，例如“提交”、“审核”、“发布”。
Marking (标记): 表示Subject当前所处状态的标记，通常是一个或多个状态的名称。
Guard (守卫): 在转换发生之前执行的条件检查，决定是否允许进行转换。
Place (位置): 工作流中的状态，Subject可以在这些位置之间移动。

Workflow组件的核心职责就是管理这些概念之间的关系，确保状态转换的正确性和一致性。

二、安装Workflow组件

首先，我们需要通过Composer安装Workflow组件：

composer require symfony/workflow

安装完成后，就可以在Symfony应用程序中使用Workflow组件了。

三、定义Workflow配置

Workflow的定义通常放在config/packages/workflow.yaml文件中。下面是一个订单工作流的示例：

# config/packages/workflow.yaml
framework:
    workflows:
        order_workflow:
            type: 'state_machine' # 可以是 'state_machine' 或 'workflow'
            marking_store:
                type: 'method'
                property: 'state' # Subject的属性，用于存储状态
            supports:
                - AppEntityOrder # 支持的Subject类型
            places:
                - cart # 购物车
                - pending # 待支付
                - processing # 处理中
                - shipped # 已发货
                - completed # 已完成
                - cancelled # 已取消
            transitions:
                create:
                    from: cart
                    to: pending
                pay:
                    from: pending
                    to: processing
                ship:
                    from: processing
                    to: shipped
                complete:
                    from: shipped
                    to: completed
                cancel:
                    from: cart
                    to: cancelled
                cancel_pending:
                    from: pending
                    to: cancelled
                cancel_processing:
                    from: processing
                    to: cancelled

在这个配置中：

order_workflow 是工作流的名称。
type 指定了工作流的类型，state_machine 表示状态机，workflow 表示更通用的工作流。状态机强调单一状态，工作流可以同时处于多个状态。
marking_store 定义了如何存储Subject的状态。 method 表示使用Subject的属性来存储。 property 指定了用于存储状态的属性名称，这里是 state。
supports 定义了哪些Subject类型可以使用这个工作流。
places 定义了工作流中的所有状态。
transitions 定义了状态之间的转换。每个转换都有一个名称 (create, pay, ship, complete, cancel 等)，以及 from 和 to 属性，分别指定了转换的起始状态和目标状态。

四、创建Subject实体

接下来，我们需要创建一个Subject实体，例如 AppEntityOrder：

<?php

namespace AppEntity;

use DoctrineORMMapping as ORM;

/**
 * @ORMEntity(repositoryClass="AppRepositoryOrderRepository")
 */
class Order
{
    /**
     * @ORMId()
     * @ORMGeneratedValue()
     * @ORMColumn(type="integer")
     */
    private $id;

    /**
     * @ORMColumn(type="string", length=255)
     */
    private $state = 'cart'; // 默认状态

    public function getId(): ?int
    {
        return $this->id;
    }

    public function getState(): ?string
    {
        return $this->state;
    }

    public function setState(string $state): self
    {
        $this->state = $state;

        return $this;
    }
}

请注意，state 属性用于存储订单的状态，并且默认值为 'cart'。这个属性的名称必须与 workflow.yaml 中 marking_store 的 property 属性一致。

五、使用Workflow组件

现在，我们可以在Controller中使用Workflow组件来管理订单的状态转换：

<?php

namespace AppController;

use AppEntityOrder;
use SymfonyBundleFrameworkBundleControllerAbstractController;
use SymfonyComponentHttpFoundationResponse;
use SymfonyComponentRoutingAnnotationRoute;
use SymfonyComponentWorkflowRegistry;

class OrderController extends AbstractController
{
    /**
     * @Route("/order/{id}/{transition}", name="order_transition")
     */
    public function transition(Order $order, string $transition, Registry $workflowRegistry): Response
    {
        $workflow = $workflowRegistry->get($order, 'order_workflow');

        if ($workflow->can($order, $transition)) {
            $workflow->apply($order, $transition);

            $entityManager = $this->getDoctrine()->getManager();
            $entityManager->flush(); // 持久化状态变更

            $this->addFlash('success', 'Order transitioned to ' . $order->getState());
        } else {
            $this->addFlash('error', 'Cannot transition order to ' . $transition);
        }

        return $this->redirectToRoute('home'); // 重定向到首页或其他页面
    }
}

在这个Controller中：

我们注入了 SymfonyComponentWorkflowRegistry 服务，它用于获取特定Subject的Workflow实例。
通过 $workflowRegistry->get($order, 'order_workflow') 获取了 order_workflow 工作流实例，并将其与 $order 对象关联起来。
$workflow->can($order, $transition) 方法检查是否允许从当前状态执行指定的转换。
如果允许转换，$workflow->apply($order, $transition) 方法执行转换，更新 $order 的状态。
最后，我们需要将状态变更持久化到数据库。

六、添加Guard (守卫)

Guard用于在转换发生之前执行条件检查。例如，我们可能希望只有管理员才能取消订单。我们可以通过添加 guard 节点到 workflow.yaml 中来实现这一点：

# config/packages/workflow.yaml
framework:
    workflows:
        order_workflow:
            # ... 其他配置
            transitions:
                cancel:
                    from: cart
                    to: cancelled
                    guard: "is_granted('ROLE_ADMIN')" # 添加Guard
                cancel_pending:
                    from: pending
                    to: cancelled
                    guard: "is_granted('ROLE_ADMIN')"
                cancel_processing:
                    from: processing
                    to: cancelled
                    guard: "is_granted('ROLE_ADMIN')"

现在，只有具有 ROLE_ADMIN 角色的用户才能执行 cancel 转换。 is_granted 是 Symfony Security 组件提供的表达式函数，用于检查用户是否具有指定的权限。

我们还可以使用表达式语言定义更复杂的Guard条件。例如，只有订单金额大于100元的订单才能被取消：

# config/packages/workflow.yaml
framework:
    workflows:
        order_workflow:
            # ... 其他配置
            transitions:
                cancel:
                    from: cart
                    to: cancelled
                    guard: "order.getTotalAmount() > 100" # 添加Guard
                cancel_pending:
                    from: pending
                    to: cancelled
                    guard: "order.getTotalAmount() > 100"
                cancel_processing:
                    from: processing
                    to: cancelled
                    guard: "order.getTotalAmount() > 100"

要使这个Guard生效，需要在 Order 实体中添加 getTotalAmount() 方法：

<?php

namespace AppEntity;

use DoctrineORMMapping as ORM;

/**
 * @ORMEntity(repositoryClass="AppRepositoryOrderRepository")
 */
class Order
{
    // ... 其他属性和方法

    /**
     * @ORMColumn(type="float")
     */
    private $totalAmount;

    public function getTotalAmount(): ?float
    {
        return $this->totalAmount;
    }

    public function setTotalAmount(float $totalAmount): self
    {
        $this->totalAmount = $totalAmount;

        return $this;
    }
}

并在数据库表中创建 total_amount 列。

七、事件监听器

Workflow组件允许我们监听状态转换的各个阶段，并在特定事件发生时执行自定义逻辑。这可以通过事件监听器来实现。

首先，我们需要创建一个事件监听器类，例如 AppEventListenerOrderWorkflowListener：

<?php

namespace AppEventListener;

use AppEntityOrder;
use SymfonyComponentEventDispatcherEventSubscriberInterface;
use SymfonyComponentWorkflowEventEvent;
use SymfonyComponentWorkflowEventGuardEvent;

class OrderWorkflowListener implements EventSubscriberInterface
{
    public static function getSubscribedEvents()
    {
        return [
            'workflow.order_workflow.enter' => 'onOrderEnter', // 进入任何状态时触发
            'workflow.order_workflow.leave' => 'onOrderLeave', // 离开任何状态时触发
            'workflow.order_workflow.transition' => 'onOrderTransition', // 任何转换时触发
            'workflow.order_workflow.completed' => 'onOrderCompleted', //  进入 "completed" 状态时触发
            'workflow.order_workflow.guard.pay' => 'onOrderPayGuard', // 执行 pay 转换前触发
        ];
    }

    public function onOrderEnter(Event $event)
    {
        $order = $event->getSubject();

        if ($order instanceof Order) {
            // 在进入状态时执行的逻辑
            // 例如：记录日志
            // dump('Entering state: ' . $event->getMarking()->getPlaces()[0]);
        }
    }

    public function onOrderLeave(Event $event)
    {
        $order = $event->getSubject();

        if ($order instanceof Order) {
            // 在离开状态时执行的逻辑
            // 例如：发送通知
            // dump('Leaving state: ' . $event->getMarking()->getPlaces()[0]);
        }
    }

    public function onOrderTransition(Event $event)
    {
        $order = $event->getSubject();
        $transitionName = $event->getTransition()->getName();

        if ($order instanceof Order) {
            // 在转换时执行的逻辑
            // 例如：更新订单的最后修改时间
            // dump('Transitioning: ' . $transitionName);
        }
    }

    public function onOrderCompleted(Event $event)
    {
        $order = $event->getSubject();

        if ($order instanceof Order) {
            // 在订单完成时执行的逻辑
            // 例如：发送感谢信
            // dump('Order completed!');
        }
    }

    public function onOrderPayGuard(GuardEvent $event)
    {
        $order = $event->getSubject();

        if ($order instanceof Order && $order->getTotalAmount() <= 0) {
            $event->setBlocked(true);
            // dump('Payment blocked due to zero or negative total amount.');
        }
    }
}

然后，我们需要将事件监听器注册为服务：

# config/services.yaml
services:
    AppEventListenerOrderWorkflowListener:
        tags:
            - { name: kernel.event_subscriber }

在这个监听器中：

getSubscribedEvents() 方法定义了监听哪些事件以及对应的处理函数。
onOrderEnter(), onOrderLeave(), onOrderTransition() 分别在进入状态、离开状态和执行转换时触发。
onOrderCompleted() 在进入 completed 状态时触发，这是一个更具体的事件。
onOrderPayGuard() 是一个Guard事件监听器，它在执行 pay 转换之前触发。如果订单金额小于等于0，则阻止转换。

注意：workflow.WORKFLOW_NAME.guard.TRANSITION_NAME 格式的事件，必须使用GuardEvent类型。

八、使用Workflow类型

在 workflow.yaml 中，我们可以使用 state_machine 或 workflow 类型。

state_machine 适用于状态之间互斥的情况，即Subject在任何时候只能处于一个状态。
workflow 适用于Subject可以同时处于多个状态的情况。

例如，我们可以创建一个文章发布工作流，允许文章同时处于“草稿”和“已审核”状态：

# config/packages/workflow.yaml
framework:
    workflows:
        article_workflow:
            type: 'workflow'
            marking_store:
                type: 'multiple_state'
                arguments: {property: 'states'}  # 存储多个状态的属性
            supports:
                - AppEntityArticle
            initial_marking: [draft] # 初始状态
            places:
                - draft
                - review
                - published
            transitions:
                submit:
                    from: draft
                    to: review
                publish:
                    from: review
                    to: published
                unpublish:
                    from: published
                    to: review

在这个例子中，marking_store 的 type 设置为 multiple_state，表示Subject可以同时处于多个状态。 arguments 数组传递了 property 属性，用于存储状态。 initial_marking 定义了Subject的初始状态。

相应地，我们需要修改 Article 实体，使用一个数组来存储状态：

<?php

namespace AppEntity;

use DoctrineORMMapping as ORM;

/**
 * @ORMEntity(repositoryClass="AppRepositoryArticleRepository")
 */
class Article
{
    /**
     * @ORMId()
     * @ORMGeneratedValue()
     * @ORMColumn(type="integer")
     */
    private $id;

    /**
     * @ORMColumn(type="json")
     */
    private $states = ['draft']; // 默认状态，使用数组

    public function getId(): ?int
    {
        return $this->id;
    }

    public function getStates(): ?array
    {
        return $this->states;
    }

    public function setStates(array $states): self
    {
        $this->states = $states;

        return $this;
    }
}

请注意，states 属性现在是一个数组，用于存储文章的状态。

九、Workflow组件的优势

使用Workflow组件可以带来以下好处：

清晰的状态管理: 将业务流程中的状态和转换规则明确地定义在配置文件中，提高了代码的可读性和可维护性。
强制执行状态转换规则: Workflow组件确保状态转换按照预定义的规则进行，避免了非法状态转换的发生。
可扩展性: 通过添加Guard和事件监听器，可以轻松地扩展Workflow的功能，满足不同的业务需求。
可测试性: Workflow组件提供了方便的测试接口，可以对状态转换规则进行单元测试。

十、实际案例：电商订单流程

让我们回到电商订单的例子，并考虑更复杂的场景。一个完整的电商订单流程可能包括以下状态：

状态	描述
cart	购物车，用户尚未提交订单
pending	待支付，用户已提交订单，等待支付
processing	处理中，已支付，商家正在准备发货
shipped	已发货，商家已发货，等待用户确认收货
completed	已完成，用户已确认收货，订单完成
cancelled	已取消，用户或商家取消了订单
refunded	已退款，订单已退款
returned	已退货，用户申请退货，等待商家处理
returning	退货中，用户已寄回商品，等待商家签收

相应的转换可能包括：

转换	描述	起始状态	目标状态
create	创建订单，将商品添加到购物车	cart	pending
pay	支付订单，用户完成支付	pending	processing
ship	发货，商家将商品发货	processing	shipped
complete	完成订单，用户确认收货	shipped	completed
cancel	取消订单，用户在未支付前取消订单	cart	cancelled
cancel_pending	取消订单，用户在支付后取消订单	pending	cancelled
cancel_processing	取消订单，商家在发货前取消订单	processing	cancelled
refund	退款，商家同意退款	processing/shipped/completed	refunded
return	申请退货，用户申请退货	shipped/completed	returned
approve_return	同意退货，商家同意用户退货申请	returned	returning
reject_return	拒绝退货，商家拒绝用户退货申请	returned	shipped/completed
receive_return	收到退货，商家收到用户寄回的商品	returning	refunded

通过Workflow组件，我们可以将这个复杂的订单流程清晰地建模，并确保状态转换的正确性和一致性。

十一、总结要点

Workflow组件提供了一种结构化的方式来管理复杂的状态转换。配置文件的简洁性、Guard的灵活性以及事件监听机制的强大功能，使得Workflow组件成为Symfony应用程序中不可或缺的工具。通过合理地使用Workflow组件，可以极大地提高代码的可维护性和可扩展性，从而更好地应对不断变化的业务需求。

Symfony Workflow组件实战：建模复杂业务流程与状态机的应用指南

发表回复 取消回复

发表回复取消回复