当前位置：首页 > news >正文

Spring Statemachine 架构详解

news 2025/9/30 7:13:57

Spring Statemachine 是一个用于在 Spring 应用中实现状态机概念的框架。它提供了一种清晰的方式来管理复杂的业务状态流转，特别适用于订单、工单、审批等有明确状态生命周期模型的业务场景。

一、核心架构概览

Spring Statemachine 的架构是分层和模块化的，主要分为以下几个核心层次：

+-----------------------------------+
|          Application Layer        |  (您的业务代码)
+-----------------------------------+
|   Spring Statemachine Framework   |
| +-------------------------------+ |
| |        StateMachine         | |  (状态机实例)
| +-------------------------------+ |
| |   StateMachineContext       | |  (状态机上下文)
| +-------------------------------+ |
| |   StateMachinePersist       | |  (持久化)
| +-------------------------------+ |
| |   StateMachineConfig        | |  (配置)
| +-------------------------------+ |
+-----------------------------------+
|         Spring Framework          |  (底层支撑)
+-----------------------------------+

二、核心组件详解

1. 状态机核心接口 (`StateMachine`)

这是与状态机交互的主要入口。

关键方法：

start(): 启动状态机
sendEvent(E event): 发送事件触发状态转换
getState(): 获取当前状态
addStateListener(): 添加状态监听器

2. 状态 (State)

代表状态机可能处于的状况。

类型：

初始状态 (Initial State): 状态机的起点
正常状态 (Normal State): 普通业务状态
选择状态 (Choice State): 基于条件的路径选择
** junction状态 (Junction State)**: 复杂条件分支
最终状态 (Final State): 状态机的终点
分叉/汇合状态 (Fork/Join State): 用于实现并行子状态机

3. 事件 (Event)

触发状态转换的信号。通常是枚举或字符串。

4. 转换 (Transition)

定义状态如何响应事件而改变。

转换类型：

外部转换 (External Transition): 源状态和目标状态不同
内部转换 (Internal Transition): 源状态和目标状态相同，执行动作但不改变状态
本地转换 (Local Transition): 在子状态机内部的转换

5. 守卫 (Guard)

转换的条件判断，返回 boolean 决定是否允许转换。

public class OrderGuard implements Guard<String, String> {@Overridepublic boolean evaluate(StateContext<String, String> context) {return context.getMessageHeader("amount") != null;}
}

6. 动作 (Action)

在状态转换过程中执行的具体业务逻辑。

