枚举概述
- 业务用途：用于电商订单全链路的状态管理，驱动前端提示、仓配协同与事件消息发送，并兼顾异常重试、对账统计与幂等处理。
- 设计思路：
- 以稳定的字符串状态码进行唯一标识（ORDER_前缀），避免依赖 ordinal，确保序列化与日志只输出 code，便于跨系统对账与消息解耦。
- 提供 isTerminal、canRefund、nextStates 等方法，支持状态判定、可退款校验与合规迁移控制。
- 允许自状态迁移（自环）以支持异常重试与幂等（同一事件重复处理不导致非法迁移）。
- 预留 UNKNOWN 以便当存在未识别的新增状态码时能够向后兼容（反序列化到 UNKNOWN 而不抛错）；新增过渡状态只需扩展静态迁移表与消息映射即可。
- 提供 reportKey 与 messageTopic 映射，确保与报表和消息主题的一致性。
枚举定义
package com.example.order;
import java.util.Collections;
import java.util.EnumMap;
import java.util.EnumSet;
import java.util.Map;
import java.util.Objects;
import java.util.Set;
// 如使用 Jackson 做 JSON 序列化/反序列化，可启用以下注解。
// 非 Jackson 环境可忽略或替换为自定义序列化策略。
// import com.fasterxml.jackson.annotation.JsonCreator;
// import com.fasterxml.jackson.annotation.JsonEnumDefaultValue;
// import com.fasterxml.jackson.annotation.JsonValue;
/**
* 订单状态（全链路）
* - 使用字符串 code（ORDER_ 前缀）作为稳定标识以便序列化、日志与跨系统对账。
* - 禁止依赖 ordinal；toString 与 JSON 序列化仅输出 code。
* - nextStates 包含自环（自身）以支持异常重试/幂等。
* - UNKNOWN 用于向后兼容未来新增状态码。
*/
public enum OrderStatus {
/**
* 未知状态（向后兼容占位）
* 解析到未识别的 code 时使用本状态，正常流程不应设置为 UNKNOWN。
*/
// @JsonEnumDefaultValue
UNKNOWN(
"ORDER_UNKNOWN",
"未知状态",
"unknown",
"order.status.unknown",
false,
false
),
/**
* 已创建：下单成功，等待支付
*/
CREATED(
"ORDER_CREATED",
"已创建",
"created",
"order.status.created",
false,
false
),
/**
* 待支付：已发起支付等待结果
*/
PENDING_PAYMENT(
"ORDER_PENDING_PAYMENT",
"待支付",
"pending_payment",
"order.status.pending_payment",
false,
false
),
/**
* 已支付：待仓配拣货
*/
PAID(
"ORDER_PAID",
"已支付",
"paid",
"order.status.paid",
false,
true // 已支付允许发起退款
),
/**
* 拣货中：仓内处理
*/
PICKING(
"ORDER_PICKING",
"拣货中",
"picking",
"order.status.picking",
false,
true // 支持退款（拣货未出库）
),
/**
* 已出库/已发货
*/
SHIPPED(
"ORDER_SHIPPED",
"已发货",
"shipped",
"order.status.shipped",
false,
true // 支持拦截退款/拒收退款策略（由业务网关控制）
),
/**
* 已签收/已送达（交易完成）
*/
DELIVERED(
"ORDER_DELIVERED",
"已签收",
"delivered",
"order.status.delivered",
true, // 终态
false // 默认不支持退款（售后另行处理，不纳入此主流程）
),
/**
* 已取消（未履约完成即终止）
*/
CANCELED(
"ORDER_CANCELED",
"已取消",
"canceled",
"order.status.canceled",
true, // 终态
false
),
/**
* 已退款（全额或最终退款）
*/
REFUNDED(
"ORDER_REFUNDED",
"已退款",
"refunded",
"order.status.refunded",
true, // 终态
false
);
// code 为唯一外部标识，序列化与日志仅输出此字段
private final String code;
// 面向用户/前端的文案
private final String label;
// 报表聚合使用的稳定 key（与数仓/指标对齐）
private final String reportKey;
// 消息主题（topic 或路由键），用于状态事件推送
private final String messageTopic;
// 是否为终态
private final boolean terminal;
// 是否可退款（在本状态下是否允许发起退款流程）
private final boolean refundable;
OrderStatus(String code,
String label,
String reportKey,
String messageTopic,
boolean terminal,
boolean refundable) {
this.code = code;
this.label = label;
this.reportKey = reportKey;
this.messageTopic = messageTopic;
this.terminal = terminal;
this.refundable = refundable;
}
// Jackson 序列化时仅输出 code；非 Jackson 环境可使用自定义序列化器
// @JsonValue
public String getCode() {
return code;
}
public String getLabel() {
return label;
}
public String getReportKey() {
return reportKey;
}
public String getMessageTopic() {
return messageTopic;
}
public boolean isTerminal() {
return terminal;
}
public boolean canRefund() {
return refundable;
}
/**
* 允许的迁移集合（包含自环，用于异常重试/幂等）。
* 例如：PENDING_PAYMENT -> {PENDING_PAYMENT, PAID, CANCELED}
*/
public Set<OrderStatus> nextStates() {
Set<OrderStatus> set = TRANSITIONS.get(this);
return set != null ? set : Collections.singleton(this);
}
/**
* 是否允许从当前状态迁移到目标状态。
* 迁移合法包括自环（幂等处理）。
*/
public boolean canTransitionTo(OrderStatus target) {
if (target == null) return false;
return nextStates().contains(target);
}
/**
* 基于 code 的解析（向后兼容：未知 code 映射为 UNKNOWN）。
*/
// @JsonCreator
public static OrderStatus fromCode(String code) {
if (code == null || code.isEmpty()) return UNKNOWN;
OrderStatus s = BY_CODE.get(code);
return s != null ? s : UNKNOWN;
}
/**
* 静态工具：检查 from -> to 是否允许。
*/
public static boolean canTransition(OrderStatus from, OrderStatus to) {
return from != null && from.canTransitionTo(to);
}
/**
* toString 仅输出 code，便于统一日志/审计。
*/
@Override
public String toString() {
return code;
}
// ---- 内部映射：code -> enum，用于高效解析 ----
private static final Map<String, OrderStatus> BY_CODE;
static {
EnumMap<OrderStatus, String> tmp = new EnumMap<>(OrderStatus.class);
for (OrderStatus s : OrderStatus.values()) {
tmp.put(s, s.code);
}
Map<String, OrderStatus> map = new java.util.HashMap<>();
for (Map.Entry<OrderStatus, String> e : tmp.entrySet()) {
String c = e.getValue();
if (map.put(c, e.getKey()) != null) {
throw new IllegalStateException("Duplicate order status code: " + c);
}
}
BY_CODE = Collections.unmodifiableMap(map);
}
// ---- 迁移关系：包含自环（幂等） ----
private static final EnumMap<OrderStatus, Set<OrderStatus>> TRANSITIONS = new EnumMap<>(OrderStatus.class);
static {
// 辅助：生成不可变集合
java.util.function.Function<OrderStatus[], Set<OrderStatus>> setOf =
(arr) -> Collections.unmodifiableSet(EnumSet.of(arr[0], arr));
// 说明：每个集合都包含自环（第一个参数即 from）
put(CREATED,
CREATED, PENDING_PAYMENT, CANCELED);
put(PENDING_PAYMENT,
PENDING_PAYMENT, PAID, CANCELED);
put(PAID,
PAID, PICKING, CANCELED, REFUNDED);
put(PICKING,
PICKING, SHIPPED, CANCELED, REFUNDED);
put(SHIPPED,
SHIPPED, DELIVERED, REFUNDED);
put(DELIVERED,
DELIVERED /* 终态，自环仅为幂等等价重复上报 */);
put(CANCELED,
CANCELED /* 终态 */);
put(REFUNDED,
REFUNDED /* 终态 */);
put(UNKNOWN,
UNKNOWN /* 不建议使用，作为占位 */);
}
private static void put(OrderStatus from, OrderStatus... allows) {
// 构造包含自环的集合（确保 allows 已包含 from；若未包含则自动加入）
EnumSet<OrderStatus> set = EnumSet.noneOf(OrderStatus.class);
if (allows == null || allows.length == 0) {
set.add(from);
} else {
Collections.addAll(set, allows);
set.add(from);
}
TRANSITIONS.put(from, Collections.unmodifiableSet(set));
}
}
使用示例
import com.example.order.OrderStatus;
import java.util.Set;
public class OrderStatusDemo {
// 事件到达时的状态迁移校验（包含幂等自环）
public static boolean tryTransition(String orderId, OrderStatus current, OrderStatus target) {
if (!OrderStatus.canTransition(current, target)) {
// 非法迁移，记录并拒绝
System.out.printf("Reject transition %s -> %s for order %s%n", current, target, orderId);
return false;
}
// 持久化 target 状态（若 target == current 则为幂等重试）
System.out.printf("Apply transition %s -> %s for order %s%n", current, target, orderId);
// persist(orderId, target.getCode());
// 发送状态事件（使用 messageTopic 与 code）
// messageBus.publish(target.getMessageTopic(), Map.of("orderId", orderId, "status", target.getCode()));
return true;
}
// 前端提示 / 文案展示
public static String prompt(OrderStatus status) {
switch (status) {
case CREATED:
return "订单已创建，请尽快支付";
case PENDING_PAYMENT:
return "支付处理中，请稍候";
case PAID:
return "支付成功，等待拣货";
case PICKING:
return "仓库拣货中，请耐心等待";
case SHIPPED:
return "包裹已发出，注意查收";
case DELIVERED:
return "包裹已签收，感谢您的购买";
case CANCELED:
return "订单已取消";
case REFUNDED:
return "已完成退款";
case UNKNOWN:
default:
return "状态更新中";
}
}
// 对账与报表统计：聚合 reportKey
public static void report(OrderStatus status) {
String key = status.getReportKey(); // 如 "shipped"
// metrics.counter("order_status", "key", key).increment();
System.out.printf("Report increment for key=%s%n", key);
}
public static void main(String[] args) {
OrderStatus cur = OrderStatus.fromCode("ORDER_PAID");
Set<OrderStatus> next = cur.nextStates();
System.out.println("Next allows from PAID: " + next); // 输出 code 集合（toString 即 code）
// 示例迁移：PAID -> PICKING
tryTransition("O202501010001", cur, OrderStatus.PICKING);
// 幂等重试：PICKING -> PICKING
tryTransition("O202501010001", OrderStatus.PICKING, OrderStatus.PICKING);
// 非法迁移：PENDING_PAYMENT -> DELIVERED
tryTransition("O202501010002", OrderStatus.PENDING_PAYMENT, OrderStatus.DELIVERED);
// 报表统计
report(OrderStatus.SHIPPED);
// 前端提示
System.out.println(prompt(OrderStatus.SHIPPED));
// 序列化（示意）：status.getCode() 或 Jackson @JsonValue
System.out.println("Serialize: " + OrderStatus.SHIPPED.getCode()); // "ORDER_SHIPPED"
}
}
注意事项
- 稳定性与兼容性
- 仅以 code 作为外部标识进行序列化与日志输出；禁止依赖 ordinal 或 name。
- 如使用 Jackson，建议启用 @JsonValue 与 @JsonCreator，并保留 UNKNOWN（或使用 @JsonEnumDefaultValue）以兼容未来新增状态码。
- 新增状态或过渡时：
- 新增一个唯一 code（以 ORDER_ 前缀）；
- 补充 label、reportKey、messageTopic；
- 在静态 TRANSITIONS 中维护合法迁移（务必包含自环）。
- 幂等与重试
- nextStates 默认包含自环，支持重复消息/重复回调的安全处理。
- canTransition/canTransitionTo 用于网关/服务间的保护，避免越级或逆向迁移。
- 退款标记
- canRefund 仅作为状态维度的可退款指示，具体业务规则（如部分退款、拦截退款、售后等）应在领域服务内进一步校验（支付渠道、物流节点等）。
- 报表与消息
- reportKey 与 messageTopic 与数据仓库指标、消息中台主题保持一致性；如需变更请以兼容方式做别名映射。
- 代码规范
- 确保 BY_CODE 无重复（枚举已在静态块校验）。
- 避免在 switch 中遗漏 UNKNOWN 分支，防止未来新增状态导致的默认行为不当。
- 单元测试覆盖：fromCode 解析、迁移矩阵合法性（不可从终态迁出，除自环）、退款标记与前端提示一致性。
