《互联网产品的服务端架构·交易、增长与平台化》2.2 订单状态机与超时关闭

// file: internal/order/state.go
// tier: L1
// verify: go test ./internal/order/

package order

import "fmt"

// State 是订单状态。
type State string

const (
	StateCreated   State = "created"
	StatePaid      State = "paid"
	StateFulfilled State = "fulfilled"
	StateClosed    State = "closed"
	StateRefunded  State = "refunded"
)

// Event 是驱动状态变化的外部事件。
type Event string

const (
	EventPay     Event = "pay"
	EventFulfill Event = "fulfill"
	EventClose   Event = "close"
	EventRefund  Event = "refund"
)

// Next 计算状态机在给定事件后的新状态。
//
// 允许的迁移：
//
//	created   --pay-->     paid
//	created   --close-->   closed
//	paid      --fulfill--> fulfilled
//	paid      --refund-->  refunded
//	fulfilled --refund-->  refunded
//
// closed 和 refunded 是终态，拒绝任何事件。未知状态、未知事件和非法迁移
// 都返回错误，而不是返回原状态让调用方误以为成功。
func Next(s State, e Event) (State, error) {
	if !knownEvent(e) {
		return "", fmt.Errorf("order: unknown event %q", e)
	}
	switch s {
	case StateCreated:
		switch e {
		case EventPay:
			return StatePaid, nil
		case EventClose:
			return StateClosed, nil
		}
	case StatePaid:
		switch e {
		case EventFulfill:
			return StateFulfilled, nil
		case EventRefund:
			return StateRefunded, nil
		}
	case StateFulfilled:
		if e == EventRefund {
			return StateRefunded, nil
		}
	case StateClosed, StateRefunded:
		return "", fmt.Errorf("order: state %q is terminal, event %q rejected", s, e)
	default:
		return "", fmt.Errorf("order: unknown state %q", s)
	}
	return "", fmt.Errorf("order: event %q is not allowed in state %q", e, s)
}

func knownEvent(e Event) bool {
	switch e {
	case EventPay, EventFulfill, EventClose, EventRefund:
		return true
	}
	return false
}

// file: internal/order/state_test.go
// tier: L1
// verify: go test ./internal/order/

package order

import (
	"strings"
	"testing"
)

func TestNextAllowsLegalTransitions(t *testing.T) {
	cases := []struct {
		from State
		ev   Event
		want State
	}{
		{StateCreated, EventPay, StatePaid},
		{StateCreated, EventClose, StateClosed},
		{StatePaid, EventFulfill, StateFulfilled},
		{StatePaid, EventRefund, StateRefunded},
		{StateFulfilled, EventRefund, StateRefunded},
	}
	for _, c := range cases {
		got, err := Next(c.from, c.ev)
		if err != nil {
			t.Fatalf("%s + %s: %v", c.from, c.ev, err)
		}
		if got != c.want {
			t.Fatalf("%s + %s = %s, want %s", c.from, c.ev, got, c.want)
		}
	}
}

func TestNextRejectsIllegalTransitions(t *testing.T) {
	cases := []struct {
		from State
		ev   Event
	}{
		{StateCreated, EventFulfill},
		{StateCreated, EventRefund},
		{StatePaid, EventPay},
		{StatePaid, EventClose},
		{StateFulfilled, EventClose},
		{StateFulfilled, EventPay},
	}
	for _, c := range cases {
		if _, err := Next(c.from, c.ev); err == nil {
			t.Fatalf("%s + %s: want error", c.from, c.ev)
		}
	}
}

func TestNextRejectsTerminalStates(t *testing.T) {
	for _, s := range []State{StateClosed, StateRefunded} {
		for _, e := range []Event{EventPay, EventFulfill, EventClose, EventRefund} {
			_, err := Next(s, e)
			if err == nil {
				t.Fatalf("%s + %s: want terminal error", s, e)
			}
			if !strings.Contains(err.Error(), "terminal") {
				t.Fatalf("%s + %s: error %q does not mention terminal", s, e, err)
			}
		}
	}
}

func TestNextRejectsUnknownInput(t *testing.T) {
	if _, err := Next("shipped", EventPay); err == nil || !strings.Contains(err.Error(), "unknown state") {
		t.Fatalf("unknown state error = %v", err)
	}
	if _, err := Next(StateCreated, "cancel"); err == nil || !strings.Contains(err.Error(), "unknown event") {
		t.Fatalf("unknown event error = %v", err)
	}
}

cd .local/checks/webapp-lab && go test ./internal/order/ -run 'TestNext' -count=1 -v

=== RUN   TestNextAllowsLegalTransitions
--- PASS: TestNextAllowsLegalTransitions (0.00s)
=== RUN   TestNextRejectsIllegalTransitions
--- PASS: TestNextRejectsIllegalTransitions (0.00s)
=== RUN   TestNextRejectsTerminalStates
--- PASS: TestNextRejectsTerminalStates (0.00s)
=== RUN   TestNextRejectsUnknownInput
--- PASS: TestNextRejectsUnknownInput (0.00s)
PASS
ok  	webapp/internal/order	0.264s