[additional] StateMachine 피드백

[wooyounggggg]

설명

최근 팀에 도입 제안하려는 StateMachine 추상 개념을 여러분께도 공유드리고, 피드백을 받아보려 합니다.

StateMachine을 도입하려던 흐름은 아래와 같습니다.

---

• (발단) Domain entity의 state와 비즈니스 로직은 우리의 도메인 정책을 이해하는데 중요한 요소이다.
  • 로직이 동작하면서, entity의 state는 현재 상태에서 다음 상태로 전이된다.
  • 또한 현재 state에 따라, entity에 적용할 수 있는 비즈니스 로직이 달라진다.
• (가정) 따라서 state와 로직간의 관계를 파악하는 것은, 단순히 entity의 상태 전이를 이해하는 개념을 넘어 도메인을 이해하는 비용을 낮추는 역할을 한다.
• 이를 일반화된 수식으로 표현하면 다음과 같다.
  • state(curr) + action(로직) => state(action)
• (구현) 따라서 (curr state, action) => (next state)를 표현할 수 있는 추상화 된 모델이 필요하다.
  • 일관적인 방식으로 상태 전이를 정의할 수 있어야 한다.
  • state와 action의 관계를 한 눈에 파악할 수 있어야 한다.
  • 비즈니스에서 일어나는 모든 개념을 표현할 수 있어야 한다.
• (주의) action은 entity에 대한 action이 아니라, entity의 state에 대한 액션이다.
  • entity의 action으로는 state를 1:1 대응시킬 수 없기 때문이다.
  • 예를 들면, order entity의 action인 pay는 pay_fail, pay_success 상태로 분기될 수 있다.
  • 따라서 order의 action이 아닌, order state에 대한 action이어야 한다.

---

이런 요구사항을 만족시키기 위해, StateMachine이라는 추상 개념을 만들어 팀에 도입을 제안하려는데, 여러분은 어떤 생각을 가지시는지 궁금합니다. comment에 이어서 구현 코드를 작성해두었습니다.

[wooyounggggg]

// 상태 전이 정책을 관리하는 추상 클래스
// - 도메인 객체(T)와 상태(Status), 액션(Action)을 기반으로 동작
// - 상태 전이 가능 여부, 다음 상태, 강제 전이 메서드를 제공

abstract class StateMachine<T, Status, Action> {

    protected abstract val transitionMap: Map<Status, Map<Action, Transition<T, Status>>>
    protected abstract fun extractStatus(entity: T): Status

    // 도메인 객체 기반 (condition 포함)
    fun isAllowed(entity: T, action: Action): Boolean {
        val status = extractStatus(entity)
        val transition = transitionMap[status]?.get(action)
        return transition?.condition?.invoke(entity) ?: false
    }

    fun nextStatus(entity: T, action: Action): Status? {
        val status = extractStatus(entity)
        val transition = transitionMap[status]?.get(action)
        return if (transition != null && transition.condition(entity)) {
            transition.nextStatus
        } else null
    }

    fun ensureTransition(entity: T, action: Action): Status {
        return nextStatus(entity, action)
            ?: throw IllegalStateException("전이 불가: ${extractStatus(entity)} → $action")
    }

    // 순수 status 기반 (condition 무시)
    fun isAllowed(status: Status, action: Action): Boolean {
        return transitionMap[status]?.containsKey(action) ?: false
    }

    fun nextStatus(status: Status, action: Action): Status? {
        return transitionMap[status]?.get(action)?.nextStatus
    }

    fun ensureTransition(status: Status, action: Action): Status {
        return nextStatus(status, action)
            ?: throw IllegalStateException("전이 불가: $status → $action")
    }
}

// 상태 전이 정의 클래스
// - 전이 조건 (condition)
// - 전이 후 상태 (nextStatus)

data class Transition<T, Status>(
    val condition: (T) -> Boolean = { true },
    val nextStatus: Status
) {
    constructor(nextStatus: Status) : this({ true }, nextStatus)
}

[wooyounggggg]

Order Domain 적용 사례

// Order 도메인에 특화된 상태 전이 선언
// - 상태(Status)와 액션(Action)별 전이 정책을 정의

object OrderStateMachine : StateMachine<Order, OrderStatus, OrderAction>() {

    override val transitionMap: Map<OrderStatus, Map<OrderAction, Transition<Order, OrderStatus>>> = mapOf(
        OrderStatus.CREATED to mapOf(
            OrderAction.PAY to Transition(OrderStatus.PAID),
            OrderAction.CANCEL to Transition(OrderStatus.CANCELLED)
        ),
        OrderStatus.PAID to mapOf(
            OrderAction.SHIP to Transition(OrderStatus.SHIPPED),
            OrderAction.CANCEL to Transition(OrderStatus.CANCELLED)
        ),
        OrderStatus.SHIPPED to mapOf(
            OrderAction.DELIVER to Transition(OrderStatus.DELIVERED),
            OrderAction.CANCEL to Transition(
                condition = { !it.isVip }, // vip 별도 정책
                nextStatus = OrderStatus.CANCELLED
            )
        )
    )

    override fun extractStatus(entity: Order): OrderStatus = entity.status
}

// Order 도메인 엔티티
// - 상태를 보유
// - 상태 전이를 수행하는 책임 (transition 메서드)

