Springboot 集成 SpringState 状态机

1.SpringState 简介

状态机核心概念​​

应用场景

• 订单生命周期管理​​
  管理订单从创建到完成的完整流程（如待支付 → 待发货 → 已完成）

• 工作流引擎​​
  审批流程的状态控制（如提交 → 审核中 → 已批准）

• ​​游戏状态流转​​
  角色状态切换（如空闲 → 战斗 → 死亡）

• 物联网设备监控​​
  设备状态跟踪（如离线 → 在线 → 故障）

2.状态机示例

2.1 项目结构和依赖包

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>org.example</groupId>
    <artifactId>spring-state-m</artifactId>
    <version>1.0-SNAPSHOT</version>

    <properties>
        <maven.compiler.source>21</maven.compiler.source>
        <maven.compiler.target>21</maven.compiler.target>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <spring-boot.version>3.5.3</spring-boot.version>
    </properties>

    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-dependencies</artifactId>
                <version>${spring-boot.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-data-redis</artifactId>
        </dependency>

        <!-- Spring State Machine -->
        <dependency>
            <groupId>org.springframework.statemachine</groupId>
            <artifactId>spring-statemachine-starter</artifactId>
            <version>4.0.0</version>
        </dependency>
        <!-- Spring State Machine Redis Persistence -->
        <dependency>
            <groupId>org.springframework.statemachine</groupId>
            <artifactId>spring-statemachine-data-redis</artifactId>
            <version>4.0.0</version>
        </dependency>
    </dependencies>
</project>

启动类

package org.example;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.scheduling.annotation.EnableAsync;

@EnableAsync
@SpringBootApplication
public class SpringStateMachine {
    public static void main(String[] args) {
        SpringApplication.run(SpringStateMachine.class, args);
    }
}

2.2 定义事件类和状态类

事件用于驱动状态转移，状态用于记录事件进度

事件类

package org.example.common;

/**
 * @Author zhx && moon
 * @Since 21
 * @Date 2025-06-18 PM 6:38
 */
public enum OrderEvent {
    PAY,            // 支付操作
    SHIP,           // 发货操作
    CONFIRM,        // 确认收货
    CANCEL          // 取消订单
}

状态类

package org.example.common;

/**
 * @Author zhx && moon
 * @Since 21
 * @Date 2025-06-18 PM 6:37
 */
public enum OrderState {
    UNPAID,         // 待支付
    PAID,           // 已支付
    SHIPPED,        // 已发货
    CONFIRMED,      // 已确认收货
    CANCELLED       // 已取消
}

2.3 Spring 事件监听器

Spring 事件监听器，用于异步处理事件流，当状态机结束时，推送当前状态机到监听器，监听器则从持久化中删除该状态机

package org.example.config;

import org.example.entity.OrderSMContext;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.event.EventListener;
import org.springframework.scheduling.annotation.Async;
import org.springframework.stereotype.Component;

/**
 * @Author zhx && moon
 * @Since 21
 * @Date 2025-06-20 AM 10:18
 */
@Component
public class AsyncEventListener {

    Logger logger = LoggerFactory.getLogger(this.getClass());

    @Autowired
    SMContainer smContainer;

    @Async
    @EventListener
    public void handleAsyncEvent(OrderSMContext context) {
        logger.info("order id {} has delete {}", context.getOrderId(), smContainer.delete(context.getOrderId()));
    }

}

2.4 状态机持久化类

利用 Redis 做状态机的持久化存储

2.4.1 Redis 状态机持久化容器

package org.example.config;

import org.example.common.OrderEvent;
import org.example.common.OrderState;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.data.redis.connection.RedisConnectionFactory;
import org.springframework.data.redis.core.RedisTemplate;
import org.springframework.data.redis.serializer.StringRedisSerializer;
import org.springframework.statemachine.data.redis.RedisStateMachineContextRepository;
import org.springframework.statemachine.persist.RepositoryStateMachinePersist;
import org.springframework.stereotype.Component;

/**
 * @Author zhx && moon
 * @Since 21
 * @Date 2025-06-18 PM 6:54
 */
@Component
public class MYRedisPerSisterConfig {

    @Autowired
    private RedisConnectionFactory factory;

    /**
     * 创建 RedisStateMachineRepository 实例
     */
    @Bean(name = "redisStateMachineContextRepository")
    public MYRedisStateMachinePer<OrderState, OrderEvent> getRedisPerSister() {
        // 创建 RedisStateMachineRepository 实例
        RedisStateMachineContextRepository<OrderState, OrderEvent> repository = new RedisStateMachineContextRepository<>(factory);
        // 持久化
        RepositoryStateMachinePersist perSister = new RepositoryStateMachinePersist(repository);
        // 获取 Redis StateMachinePerSister 实例
        MYRedisStateMachinePer machine = new MYRedisStateMachinePer<>(perSister);
        RedisTemplate<String, byte[]>  redisTemplate = createDefaultTemplate(factory);
        machine.setRedisTemplate(redisTemplate);
        // 返回
        return machine;
    }

    /**
     * 与 RedisStateMachineContextRepository 使用相同的序列化配置
     * @param connectionFactory
     * @return
     */
    private static RedisTemplate<String, byte[]> createDefaultTemplate(RedisConnectionFactory connectionFactory) {
        RedisTemplate<String, byte[]> template = new RedisTemplate();
        template.setKeySerializer(new StringRedisSerializer());
        template.setHashKeySerializer(new StringRedisSerializer());
        template.setConnectionFactory(connectionFactory);
        template.afterPropertiesSet();
        return template;
    }
}

2.4.2 Redis 配置

package org.example.config;

import org.springframework.data.redis.core.RedisTemplate;
import org.springframework.statemachine.StateMachinePersist;
import org.springframework.statemachine.data.redis.RedisStateMachinePersister;

/**
 * @Author zhx && moon
 * @Since 21
 * @Date 2025-06-19 PM 5:21
 */
public class MYRedisStateMachinePer<S, E> extends RedisStateMachinePersister<S, E> {

    RedisTemplate<String, byte[]> redisTemplate;

    public MYRedisStateMachinePer(StateMachinePersist<S, E, String> stateMachinePersist) {
        super(stateMachinePersist);
    }

    public void setRedisTemplate(RedisTemplate<String, byte[]> redisTemplate){
        this.redisTemplate = redisTemplate;
    }

    /**
     * 检查 Redis 中是否存在指定的 key
     * @param key
     * @return
     */
    public boolean isUnExist(String key){
        return !this.redisTemplate.hasKey(key);
    }

    /**
     * 删除 Redis 中指定的 key
     * @param key
     * @return
     */
    public boolean deleteKey(String key){
        return this.redisTemplate.delete(key);
    }

}

2.4.3 状态机监听器

用于监听状态机状态变化

package org.example.config;

import org.example.common.OrderEvent;
import org.example.common.OrderState;
import org.example.entity.OrderSMContext;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.ApplicationEventPublisher;
import org.springframework.messaging.Message;
import org.springframework.statemachine.StateMachine;
import org.springframework.statemachine.listener.StateMachineListenerAdapter;
import org.springframework.statemachine.state.State;
import org.springframework.stereotype.Component;

/**
 * @Author zhx && moon
 * @Since 21
 * @Date 2025-06-19 PM 4:58
 */
@Component
public class RedStateMachineListener extends StateMachineListenerAdapter<OrderState, OrderEvent> {

    Logger logger = LoggerFactory.getLogger(this.getClass());

    @Autowired
    private ApplicationEventPublisher publisher;

    /**
     * 状态变化
     * @param from
     * @param to
     */
    @Override
    public void stateChanged(State<OrderState, OrderEvent> from, State<OrderState, OrderEvent> to) {
        // 状态变更时的处理
        if (null == from) {
            logger.info("state machine init, from Init to {}", to.getId());
        } else {
            logger.info("state machine change, from {} to {}", from.getId(), to.getId());
        }
    }

    /**
     * 状态机启动成功时的回调
     * @param sm
     */
    @Override
    public void stateMachineStarted(StateMachine<OrderState, OrderEvent> sm) {
        logger.info("state machine {} start success.", sm.getId());
    }

    /**
     * 状态机结束的回调
     * @param sm
     */
    @Override
    public void stateMachineStopped(StateMachine<OrderState, OrderEvent> sm) {
        logger.info("state machine {} stop success.", sm.getId());
        publisher.publishEvent(new OrderSMContext(sm.getId()));
    }

    @Override
    public void eventNotAccepted(Message<OrderEvent> event) {
        logger.error("Event not accepted: {}", event.getPayload());
    }

}

2.5 装机器容器

用于管理状态机的创建，本地化缓存与持久化存储

package org.example.config;

import org.example.common.OrderEvent;
import org.example.common.OrderState;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.statemachine.StateMachine;
import org.springframework.statemachine.config.StateMachineFactory;
import org.springframework.stereotype.Component;

import java.util.HashMap;
import java.util.Map;
import java.util.Objects;

/**
 * @Author zhx && moon
 * @Since 21
 * @Date 2025-06-19 PM 4:30
 */
@Component
public class SMContainer {

    Logger logger = LoggerFactory.getLogger(this.getClass());

    @Autowired
    private StateMachineFactory<OrderState, OrderEvent> factory;

    @Autowired
    private MYRedisStateMachinePer<OrderState, OrderEvent> myRedisStateMachinePer;

    private Map<String, StateMachine<OrderState, OrderEvent>> map = new HashMap<>(16);

    /**
     * 获取状态机
     * @param orderId 订单ID
     * @return 状态机实例
     */
    public synchronized StateMachine<OrderState, OrderEvent> getStateMachine(String orderId) {
        String key = getKey(orderId);
        try {
            // 取缓存
            StateMachine<OrderState, OrderEvent> sm = map.get(orderId);
            // 校验
            if (Objects.isNull(sm)) {
                // 获取状态机实例
                sm = factory.getStateMachine(orderId);
                // 校验是否存在
                if (myRedisStateMachinePer.isUnExist(key)) {
                    sm.startReactively().subscribe();
                    myRedisStateMachinePer.persist(sm, key);
                } else {
                    // 恢复状态
                    myRedisStateMachinePer.restore(sm, key);
                }
                // 缓存状态机
                map.put(orderId, sm);
            }
            return sm;
        } catch (Exception e) {
            logger.error("get state machine error: {}", e.getMessage(), e);
            return null;
        }
    }

    /**
     * 保存状态机
     * @param orderId
     * @param stateMachine
     */
    public synchronized boolean save(StateMachine<OrderState, OrderEvent> stateMachine, String orderId){
        try {
            String key = getKey(orderId);
            myRedisStateMachinePer.persist(stateMachine, key);
            return true;
        } catch (Exception e) {
            logger.error("save state machine error: {}", e.getMessage(), e);
            return false;
        }
    }

    /**
     * 删除状态机
     * @param orderId
     * @return
     */
    public synchronized boolean delete(String orderId){
        return myRedisStateMachinePer.deleteKey(getKey(orderId));
    }

    /**
     * 获取 KEY
     * @param orderId
     * @return
     */
    private String getKey(String orderId){
        return "STATE-MACHINE:" +orderId;
    }

}

2.6 状态机事件发送器

用于统一发送状态机事件，管理事件发送过程

package org.example.config;

import org.example.common.OrderEvent;
import org.example.common.OrderState;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.messaging.Message;
import org.springframework.messaging.support.MessageBuilder;
import org.springframework.statemachine.StateMachine;
import org.springframework.statemachine.StateMachineEventResult;
import org.springframework.stereotype.Component;
import reactor.core.publisher.Mono;

import java.util.concurrent.atomic.AtomicBoolean;

/**
 * @Author zhx && moon
 * @Since 21
 * @Date 2025-06-20 PM 2:22
 */
@Component
public class SMEventSender {

    Logger logger = LoggerFactory.getLogger(this.getClass());

    @Autowired
    SMContainer smContainer;

    /**
     * 初始化订单状态机
     * @param orderId
     */
    public void initOrderStateMachine(String orderId) {
        smContainer.getStateMachine(orderId);
    }

    /**
     * 发送事件
     * @param orderId
     * @param event
     * @return
     */
    public boolean send(String orderId, OrderEvent event) {
        // 获取状态
        StateMachine<OrderState, OrderEvent> sm = smContainer.getStateMachine(orderId);
        // 构建事件消息
        Message<OrderEvent> message = MessageBuilder
                .withPayload(event)
                .setHeader("orderId", orderId) // 订单对象关联状态机
                .build();
        // 发送事件
        AtomicBoolean result = new AtomicBoolean(false);
        sm.sendEvent(Mono.just(message)).subscribe(r->{
            if (r.getResultType() == StateMachineEventResult.ResultType.ACCEPTED) {
                // 成功
                result.set(true);
                // 在未完成时持久化
                if (!OrderEvent.CONFIRM.equals(event)) {
                    smContainer.save(sm, orderId);
                }
            } else {
                result.set(false);
            }
        });
        // 输出
        logger.info("send event: {}, orderId: {}, result: {}", event, orderId, result.get());
        // 返回
        return result.get();
    }

}

2.7 状态机配置

状态机配置，定义事件和状态关系，以及守卫和动作

package org.example.config;

import org.example.common.OrderEvent;
import org.example.common.OrderState;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Configuration;
import org.springframework.statemachine.config.EnableStateMachineFactory;
import org.springframework.statemachine.config.StateMachineConfigurerAdapter;
import org.springframework.statemachine.config.builders.StateMachineConfigurationConfigurer;
import org.springframework.statemachine.config.builders.StateMachineStateConfigurer;
import org.springframework.statemachine.config.builders.StateMachineTransitionConfigurer;

import java.util.EnumSet;

/**
 * @Author zhx && moon
 * @Since 21
 * @Date 2025-06-18 PM 6:38
 */
@Configuration
@EnableStateMachineFactory
public class StateMachineConfig extends StateMachineConfigurerAdapter<OrderState, OrderEvent> {

    Logger logger = LoggerFactory.getLogger(this.getClass());

    @Autowired
    RedStateMachineListener listener;

    @Override
    public void configure(StateMachineConfigurationConfigurer<OrderState, OrderEvent> config) throws Exception {
        config.withConfiguration()
                // 注册监听器
                .listener(listener);
    }

    /**
     * 状态机初始化
     * @param states
     * @throws Exception
     */
    @Override
    public void configure(StateMachineStateConfigurer<OrderState, OrderEvent> states) throws Exception {
        states.withStates()
                .initial(OrderState.UNPAID)
                .states(EnumSet.allOf(OrderState.class))
                .end(OrderState.CONFIRMED)
                .end(OrderState.CANCELLED);
    }

    /**
     * 状态转移逻辑
     * @param transitions
     * @throws Exception
     */
    @Override
    public void configure(StateMachineTransitionConfigurer<OrderState, OrderEvent> transitions) throws Exception {
        transitions
                // 支付：UNPAID -> PAID
                .withExternal()
                .source(OrderState.UNPAID)
                .target(OrderState.PAID)
                .guard(context -> {
                    // （前置）守卫条件,校验支付结果
                    logger.info("check order {} pay result ...", context.getMessageHeader("orderId"));
                    return true;
                })
                .action(context -> {
                    // （后置）触发动作,通知仓库备货
                    logger.info("order {} pay success, notify warehouse to prepare goods ...", context.getMessageHeader("orderId"));
                })
                .event(OrderEvent.PAY)
                .and()
                // 发货：PAID -> SHIPPED
                .withExternal()
                .source(OrderState.PAID)
                .target(OrderState.SHIPPED)
                .event(OrderEvent.SHIP)
                .and()
                // 确认收货：SHIPPED -> CONFIRMED
                .withExternal()
                .source(OrderState.SHIPPED)
                .target(OrderState.CONFIRMED)
                .event(OrderEvent.CONFIRM)
                .and()
                // 取消订单（仅在待支付可取消）
                .withExternal()
                .source(OrderState.UNPAID)
                .target(OrderState.CANCELLED)
                .event(OrderEvent.CANCEL);
    }

}

2.8 接口类

用于模拟订单操作

package org.example.controller;

import org.example.service.OrderService;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * @Author zhx && moon
 * @Since 21
 * @Date 2025-06-18 PM 6:41
 */
@RestController
@RequestMapping("/orders")
public class OrderController {

    @Autowired
    private OrderService orderService;

    @GetMapping("/create")
    public String create() {
        return orderService.createOrder();
    }

    @GetMapping("/pay/{orderId}")
    public String pay(@PathVariable("orderId") String orderId) {
        return orderService.payOrder(orderId);
    }

    @GetMapping("/shipped/{orderId}")
    public String shipped(@PathVariable("orderId") String orderId) {
        return orderService.shipped(orderId);
    }

    @GetMapping("/confirm/{orderId}")
    public String confirm(@PathVariable("orderId") String orderId) {
        return orderService.confirm(orderId);
    }

    @GetMapping("/{orderId}/status")
    public String status(@PathVariable String orderId) {
        return "当前状态: " + orderService.getOrderState(orderId);
    }

}

2.9 实现类

package org.example.service;

import org.example.common.OrderEvent;
import org.example.common.OrderState;
import org.example.config.SMEventSender;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;

/**
 * @Author zhx && moon
 * @Since 21
 * @Date 2025-06-18 PM 6:40
 */
@Service
public class OrderService {

    @Autowired
    SMEventSender smEventSender;

    /**
     * 创建订单并初始化状态机
     * @return
     */
    public String createOrder() {
        try {
            // 使用时间戳作为订单ID
            String orderId = String.valueOf(System.currentTimeMillis());
            // 初始化
            smEventSender.initOrderStateMachine(orderId);
            // 返回订单ID
            return orderId;
        } catch (Exception e) {
            return e.getMessage();
        }
    }

    /**
     * 支付
     * @param orderId
     * @return
     */
    public String payOrder(String orderId) {
        try {
            boolean result = smEventSender.send(orderId, OrderEvent.PAY);
            return "success:" + result;
        } catch (Exception e) {
            return e.getMessage();
        }
    }

    /**
     * 发货
     * @param orderId
     * @return
     */
    public String shipped(String orderId) {
        try {
            boolean result = smEventSender.send(orderId, OrderEvent.SHIP);
            return "success:" + result;
        } catch (Exception e) {
            return e.getMessage();
        }
    }

    /**
     * 确认收货
     * @param orderId
     * @return
     */
    public String confirm(String orderId) {
        try {
            boolean result = smEventSender.send(orderId, OrderEvent.CONFIRM);
            return "success:" + result;
        } catch (Exception e) {
            return e.getMessage();
        }
    }

    public OrderState getOrderState(String orderId) {
        return OrderState.UNPAID;
    }
}

2.10 状态机上下文

用于管理状态机信息

package org.example.entity;

import org.example.common.OrderState;

import java.time.LocalDateTime;
import java.util.HashMap;
import java.util.Map;

/**
 * @Author zhx && moon
 * @Since 21
 * @Date 2025-06-18 PM 6:54
 */
public class OrderSMContext {

    public OrderSMContext(String orderId){
        this.orderId = orderId;
    }

    private String orderId;
    private OrderState currentState;
    private Map<String, Object> extendedState = new HashMap<>();
    private LocalDateTime createdAt;
    private LocalDateTime lastModifiedAt;

    public String getOrderId() {
        return orderId;
    }

    public void setOrderId(String orderId) {
        this.orderId = orderId;
    }
}

2.11 配置文件

spring:
  data:
    redis:
      database: 0
      host: 192.168.1.103
      port: 6379
      password: 123456
      timeout: 5000

3.状态机测试

3.1创建订单

3.2持久化结果

初始化时自动将数据持久化到 Redis

3.3 支付订单

3.4 发货

3.5 确认收货

后台日志