《游戏服务端架构·品类、状态与拓扑》12.2 时序图、状态机与契约表

idle --create_room--> creating --room_ready--> waiting
waiting --start_match--> playing --match_end--> settling --settle_done--> closed
playing --disconnect--> reconnecting --reconnect--> playing
waiting --cancel_room--> closed

契约表 operation ──> 状态机 trigger ──> 时序图 step
        │                    │
        └──── 错误码覆盖 ────┘

client          gateway              room
  |--create_room-->|                  |
  |                |--create_room---->|
  |                |<--room_ready-----|
  |<--room_ready---|                  |
  |                |                  |
  |   (网络断开)    |                  |
  |--reconnect---->|--reconnect------>|
  |                |<--state_snapshot-|
  |<--state_snapshot|                 |

// file: internal/contractspec/contractspec.go
// tier: L1
// verify: go test ./internal/contractspec/
package contractspec

import (
	"fmt"
	"strings"
)

// Contract describes one operation that crosses a process boundary.
type Contract struct {
	Operation      string
	Request        []string
	Response       []string
	Errors         []string
	Idempotent     bool
	IdempotencyKey string
}

// Step is one arrow in a sequence diagram.
type Step struct {
	From      string
	To        string
	Operation string
}

// Transition is one edge in the room state machine.
type Transition struct {
	From    string
	Trigger string
	To      string
	Errors  []string
}

// Machine is the lifecycle shared by documents, code, and tests.
type Machine struct {
	Initial     string
	States      []string
	Terminal    []string
	Transitions []Transition
}

// ValidateMachine checks structure only. Reachability is a separate check
// because an invalid machine should fail before graph traversal.
func ValidateMachine(m Machine) []error {
	var errs []error
	if len(m.States) == 0 {
		return []error{fmt.Errorf("machine has no states")}
	}
	states := make(map[string]bool, len(m.States))
	for _, s := range m.States {
		if strings.TrimSpace(s) == "" {
			errs = append(errs, fmt.Errorf("machine has an empty state"))
			continue
		}
		if states[s] {
			errs = append(errs, fmt.Errorf("state %q is declared twice", s))
		}
		states[s] = true
	}
	if !states[m.Initial] {
		errs = append(errs, fmt.Errorf("initial state %q is not declared", m.Initial))
	}
	terminal := make(map[string]bool, len(m.Terminal))
	for _, s := range m.Terminal {
		if !states[s] {
			errs = append(errs, fmt.Errorf("terminal state %q is not declared", s))
		}
		terminal[s] = true
	}
	outgoing := make(map[string]bool, len(m.Transitions))
	for _, t := range m.Transitions {
		if !states[t.From] || !states[t.To] {
			errs = append(errs, fmt.Errorf("transition %q->%q uses an unknown state", t.From, t.To))
		}
		if strings.TrimSpace(t.Trigger) == "" {
			errs = append(errs, fmt.Errorf("transition %q->%q has no trigger", t.From, t.To))
		}
		if terminal[t.From] {
			errs = append(errs, fmt.Errorf("terminal state %q has an outgoing transition", t.From))
		}
		outgoing[t.From] = true
	}
	for _, s := range m.States {
		if !terminal[s] && !outgoing[s] {
			errs = append(errs, fmt.Errorf("non-terminal state %q has no outgoing transition", s))
		}
	}
	return errs
}

// CheckReachability returns every state that cannot be entered from Initial.
func CheckReachability(m Machine) []error {
	seen := map[string]bool{m.Initial: true}
	queue := []string{m.Initial}
	for len(queue) > 0 {
		cur := queue[0]
		queue = queue[1:]
		for _, t := range m.Transitions {
			if t.From == cur && !seen[t.To] {
				seen[t.To] = true
				queue = append(queue, t.To)
			}
		}
	}
	var errs []error
	for _, s := range m.States {
		if !seen[s] {
			errs = append(errs, fmt.Errorf("state %q is unreachable from %q", s, m.Initial))
		}
	}
	return errs
}

// CheckCoverage enforces a two-way match between the machine and the table:
// every trigger has a contract, every contract is used, and every declared
// error is reachable through a transition of that operation.
func CheckCoverage(m Machine, contracts []Contract) []error {
	var errs []error
	byOp := make(map[string]Contract, len(contracts))
	for _, c := range contracts {
		if _, ok := byOp[c.Operation]; ok {
			errs = append(errs, fmt.Errorf("contract %q: duplicate operation", c.Operation))
		}
		byOp[c.Operation] = c
		if strings.TrimSpace(c.Operation) == "" {
			errs = append(errs, fmt.Errorf("contract with empty operation"))
		}
		if len(c.Request) == 0 || len(c.Response) == 0 {
			errs = append(errs, fmt.Errorf("contract %q: request or response is empty", c.Operation))
		}
		if c.Idempotent && strings.TrimSpace(c.IdempotencyKey) == "" {
			errs = append(errs, fmt.Errorf("contract %q: idempotent without key", c.Operation))
		}
	}
	used := make(map[string]bool, len(m.Transitions))
	for _, t := range m.Transitions {
		used[t.Trigger] = true
		c, ok := byOp[t.Trigger]
		if !ok {
			errs = append(errs, fmt.Errorf("transition %s->%s: no contract for %q", t.From, t.To, t.Trigger))
			continue
		}
		declared := make(map[string]bool, len(c.Errors))
		for _, e := range c.Errors {
			declared[e] = true
		}
		for _, e := range t.Errors {
			if !declared[e] {
				errs = append(errs, fmt.Errorf("transition %s->%s: error %q not in contract %q", t.From, t.To, e, t.Trigger))
			}
		}
	}
	for _, c := range contracts {
		if !used[c.Operation] {
			errs = append(errs, fmt.Errorf("contract %q: no transition uses it", c.Operation))
			continue
		}
		reached := make(map[string]bool)
		for _, t := range m.Transitions {
			if t.Trigger == c.Operation {
				for _, e := range t.Errors {
					reached[e] = true
				}
			}
		}
		for _, e := range c.Errors {
			if !reached[e] {
				errs = append(errs, fmt.Errorf("contract %q: error %q never reached", c.Operation, e))
			}
		}
	}
	return errs
}

// CheckSequence verifies that every arrow uses an operation from the table.
// Ordering belongs to the diagram; existence belongs to the contract table.
func CheckSequence(steps []Step, contracts []Contract) []error {
	var errs []error
	known := make(map[string]bool, len(contracts))
	for _, c := range contracts {
		known[c.Operation] = true
	}
	for i, s := range steps {
		if strings.TrimSpace(s.From) == "" || strings.TrimSpace(s.To) == "" {
			errs = append(errs, fmt.Errorf("step %d: empty actor", i+1))
		}
		if !known[s.Operation] {
			errs = append(errs, fmt.Errorf("step %d: operation %q not in contract table", i+1, s.Operation))
		}
	}
	return errs
}

$ cd .local/checks/gsarch-lab
$ go test -count=1 ./internal/contractspec/
ok  	gsarchlab/internal/contractspec	0.485s