Spring StateMachine in Production: Modeling, Redis Persistence & High-Concurrency Anti-Duplication Patterns

1. State, Event, Transition & Guard: Align with Business Semantics

Spring StateMachine centers on four abstractions mapped directly to business concepts:

State : Stable phases of an entity (e.g., CREATED, PAID, SHIPPING). Use enum to avoid string magic values.

Event : Signals that drive transitions — user actions ( PAY_SUCCESS, CANCEL) or system signals ( TIMEOUT, STOCK_PRE_OCCUPY_FAIL).

Transition : Defines "from state X, on event Y, go to state Z." This is the skeleton, kept in configuration, not business code.

Guard : Pre-transition checks (inventory, amount, permissions). Returns true to proceed, false to block with a clear error code.

Configuration and actions are separated: configuration defines the graph; actions (Entry/Exit/Action) are delegated to Spring beans.

@Configuration
@EnableStateMachineFactory
public class OrderStateMachineConfig extends StateMachineConfigurerAdapter<OrderStatus, OrderEvent> {

    @Override
    public void configure(StateMachineStateConfigurer<OrderStatus, OrderEvent> states) throws Exception {
        states.withStates()
            .initial(OrderStatus.CREATED)
            .state(OrderStatus.PAID, entryOrderPaidAction(), exitOrderPaidAction())
            .state(OrderStatus.COMPLETED)
            .state(OrderStatus.CLOSED);
    }

    @Override
    public void configure(StateMachineTransitionConfigurer<OrderStatus, OrderEvent> transitions) throws Exception {
        transitions
            .withExternal()
                .source(OrderStatus.CREATED).target(OrderStatus.PAID).event(OrderEvent.PAY_SUCCESS)
                .guard(paymentAmountGuard())
                .action(executePaymentPostAction())
            .and()
            .withExternal()
                .source(OrderStatus.PAID).target(OrderStatus.COMPLETED).event(OrderEvent.CONFIRM_RECEIVE)
                .guard(receiveGuard());
    }
}

Practical habits:

Guards should be pure validation functions — no DB writes or MQ sends.

Actions are the real execution points; offload external RPCs or long tasks to async thread pools or MQ to avoid blocking the state machine thread.

Entry/Exit hooks suit audit logs, extension-field updates, and state-change notifications.

2. Production-Grade Persistence & Anti-Duplication

Persistence: Why We Switched Entirely to Redis

Early attempts used JPA to serialize StateMachineContext into MySQL — safe for long-lived flows (e.g., credit contracts). Under flash-sale traffic, frequent deserialization + transaction commits saturated the DB connection pool. Moving to Redis (storing JSON snapshots in HASH or String) brought read/write latency to sub-millisecond, and TTL auto-expires cold data, cutting ops overhead.

@Component
public class RedisStateMachinePersist implements StateMachinePersist<OrderStatus, OrderEvent, String> {

    private final StringRedisTemplate redisTemplate;
    private final ObjectMapper mapper;

    public RedisStateMachinePersist(StringRedisTemplate redisTemplate, ObjectMapper mapper) {
        this.redisTemplate = redisTemplate;
        this.mapper = mapper;
    }

    @Override
    public void write(StateMachineContext<OrderStatus, OrderEvent> context, String bizId) {
        String key = "sm:order:" + bizId;
        try {
            redisTemplate.opsForValue().set(key, mapper.writeValueAsString(context));
            redisTemplate.expire(key, 3, TimeUnit.DAYS);
        } catch (Exception e) {
            throw new RuntimeException("状态机持久化失败", e);
        }
    }

    @Override
    public StateMachineContext<OrderStatus, OrderEvent> read(String bizId) {
        String json = redisTemplate.opsForValue().get("sm:order:" + bizId);
        return StringUtils.hasText(json) ? mapper.readValue(json, new TypeReference<>() {}) : null;
    }
}

Anti-Concurrency Tampering: Distributed Lock + Optimistic Lock + Event Idempotency

StateMachine.sendEvent()

is not thread-safe. In a cluster, the same order can be hit simultaneously by a payment callback and a timeout job. The battle-tested chain:

Fine-grained distributed lock : Redisson lock keyed by bizId, short timeout (3–5 s), fast-fail on contention.

Database optimistic lock : Main table carries a version field. Before restoring the state machine, read the version; on persist,

update set version = version + 1 where id = ? and version = ?

to prevent lost updates.

Event-level idempotency : Upstream sends a unique eventId (snowflake/UUID). SETNX eventId 1 EX 86400 blocks duplicate delivery; retain eventId after successful processing.

Encapsulated invocation template:

