《游戏服务端架构·品类、状态与拓扑》3.1 单体、分层与模块化单体

auth ─────────────► ops
  ▲                   ▲
  │                   │
room ───► economy ────┘
  │           ▲
  └───────────┴──── settlement ───► auth / ops

// file: internal/arch/graph.go
// tier: L1
// verify: go test ./internal/arch/
package arch

import (
	"fmt"
	"sort"
)

type Module string

const (
	Auth       Module = "auth"
	Room       Module = "room"
	Economy    Module = "economy"
	Settlement Module = "settlement"
	Ops        Module = "ops"
)

// modules is fixed so cycle reports are reproducible.
var modules = []Module{Auth, Room, Economy, Settlement, Ops}

type Edge struct {
	From Module
	To   Module
}

func (e Edge) String() string { return string(e.From) + "->" + string(e.To) }

// contract lists what a module MAY import. Anything absent is forbidden.
var contract = map[Module][]Module{
	Auth:       {Ops},
	Room:       {Auth, Economy},
	Economy:    {Auth, Ops},
	Settlement: {Room, Economy, Auth, Ops},
	Ops:        {},
}

func known(m Module) bool {
	_, ok := contract[m]
	return ok
}

func Allowed(e Edge) bool {
	for _, to := range contract[e.From] {
		if to == e.To {
			return true
		}
	}
	return false
}

type Violation struct {
	Edge   Edge
	Reason string
}

func (v Violation) String() string { return fmt.Sprintf("%s: %s", v.Edge, v.Reason) }

// Validate reports every dependency the contract does not permit.
func Validate(edges []Edge) []Violation {
	var out []Violation
	seen := make(map[Edge]bool, len(edges))
	for _, e := range edges {
		if !known(e.From) || !known(e.To) {
			out = append(out, Violation{e, "unknown module"})
			continue
		}
		if seen[e] {
			out = append(out, Violation{e, "duplicate dependency edge"})
			continue
		}
		seen[e] = true
		if !Allowed(e) {
			out = append(out, Violation{e,
				fmt.Sprintf("%s may not depend on %s", e.From, e.To)})
		}
	}
	return out
}

// DetectCycle returns the first cycle, with its start module repeated at the
// end (room->economy->room). The boolean is false when the graph is acyclic.
func DetectCycle(edges []Edge) ([]Module, bool) {
	adj := make(map[Module][]Module, len(modules))
	for _, m := range modules {
		adj[m] = nil
	}
	for _, e := range edges {
		if known(e.From) && known(e.To) {
			adj[e.From] = append(adj[e.From], e.To)
		}
	}
	for m := range adj {
		sort.Slice(adj[m], func(i, j int) bool { return adj[m][i] < adj[m][j] })
	}

	const white, gray, black = 0, 1, 2
	color := make(map[Module]int, len(modules))
	var stack, cycle []Module

	var dfs func(Module) bool
	dfs = func(m Module) bool {
		color[m] = gray
		stack = append(stack, m)
		for _, next := range adj[m] {
			if color[next] == gray {
				for i, s := range stack {
					if s == next {
						cycle = append(cycle, stack[i:]...)
						break
					}
				}
				cycle = append(cycle, next)
				return true
			}
			if color[next] == white && dfs(next) {
				return true
			}
		}
		stack = stack[:len(stack)-1]
		color[m] = black
		return false
	}

	for _, m := range modules {
		if color[m] == white && dfs(m) {
			return cycle, true
		}
	}
	return nil, false
}

// Check is the CI gate: allow-list violations plus cycle detection in one call.
func Check(edges []Edge) ([]Violation, []Module) {
	cycle, _ := DetectCycle(edges)
	return Validate(edges), cycle
}

// file: internal/arch/graph_test.go
// tier: L1
// verify: go test ./internal/arch/
package arch

import "testing"

func TestLegalDependenciesPass(t *testing.T) {
	edges := []Edge{
		{Auth, Ops}, {Room, Auth}, {Room, Economy},
		{Economy, Auth}, {Economy, Ops},
		{Settlement, Room}, {Settlement, Economy},
		{Settlement, Auth}, {Settlement, Ops},
	}
	if v, c := Check(edges); len(v) != 0 || len(c) != 0 {
		t.Fatalf("legal layout rejected: %v cycle=%v", v, c)
	}
}

func TestIllegalDependenciesRejected(t *testing.T) {
	edges := []Edge{
		{Auth, Room}, {Room, Settlement},
		{Economy, Room}, {Ops, Auth},
	}
	got := Validate(edges)
	if len(got) != len(edges) {
		t.Fatalf("got %d violations, want %d: %v", len(got), len(edges), got)
	}
	for i, v := range got {
		if v.Edge != edges[i] || v.Reason == "" {
			t.Fatalf("violation %d = %+v", i, v)
		}
	}
}

func TestCycleDetected(t *testing.T) {
	edges := []Edge{{Room, Economy}, {Economy, Settlement}, {Settlement, Room}}
	cycle, ok := DetectCycle(edges)
	if !ok {
		t.Fatal("cycle not detected")
	}
	if len(cycle) != 4 || cycle[0] != cycle[3] {
		t.Fatalf("path must repeat its start: %v", cycle)
	}
	if _, c := Check(edges); len(c) == 0 {
		t.Fatal("Check must surface the cycle")
	}
}

func TestContractItselfIsAcyclic(t *testing.T) {
	var edges []Edge
	for from, targets := range contract {
		for _, to := range targets {
			edges = append(edges, Edge{from, to})
		}
	}
	if cycle, ok := DetectCycle(edges); ok {
		t.Fatalf("allow-list contains a cycle: %v", cycle)
	}
}

func TestUnknownAndDuplicateEdges(t *testing.T) {
	got := Validate([]Edge{
		{Module("billing"), Economy},
		{Room, Auth}, {Room, Auth},
	})
	if len(got) != 2 || got[0].Reason != "unknown module" ||
		got[1].Reason != "duplicate dependency edge" {
		t.Fatalf("got %+v", got)
	}
}

$ cd .local/checks/gsarch-lab
$ gofmt -l .
$ go vet ./...
$ go test -count=1 -v ./internal/arch/
=== RUN   TestLegalDependenciesPass
--- PASS: TestLegalDependenciesPass (0.00s)
=== RUN   TestIllegalDependenciesRejected
--- PASS: TestIllegalDependenciesRejected (0.00s)
=== RUN   TestCycleDetected
--- PASS: TestCycleDetected (0.00s)
=== RUN   TestContractItselfIsAcyclic
--- PASS: TestContractItselfIsAcyclic (0.00s)
=== RUN   TestUnknownAndDuplicateEdges
--- PASS: TestUnknownAndDuplicateEdges (0.00s)
PASS
ok  	gsarchlab/internal/arch	0.234s

settlement（异步、无玩家直连）
    → room（有状态、需排空与租约）
    → economy（强一致、需幂等与对账）
    → auth（地基，最后动）