public class PaymentAction implements Action<String, String> {@Overridepublic void execute(StateContext<String, String> context) {// 执行支付逻辑System.out.println("Processing payment...");}
}

三、配置方式详解

1. 枚举配置方式（推荐）

public enum OrderStates {INITIAL, PAYMENT_PENDING, PAYMENT_PROCESSING, PAYMENT_SUCCESS, PAYMENT_FAILED, COMPLETED, CANCELLED
}public enum OrderEvents {SUBMIT, PROCESS_PAYMENT, PAYMENT_SUCCESS, PAYMENT_FAILED, CANCEL
}

2. 配置类示例

@Configuration
@EnableStateMachine
public class OrderStateMachineConfig extends StateMachineConfigurerAdapter<OrderStates, OrderEvents> {@Overridepublic void configure(StateMachineStateConfigurer<OrderStates, OrderEvents> states) throws Exception {states.withStates().initial(OrderStates.INITIAL).state(OrderStates.PAYMENT_PENDING).state(OrderStates.PAYMENT_PROCESSING, paymentAction(), null) // 进入动作，退出动作.state(OrderStates.PAYMENT_SUCCESS).state(OrderStates.PAYMENT_FAILED, errorAction()).end(OrderStates.COMPLETED).end(OrderStates.CANCELLED);}@Overridepublic void configure(StateMachineTransitionConfigurer<OrderStates, OrderEvents> transitions) throws Exception {transitions.withExternal().source(OrderStates.INITIAL).target(OrderStates.PAYMENT_PENDING).event(OrderEvents.SUBMIT).guard(orderGuard()).and().withExternal().source(OrderStates.PAYMENT_PENDING).target(OrderStates.PAYMENT_PROCESSING).event(OrderEvents.PROCESS_PAYMENT).action(paymentAction()).and().withExternal().source(OrderStates.PAYMENT_PROCESSING).target(OrderStates.PAYMENT_SUCCESS).event(OrderEvents.PAYMENT_SUCCESS).action(successAction()).and().withExternal().source(OrderStates.PAYMENT_PROCESSING).target(OrderStates.PAYMENT_FAILED).event(OrderEvents.PAYMENT_FAILED).action(failureAction());}@Beanpublic Guard<OrderStates, OrderEvents> orderGuard() {return new OrderGuard();}@Beanpublic Action<OrderStates, OrderEvents> paymentAction() {return new PaymentAction();}
}

四、高级特性架构

1. 分层状态机 (Hierarchical State Machine)

@Override
public void configure(StateMachineStateConfigurer<OrderStates, OrderEvents> states) throws Exception {states.withStates().initial(OrderStates.INITIAL).state(OrderStates.PAYMENT_PENDING).state(OrderStates.PROCESSING).and().withStates().parent(OrderStates.PROCESSING).initial(OrderStates.PACKAGING).state(OrderStates.SHIPPING).state(OrderStates.DELIVERING);
}

2. 区域状态机 (Regions - 并行状态)

@Override
public void configure(StateMachineStateConfigurer<States, Events> states) throws Exception {states.withStates().initial(States.SI).state(States.S1).and().withStates().parent(States.S1).initial(States.S2).region("R1").state(States.S3).and().withStates().parent(States.S1).initial(States.S4).region("R2").state(States.S5);
}

3. 持久化架构

public interface StateMachinePersist<S, E, T> {void write(StateMachineContext<S, E> context, T contextObj) throws Exception;StateMachineContext<S, E> read(T contextObj) throws Exception;
}// Redis持久化示例
@Bean
public RedisStateMachinePersister<String, String> redisPersister(RedisPersistingStateMachineInterceptor<String, String> persister) {return new RedisStateMachinePersister<>(persister);
}

五、监听器架构

提供完整的状态机生命周期监听。

@Component
public class OrderStateMachineListener implements StateMachineListener<OrderStates, OrderEvents> {@Overridepublic void stateChanged(State<OrderStates, OrderEvents> from, State<OrderStates, OrderEvents> to) {System.out.println("State changed from " + from + " to " + to);}@Overridepublic void eventNotAccepted(Message<OrderEvents> event) {System.out.println("Event not accepted: " + event.getPayload());}@Overridepublic void transition(Transition<OrderStates, OrderEvents> transition) {// 转换开始}@Overridepublic void transitionStarted(Transition<OrderStates, OrderEvents> transition) {// 转换开始}@Overridepublic void transitionEnded(Transition<OrderStates, OrderEvents> transition) {// 转换结束}
}

六、使用示例

1. 服务层封装

@Service
public class OrderStateMachineService {@Autowiredprivate StateMachine<OrderStates, OrderEvents> stateMachine;@Autowiredprivate StateMachinePersist<OrderStates, OrderEvents, String> persister;public boolean submitOrder(String orderId) {stateMachine.start();// 发送事件boolean accepted = stateMachine.sendEvent(OrderEvents.SUBMIT);if (accepted) {// 持久化状态persister.persist(stateMachine, orderId);}return accepted;}public boolean processPayment(String orderId) {// 从持久化存储恢复状态机stateMachine = persister.restore(stateMachine, orderId);Message<OrderEvents> message = MessageBuilder.withPayload(OrderEvents.PROCESS_PAYMENT).setHeader("orderId", orderId).build();return stateMachine.sendEvent(message);}
}

2. 控制器层

@RestController
@RequestMapping("/orders")
public class OrderController {@Autowiredprivate OrderStateMachineService stateMachineService;@PostMapping("/{orderId}/submit")public ResponseEntity<String> submitOrder(@PathVariable String orderId) {boolean success = stateMachineService.submitOrder(orderId);if (success) {return ResponseEntity.ok("Order submitted successfully");} else {return ResponseEntity.badRequest().body("Failed to submit order");}}
}