Class StatusTransition

java.lang.Object
io.leandev.appfuse.entity.StatusTransition
public final class StatusTransition extends Object

狀態流轉工具類

提供狀態流轉驗證的靜態方法，協助 Service 層驗證狀態變更是否合法。

設計原則：

  • 框架只提供驗證工具，不定義狀態流轉規則
  • 狀態流轉規則由應用層的 Status 列舉定義
  • 驗證失敗時拋出 ConflictException（HTTP 409）

Status 列舉建議實作：

public enum OrderStatus {
    PENDING("待處理"),
    CONFIRMED("已確認"),
    COMPLETED("已完成"),
    CANCELLED("已取消");

    private final String label;

    // 狀態流轉規則
    private static final Map<OrderStatus, List<OrderStatus>> TRANSITIONS = Map.of(
        PENDING, List.of(CONFIRMED, CANCELLED),
        CONFIRMED, List.of(COMPLETED, CANCELLED),
        COMPLETED, List.of(),
        CANCELLED, List.of()
    );

    public boolean canTransitionTo(OrderStatus target) {
        List<OrderStatus> allowed = TRANSITIONS.get(this);
        return allowed != null && allowed.contains(target);
    }

    public List<OrderStatus> getAllowedTransitions() {
        return TRANSITIONS.getOrDefault(this, List.of());
    }

    public boolean isTerminal() {
        return this == COMPLETED || this == CANCELLED;
    }
}

Service 層使用範例：

public Order updateStatus(String id, OrderStatus newStatus) {
    Order order = repository.findById(id).orElseThrow(...);

    // 方式 1：使用方法參考
    StatusTransition.validate(
        order.getStatus(),
        newStatus,
        OrderStatus::canTransitionTo,
        "Order"
    );

    // 方式 2：使用 getAllowedTransitions
    StatusTransition.validate(
        order.getStatus(),
        newStatus,
        OrderStatus::getAllowedTransitions,
        "Order"
    );

    order.setStatus(newStatus);
    return repository.save(order);
}
See Also:

  • Method Details

    • validate

      public static <S extends Enum<S>> void validate(S from, S to, BiPredicate<S,S> canTransition, String entityType)

      驗證狀態流轉是否合法

      使用 canTransition 函數驗證，如驗證失敗拋出 ConflictException。

      Type Parameters:
      S - 狀態列舉型別
      Parameters:
      from - 來源狀態
      to - 目標狀態
      canTransition - 驗證函數，接收 (from, to) 返回是否允許
      entityType - 實體類型名稱（用於錯誤訊息）
      Throws:
      ConflictException - 如果狀態流轉不合法

    • validate

      public static <S extends Enum<S>> void validate(S from, S to, Function<S,List<S>> getAllowedTransitions, String entityType)

      驗證狀態流轉是否合法（使用允許列表）

      使用 getAllowedTransitions 函數取得允許的目標狀態列表， 檢查目標狀態是否在列表中。

      Type Parameters:
      S - 狀態列舉型別
      Parameters:
      from - 來源狀態
      to - 目標狀態
      getAllowedTransitions - 取得允許轉換列表的函數
      entityType - 實體類型名稱（用於錯誤訊息）
      Throws:
      ConflictException - 如果狀態流轉不合法

    • canTransition

      public static <S extends Enum<S>> boolean canTransition(S from, S to, BiPredicate<S,S> canTransition)
      檢查狀態流轉是否合法（不拋出例外）
      Type Parameters:
      S - 狀態列舉型別
      Parameters:
      from - 來源狀態
      to - 目標狀態
      canTransition - 驗證函數
      Returns:
      true 如果流轉合法

    • canTransition

      public static <S extends Enum<S>> boolean canTransition(S from, S to, Function<S,List<S>> getAllowedTransitions)
      檢查狀態流轉是否合法（使用允許列表，不拋出例外）
      Type Parameters:
      S - 狀態列舉型別
      Parameters:
      from - 來源狀態
      to - 目標狀態
      getAllowedTransitions - 取得允許轉換列表的函數
      Returns:
      true 如果流轉合法