补偿成功事务场景 (Compensating Success Transaction)

在此场景中，SEC 未能全部执行完所有正向执行器。在执行途中某个步骤发生了业务异常或不可恢复错误。因此，Saga 引擎立即启动逆向补偿流程，将此前成功执行的步骤逐一逆向撤销。

StackSaga 补偿成功事务场景架构图

  • 1 用户发起请求：客户端发起下单请求，由 Spring MVC 的 OrderController 接收请求入口。

  • 2 初始化领域实体：初始化下单领域的 DomainEntity，配置起始执行器并将事务委托给 StackSaga。 （在此阶段，框架自动分配全局唯一的 transaction uid，可直接通过 DomainEntity 对象获取。）

  • 3 SEC 协调接管：在正式调用起始执行器前，SEC 将 DomainEntity 的初始状态快照原子写入事件存储 (Event Store)。

  • 4 执行起始执行器 ([Command] CreateOrderExecutor)：

    • 4.1 SEC 触发 doProcess，调用 InternalOrderService 的 createOrder() 方法在本地创建订单。

    • 4.2 调用成功后，SEC 将领域实体的最新状态快照保存至事件存储。

    • 4.3 快照落盘后，SEC 回调 Handler 的 onEachProcessPerformed 方法。

    • 4.4 业务层在回调中更新订单状态为“已创建”。

    • 4.5 异步下发短信或邮件通知客户订单已成功受理。

  • 5 执行第 2 个执行器 ([Query] UserExecutor)：

    • 5.1 SEC 调度 [Query] UserExecutor 的 doProcess 方法，调用 ExternalUserStatusService 的 checkUser()。

    • 5.2 ExternalUserStatusService 远程调用 user-service 验证用户信息。

    • 5.3 调用成功返回后，SEC 记录状态快照。

    • 5.4 SEC 回调 Handler 的 onEachProcessPerformed 方法。

      注：由于该执行器属于纯查询性质的 QueryExecutor，因此在此处不涉及任何状态变更或订单数据更新。

  • 6 执行支付执行器时发生异常 ([Command] PaymentExecutor)：

    • 6.1 SEC 调度 PaymentExecutor 的 doProcess 方法，触发 ExternalPaymentService 的 makePayment()。

    • 6.2 ExternalPaymentService 远程向 payment-service 发起扣款请求。在此步骤中，调用发生异常（例如用户信用卡额度不足或账户已被冻结）。

  • 7 异常捕获与补偿启动：

    • SEC 捕获到执行异常，并立即回调 Handler 的 onProcessException 钩子方法，通知业务层*处理过程发生失败*。

    • 由于该异常不可继续正向重试推进，正向执行流在此终止，Saga 引擎立即从此节点切换为逆向补偿流程 (Compensating Process)。

      (注：如果需要在此刻向用户下发退单提示或预先更新订单状态，可在该回调中执行相应代码。)

  • 8 逆向执行补偿逻辑：

    • 倒序查找需要被撤销的步骤。由于 UserExecutor 是纯查询操作，无需任何补偿；因此补偿流程直接定位至上一个 CommandExecutor —— 即 OrderExecutor。

    • SEC 调度 OrderExecutor 的 doRevert 补偿方法。

    • 8.1 doRevert 方法内部调用 createOrderRevert，将此前创建的订单记录状态置为“已取消/已作废”。

    • 8.2 如果在补偿过程中需要暂存特定回滚元数据（如撤销凭据、日志或批注），可将其保存至框架提供的回滚提示存储 (Revert-Hint-Store) 中。

    • 8.3 补偿逻辑顺利执行完毕后，SEC 自动回调 Handler 的 onEachRevertPerformed 钩子方法。

    • 8.4 业务系统通知客户由于扣款失败，订单已自动撤销。

  • 9 补偿完成终态确认：

    • StackSaga 状态机确认所有已提交的步骤均已完全反向补偿完毕。

    • SEC 调用 Handler 的 onTransactionCompleted 回调，传入终态标识 REVERT_SUCCESS（补偿成功）。

    • 9.1 业务层将订单记录更新为“已成功回滚 (REVERTED)”。

    • 9.2 向用户推送订单已全额撤销的终态确认凭证。

为了保障分布式长事务在全局视角下的最终一致性，补偿过程本身也是支持自动重试的。因为无论发生什么网络抖动，所有必须执行的补偿动作都必须确保被彻底调用。欲深入了解 StackSaga 中逆向补偿的重试工作机制，请参阅相关异常与重试说明文档。