public Result sendEventSafely(String bizId, OrderEvent event, String eventId) {
    RLock lock = redissonClient.getLock("lock:order:sm:" + bizId);
    try {
        if (!lock.tryLock(3, 5, TimeUnit.SECONDS)) {
            return Result.fail("BUSY", "请求处理中，请勿重复提交");
        }

        // 1. Idempotency gate
        if (Boolean.FALSE.equals(idempotentService.tryLock(eventId, 24))) {
            return Result.ok("ALREADY_PROCESSED");
        }

        // 2. Fetch latest state & version check
        OrderEntity order = orderMapper.selectForUpdate(bizId);
        StateMachine<OrderStatus, OrderEvent> sm = smFactory.getStateMachine(bizId);
        persister.restore(sm, bizId);

        // 3. Drive transition
        Message<OrderEvent> msg = MessageBuilder.withPayload(event).build();
        boolean accepted = sm.sendEvent(msg);
        if (!accepted) {
            return Result.fail("REJECT", "状态守卫拦截或事件非法");
        }

        // 4. Persist & release idempotency
        persister.persist(sm, bizId);
        orderMapper.updateStateVersion(bizId, sm.getState().getId(), order.getVersion());
        idempotentService.release(eventId); // keep on success

        return Result.ok(sm.getState().getId());
    } catch (Exception e) {
        // On exception, retain eventId for retry investigation; do not blindly clean up
        log.error("状态机流转异常, bizId={}, event={}", bizId, event, e);
        return Result.fail("SYS_ERR", "系统内部异常");
    } finally {
        if (lock.isHeldByCurrentThread()) lock.unlock();
    }
}

This bundles concurrency control, state restore, business execution, and version update under one lock. In production it has eliminated "ghost states." Note: if Action is async, sendEvent() returns immediately — move persistence into the async thread or event listener, preserving order.

3. Async Decoupling, Timeout Auto-Close & Exception Compensation

The state machine handles routing, not execution. When Action calls external systems or heavy computation, synchronous blocking kills throughput.

Async decoupling : Either configure a custom TaskExecutor to run actions in a thread pool, or have the state machine only decide and emit an OrderStatusChangeEvent to Kafka/RabbitMQ; consumers rebuild context and run heavy logic. The latter decouples more cleanly but requires you to guarantee eventual consistency.

Timeout auto-transition : Avoid the built-in

Timer</sub> events — they work on a single node but drift in clusters. Use MQ delayed messages (RocketMQ delay levels or RabbitMQ delay plugin) or Redis <code>ZSET

as a delay queue. On expiry, push a TIMEOUT event; the guard checks if the state is still CREATED — if yes, close the order; otherwise discard.

Exception compensation & dead-letter safety net : The state machine does not own transactions. If an Action fails mid-way (e.g., payment succeeded but warehouse system is down), rolling back the state machine often causes more chaos. Standard fallback:

Transition to compensation state : Emit a COMPENSATE_EVENT; guard routes to COMPENSATING state to run reverse logic (freeze funds, release inventory).

Local message table / Outbox : At critical nodes, write to a local message table first, then async-publish to MQ. A scheduled job scans and retries, ensuring downstream eventually receives the message.

Dead-letter queue (DLQ) + exponential backoff : Unrecoverable exceptions go to DLQ with retry schedule 1s→2s→4s→16s→…→5min. Retry path must include idempotency checks, or retries amplify the damage.

4. Selection Guide & Pitfall Summary

When to adopt Spring StateMachine : 5+ states, crossing transition paths, reverse and parallel branches. Also valuable when product/QA need a visual flow graph or compliance demands a full audit trail — declarative configuration saves massive communication overhead. With distributed locks and persistence, it holds up under high concurrency.

When to avoid : Only 2–3 states (e.g., draft/published/deleted) — Enum + strategy pattern suffices; state machine is overkill. Heavy human approval, multi-level sign-off, dynamic branching — use Camunda/Flowable (BPMN engines); state machines cannot model human tasks or long-running orchestration. Also, Spring StateMachine relies on reflection and heavy bean assembly — cold start is slow. Warm up StateMachineFactory at startup, not on first request.

Comparison with alternatives

Pure Java Enum + if: fastest, but maintenance cost explodes with state count. Apache Commons SCXML: standards-based, but verbose config and essentially unmaintained. Squirrel Foundation: good performance, lightweight, but detached from Spring ecosystem — persistence and async need custom wrappers. Spring StateMachine: steeper learning curve, heavier API, but best integration with Spring stack, highly pluggable. Camunda/Flowable: fit for long BPMN processes, resource-heavy; don't force-fit lightweight business.

Choose based on project scale and team stack.

Key pitfalls

State is the result, event is the cause. Never bypass the machine with order.setStatus(). All state changes must go through sendEvent.

Lock granularity must be fine. A global lock is catastrophic during peak; insist on bizId -level locking with short timeout and fast-fail.

Logs must carry context. Every transition logs structured fields: TraceID, BizID, FromState, ToState, Event, GuardResult. Hook into APM — cuts debugging time in half.

Never put business logic in Guard. Guards are read-only; writes belong in Action or Service. Seen cases where coupon issuance lived in a guard — guard failed, coupon not sent, but state changed, causing reconciliation nightmares.

State machines are no silver bullet; they simply converge complex business flows into a verifiable deterministic model. Draw clear boundaries, harden persistence, close the anti-duplication loop — and the system climbs out of the "state quagmire" into a clean pipeline.