Mastering Order State Management with Spring State Machine

In many real projects we encounter state‑change problems across multiple processes, such as order status transitions. When an event is triggered, the order state changes. To manage these event‑driven state changes with high extensibility, we can use Spring State Machine.

1. Understanding Spring State Machine

Spring State Machine, a module of the Spring Framework, provides an implementation of a finite state machine that describes a system’s transitions between states and the events that trigger those transitions. It offers a clear way to define states and transitions and handles event‑driven state migrations.

2. Practical Implementation of Order Status Changes

(1) Add Maven Dependencies

<code>&lt;dependencies&gt;
    &lt;dependency&gt;
        &lt;groupId&gt;org.springframework.boot&lt;/groupId&gt;
        &lt;artifactId&gt;spring-boot-starter-web&lt;/artifactId&gt;
    &lt;/dependency&gt;
    &lt;dependency&gt;
        &lt;groupId&gt;org.springframework.statemachine&lt;/groupId&gt;
        &lt;artifactId&gt;spring-statemachine-starter&lt;/artifactId&gt;
        &lt;version&gt;2.2.0.RELEASE&lt;/version&gt;
    &lt;/dependency&gt;
    &lt;dependency&gt;
        &lt;groupId&gt;org.springframework.boot&lt;/groupId&gt;
        &lt;artifactId&gt;spring-boot-starter-test&lt;/artifactId&gt;
        &lt;scope&gt;test&lt;/scope&gt;
        &lt;exclusions&gt;
            &lt;exclusion&gt;
                &lt;groupId&gt;org.junit.vintage&lt;/groupId&gt;
                &lt;artifactId&gt;junit-vintage-engine&lt;/artifactId&gt;
            &lt;/exclusion&gt;
        &lt;/exclusions&gt;
    &lt;/dependency&gt;
&lt;/dependencies&gt;</code>

(2) Define Order States

<code>public enum OrderStatusEnum {
    WAIT_PAY(1,"待支付"),
    WAIT_DELIVER_GOODS(3, "待发货"),
    WAIT_RECEIVE_GOODS(5,"待收货"),
    TRANSACTION_SUCCESS(7, "交易完成"),
    ;
    private Integer status;
    private String desc;

    OrderStatusEnum(Integer status, String desc) {
        this.status = status;
        this.desc = desc;
    }

    public Integer getStatus() { return status; }
    public String getDesc() { return desc; }
}</code>

(3) Define Order Events

<code>public enum OrderEventEnum {
    USER_PAY("用户支付"),
    WAREHOUSE_DELIVER_GOODS("仓库发货"),
    USER_RECEIVE_GOODS("用户收货"),
    ;
    private String desc;

    OrderEventEnum(String desc) { this.desc = desc; }
    public String getDesc() { return desc; }
}</code>

(4) Configure State‑Event Relationships

<code>@Configuration
@EnableStateMachine(name = "springStateMachineConfig")
public class SpringStateMachineConfig extends EnumStateMachineConfigurerAdapter&lt;OrderStatusEnum, OrderEventEnum&gt; {

    @Override
    public void configure(StateMachineStateConfigurer&lt;OrderStatusEnum, OrderEventEnum&gt; state) throws Exception {
        state.withStates()
                .initial(OrderStatusEnum.WAIT_PAY)
                .states(Stream.of(OrderStatusEnum.values()).collect(Collectors.toSet()));
    }

    @Override
    public void configure(StateMachineTransitionConfigurer&lt;OrderStatusEnum, OrderEventEnum&gt; transitions) throws Exception {
        transitions
                .withExternal()
                .source(OrderStatusEnum.WAIT_PAY).target(OrderStatusEnum.WAIT_DELIVER_GOODS)
                .event(OrderEventEnum.USER_PAY)
                .and()
                .withExternal()
                .source(OrderStatusEnum.WAIT_DELIVER_GOODS).target(OrderStatusEnum.WAIT_RECEIVE_GOODS)
                .event(OrderEventEnum.WAREHOUSE_DELIVER_GOODS)
                .and()
                .withExternal()
                .source(OrderStatusEnum.WAIT_RECEIVE_GOODS).target(OrderStatusEnum.TRANSACTION_SUCCESS)
                .event(OrderEventEnum.USER_RECEIVE_GOODS);
    }
}</code>

(5) Listen to Specific Events

<code>@Component
@WithStateMachine(name = "springStateMachineConfig")
public class SpringStateMachineEventListener {

    @OnTransition(target="WAIT_PAY")
    public boolean create(Message&lt;OrderEntity&gt; order) {
        System.out.println("订单创建，待支付");
        return true;
    }

    @OnTransition(source = "WAIT_PAY", target="WAIT_DELIVER_GOODS")
    public boolean userPay(Message&lt;OrderEntity&gt; order) {
        System.out.println("用户支付");
        return true;
    }

    @OnTransition(source = "WAIT_DELIVER_GOODS", target="WAIT_RECEIVE_GOODS")
    public boolean warehourseDeliver(Message&lt;OrderEntity&gt; order) {
        System.out.println("仓库发货");
        return true;
    }

    @OnTransition(source = "WAIT_RECEIVE_GOODS", target="TRANSACTION_SUCCESS")
    public boolean userReceive(Message&lt;OrderEntity&gt; order) {
        System.out.println("用户收货");
        return true;
    }
}</code>

With these core pieces—state definitions, event definitions, configuration of their relationships, and listeners—we have a complete, extensible workflow for order status management. Spring State Machine also offers additional features such as actions and guards for more complex scenarios.

Summary: In workflow‑like business scenarios (e.g., order processing), binding states to events via Spring State Machine enables clean, event‑driven state transitions. Other mature state‑machine solutions (e.g., Cola) exist, and adding new states like order cancellation simply requires defining the new state, event, and listener.