Java EnumMap 构建订单状态机：状态转移表、非法迁移与默认分支

订单状态一多，最容易失控的不是枚举本身，而是“谁能跳到谁”被拆进了控制器、定时任务和退款回调。把规则集中到 Java 的 EnumMap 后，状态表就是一份可读的流程契约：正常迁移查得到，非法迁移有统一结果，新增状态也能在测试里暴露遗漏。

适合用 EnumMap 做状态机，但不要把它当成“任意状态都能跳”的字典；每个当前状态都要有明确的转移表，并为未知目标保留默认分支。

为什么订单状态适合用 EnumMap 表达

假设订单有 CREATED、PAID、SHIPPED、COMPLETED 和 REFUNDED 五个状态。用多层 if-else 写迁移时，支付回调处理一份，后台补发货又一份，过一阵子就会出现“页面显示已发货，但退款接口仍把它当成已支付”的分叉。

EnumMap 的键必须来自同一个枚举类型，内部按枚举常量组织，遍历顺序也遵循枚举声明顺序。状态机的好处不在于它比普通 HashMap 更神奇，而在于状态集合固定，表结构能直接对应领域模型。

enum OrderState {
    CREATED, PAID, SHIPPED, COMPLETED, REFUNDED
}

record Transition(String event, OrderState next) {}

这里的 OrderState 和 Transition 是正文后续唯一依赖的领域节点。事件名称放在转移值里，既能给日志使用，也能让测试检查“为什么发生了这次迁移”。

先把状态转移表集中起来

状态表可以理解为一张二维映射：第一层键是当前状态，第二层键是目标状态，值是允许这次迁移的事件。这样写的关键是每一行都显式建出来，不依赖调用方自己猜规则。

final class OrderStateMachine {
    private final EnumMap> transitions
        = new EnumMap(OrderState.class);

    OrderStateMachine() {
        allow(OrderState.CREATED, OrderState.PAID, "pay");
        allow(OrderState.PAID, OrderState.SHIPPED, "ship");
        allow(OrderState.SHIPPED, OrderState.COMPLETED, "confirm");
        allow(OrderState.PAID, OrderState.REFUNDED, "refund");
    }

    private void allow(OrderState from, OrderState to, String event) {
        transitions.computeIfAbsent(from,
                ignored -> new EnumMap(OrderState.class))
            .put(to, event);
    }
}

Oracle 的 Java SE 25 API 文档明确说明，EnumMap 面向枚举键，内部表示紧凑，并按枚举常量的自然顺序维护集合视图。这里用 computeIfAbsent 创建当前状态的第二层表，避免初始化一张包含大量空值的矩阵。

这张图对应的关系只有四个正文节点：OrderState、transitions、computeIfAbsent 和 allow。它表达的是“调用 allow 写入状态表”，不是一个泛化的 Java 架构海报。

让 transition 统一处理合法和非法迁移

有了表，业务入口只需要调用一个 transition 方法。它先取当前状态的目标表，再查目标状态；任何一步没有结果，都返回明确的拒绝信息。这里不要用 null 代表所有失败，否则日志无法区分“当前状态没有规则”和“目标状态不允许”。

Optional transition(OrderState from, OrderState to) {
    EnumMap targets = transitions.get(from);
    if (targets == null) {
        return Optional.empty();
    }
    String event = targets.get(to);
    if (event == null) {
        return Optional.empty();
    }
    return Optional.of(new Transition(event, to));
}

调用方可以把空结果转成业务错误，也可以记录当前状态和目标状态。比如 transition(PAID, COMPLETED) 会被拒绝，因为订单必须先经过 SHIPPED；transition(PAID, REFUNDED) 则能得到事件 refund。

图中的 transition、targets、Transition 和 Optional.empty 都能在本节代码中逐字核对。调用链的最后一个节点是拒绝分支，方便排查“为什么支付订单不能直接完成”。

默认分支要保护新增状态

状态机最危险的回归不是编译错误，而是新增了 CANCELLED 后，旧代码默认把它当作普通状态继续处理。可以在构造表时检查每个状态是否有规则，也可以在入口增加显式默认分支，把没有迁移表的状态当作拒绝。

TransitionResult apply(OrderState from, OrderState to) {
    return transition(from, to)
        .map(result -> TransitionResult.allowed(result.event(), result.next()))
        .orElseGet(() -> TransitionResult.rejected(from, to));
}

orElseGet 是这里的安全网：无论是当前状态缺少表，还是目标状态没有事件，最终都会进入 rejected。如果业务要求区分两类原因，可以把 transition 的返回值改成带错误码的结果对象，但不要把默认分支删掉。

用测试锁住状态机的边界

测试不必把每一组枚举排列都写成重复断言，先覆盖领域真正关心的路径即可：

@Test
void paidCanRefundButCannotCompleteDirectly() {
    var machine = new OrderStateMachine();

    assertEquals("refund",
        machine.transition(OrderState.PAID, OrderState.REFUNDED)
            .orElseThrow().event());
    assertTrue(machine.transition(OrderState.PAID, OrderState.COMPLETED).isEmpty());
}

再补一条从 CREATED 到 PAID 的成功路径，以及一个不存在当前规则的状态测试。若以后加入枚举常量，测试应提醒你补充允许关系，而不是让新状态默默拥有权限。

哪些场景不该套 EnumMap 状态机

如果状态来自数据库、可以由租户动态配置，或转移规则本身带复杂条件（例如库存、风控额度和操作者角色同时参与），枚举键就不是完整模型。此时可以保留 OrderState，但把规则下沉到数据库或策略对象，并让状态机只负责调用和记录结果。

另外，EnumMap 不是线程安全容器。状态表如果在启动后不再修改，可以在构造阶段完成后只读使用；如果确实要热更新，应在替换整张不可变快照时处理并发，而不是让多个线程直接写同一张 transitions。

相关问题

EnumMap 能不能直接替代 HashMap？

键是固定枚举时可以优先考虑它；键来自用户输入或配置时，HashMap 更自然，也不需要为了使用 EnumMap 强行把动态值改成枚举。

为什么不直接用 switch 写状态迁移？

少量状态、规则不会增长时 switch 很直观；当迁移关系持续增加，集中表更容易审查、遍历和做数据驱动测试。

状态表需要放进数据库吗？

固定业务规则通常不需要。只有规则需要运营配置、租户隔离或不发版调整时，才值得持久化，并保留版本与回滚信息。

最后的检查清单

• 每个允许迁移是否都通过 allow 写入了 transitions？
• transition 是否同时处理了缺少当前状态和缺少目标状态？
• 非法迁移是否能留下 from、to 和事件上下文？
• 新增枚举状态时，测试是否会迫使你补充规则？