data class Order(
    val id: Long,
    var status: OrderStatus,
    val isVip: Boolean = false
) {
    fun transition(action: OrderAction) {
        this.status = OrderStateMachine.ensureTransition(this, action)
    }
}

// Order의 상태를 나타내는 enum

enum class OrderStatus {
    CREATED, PAID, SHIPPED, DELIVERED, CANCELLED
}

// Order에 대해 수행할 수 있는 액션을 나타내는 enum

enum class OrderAction {
    PAY, SHIP, DELIVER, CANCEL
}

// Order의 상태 전이를 처리하는 서비스
// - 도메인 기반 transition
// - direct update (currentStatus 기반) transition 지원

@Service
class OrderService(
    private val orderRepository: OrderRepository
) {

    // 도메인 객체를 통한 상태 전이
    fun transitionOrder(orderId: Long, action: OrderAction) {
        val order = orderRepository.findById(orderId)
            .orElseThrow { IllegalArgumentException("주문을 찾을 수 없습니다: $orderId") }

        order.transition(action)
        orderRepository.save(order)
    }

    // status만을 사용한 direct update 방식
    fun transitionOrderDirectly(orderId: Long, currentStatus: OrderStatus, action: OrderAction): Boolean {
        if (!OrderStateMachine.isAllowed(currentStatus, action)) return false

        val nextStatus = OrderStateMachine.nextStatus(currentStatus, action)
            ?: return false

        return orderRepository.updateStatusIfCurrent(orderId, currentStatus, nextStatus)
    }
}

// Order 엔티티용 기본 Repository
// - JpaRepository + 조건부 상태 업데이트 커스텀 인터페이스 포함

interface OrderRepository : JpaRepository<Order, Long>, OrderRepositoryCustom

interface OrderRepositoryCustom {
    fun updateStatusIfCurrent(orderId: Long, currentStatus: OrderStatus, nextStatus: OrderStatus): Boolean
}

[wooyounggggg]

import org.junit.jupiter.api.Test
import org.junit.jupiter.api.assertThrows
import kotlin.test.*

/**
 * OrderStateMachine 상태 전이 테스트
 * - 상태 전이 정책이 정확히 정의된 대로 동작하는지 검증
 */
class OrderStateMachineTest {

    @Test
    /** CREATED 상태에서 PAY 액션을 수행하면 PAID 상태로 전이된다 */
    fun `CREATED 상태에서 결제하면 PAID로 전이된다`() {
        val order = Order(id = 1L, status = OrderStatus.CREATED)

        val next = OrderStateMachine.nextStatus(order, OrderAction.PAY)

        assertEquals(OrderStatus.PAID, next)
    }

    @Test
    /** PAID 상태에서 SHIP 액션을 수행하면 SHIPPED 상태로 전이된다 */
    fun `PAID 상태에서 배송하면 SHIPPED로 전이된다`() {
        val order = Order(id = 2L, status = OrderStatus.PAID)

        val next = OrderStateMachine.ensureTransition(order, OrderAction.SHIP)

        assertEquals(OrderStatus.SHIPPED, next)
    }

    @Test
    /** SHIPPED 상태에서 VIP 사용자는 CANCEL 액션을 수행할 수 없다 */
    fun `SHIPPED 상태에서 VIP는 취소할 수 없다`() {
        val vipOrder = Order(id = 3L, status = OrderStatus.SHIPPED, isVip = true)

        assertFalse(OrderStateMachine.isAllowed(vipOrder, OrderAction.CANCEL))
        assertNull(OrderStateMachine.nextStatus(vipOrder, OrderAction.CANCEL))

        assertThrows<IllegalStateException> {
            OrderStateMachine.ensureTransition(vipOrder, OrderAction.CANCEL)
        }
    }

    @Test
    /** SHIPPED 상태에서 일반 사용자는 CANCEL 액션을 수행할 수 있다 */
    fun `SHIPPED 상태에서 일반 사용자는 취소할 수 있다`() {
        val order = Order(id = 4L, status = OrderStatus.SHIPPED, isVip = false)

        val next = OrderStateMachine.ensureTransition(order, OrderAction.CANCEL)

        assertEquals(OrderStatus.CANCELLED, next)
    }

    @Test
    /** DELIVERED 상태에서는 어떤 액션도 전이되지 않는다 */
    fun `DELIVERED 상태에서는 어떤 액션도 전이되지 않는다`() {
        val order = Order(id = 5L, status = OrderStatus.DELIVERED)

        OrderAction.values().forEach { action ->
            assertFalse(OrderStateMachine.isAllowed(order, action), "Action $action should not be allowed")
            assertNull(OrderStateMachine.nextStatus(order, action), "Action $action should not yield next status")
        }
    }

    @Test
    /** 전이 규칙이 정의되지 않은 상태/액션 조합은 예외를 발생시킨다 */
    fun `ensureTransition은 전이 조건이 맞지 않으면 예외를 던진다`() {
        val order = Order(id = 6L, status = OrderStatus.CREATED)

        assertThrows<IllegalStateException> {
            OrderStateMachine.ensureTransition(order, OrderAction.SHIP) // PAY 없이 SHIP은 불가
        }
    }
}