《MMO 服务器开发》1.1 分区分服与集群拓扑

// file: internal/topology/topology.go
// tier: L1
// verify: go test ./internal/topology/
// Package topology encodes the two questions chapter one asks about a cluster:
// which node roles exist, and which of the three deployment shapes (sharded
// zones, split servers, one global shard) a title is running.
//
// The node table is the important one. A role is defined by the state it owns,
// not by the directory it lives in: gateway owns connections, scene owns a map
// instance, battle owns one match, world owns a player, directory owns the
// routing table. Every role except directory is single-writer for the state it
// holds, which is what makes the cluster shardable at all.
package topology

// Role names one kind of process in an aegis cluster.
type Role string

const (
	// RoleGateway holds connection state: handshake, heartbeat, reconnect
	// ticket, rate-limit window. One copy per socket, so gateways replicate
	// freely and scale horizontally.
	RoleGateway Role = "gateway"
	// RoleScene holds map-instance state: authoritative X/Y, AOI, spawns.
	// Exactly one process mutates a given instance.
	RoleScene Role = "scene"
	// RoleBattle holds one match's state: teams, cooldowns, round score. It is
	// created per match and thrown away afterwards.
	RoleBattle Role = "battle"
	// RoleWorld holds a player's persistent state: bag, quest, guild, social.
	// Keyed by PlayerID, so players shard across world nodes.
	RoleWorld Role = "world"
	// RoleDirectory holds no player state: it owns the routing table that maps
	// PlayerID / InstanceID / NodeID to the node that currently owns it.
	RoleDirectory Role = "directory"
)

// Ownership describes how a role's state may be placed across processes.
type Ownership string

const (
	// OwnPerConnection state is copied once per open socket; two gateways each
	// holding a copy cannot disagree.
	OwnPerConnection Ownership = "per-connection"
	// OwnPerInstance state has exactly one writer, keyed by instance ID.
	OwnPerInstance Ownership = "per-instance"
	// OwnPerPlayer state has exactly one writer per player, keyed by PlayerID.
	OwnPerPlayer Ownership = "per-player"
	// OwnReplicated state is a control-plane copy that many nodes read and one
	// leader writes; it is deliberately replicated for availability.
	OwnReplicated Ownership = "replicated-control-plane"
)

// NodeRole is the section 1.1 boundary table in code.
type NodeRole struct {
	Role      Role
	Owns      string
	Ownership Ownership
	// SingleWriter is true when exactly one process may mutate this state.
	// Every role but the directory is single-writer for what it holds.
	SingleWriter bool
	// Horizontal is true when the role scales out by adding identical nodes
	// with no coordination beyond the routing table.
	Horizontal bool
}

// nodeRoles is the five-node boundary table of section 1.1.
var nodeRoles = []NodeRole{
	{RoleGateway, "connection: heartbeat, reconnect ticket, rate limit", OwnPerConnection, false, true},
	{RoleScene, "map instance: position, AOI, spawns", OwnPerInstance, true, true},
	{RoleBattle, "one match: teams, cooldowns, score", OwnPerInstance, true, true},
	{RoleWorld, "player: bag, quest, guild, social", OwnPerPlayer, true, true},
	{RoleDirectory, "routing table: id -> owning node", OwnReplicated, false, true},
}

// RoleOf returns the boundary entry for a role.
func RoleOf(r Role) (NodeRole, bool) {
	for _, n := range nodeRoles {
		if n.Role == r {
			return n, true
		}
	}
	return NodeRole{}, false
}

// AllRoles returns the five roles in table order.
func AllRoles() []Role {
	out := make([]Role, 0, len(nodeRoles))
	for _, n := range nodeRoles {
		out = append(out, n.Role)
	}
	return out
}

// Form names one of the three deployment shapes.
type Form string

const (
	// FormZone is the classic "分区": the world is cut into zones, and players
	// in different zones never meet. The zone boundary is a hard partition.
	FormZone Form = "zone"
	// FormServer is "分服": whole independent servers, each a self-contained
	// world; interaction across servers happens only through explicit
	// cross-server features.
	FormServer Form = "server"
	// FormGlobal is "全球同服": one logical world, scaled with dynamic shards
	// so any two players can meet. It pays for that reach with a routing layer.
	FormGlobal Form = "global"
)

// Shape is the section 1.1 comparison of the three forms.
type Shape struct {
	Form Form
	// MeetAnyPair is true when any two players can be placed in one match.
	MeetAnyPair bool
	// NeedsRouting is true when a directory/routing layer is mandatory, because
	// state ownership is decided at runtime rather than fixed at login.
	NeedsRouting bool
	// Isolation is what the shape buys you when one part of the world fails.
	Isolation string
}

// shapes is the three-form comparison table of section 1.1.
var shapes = []Shape{
	{FormZone, false, false, "a zone outage is contained to that zone"},
	{FormServer, false, true, "a server outage is contained to that server"},
	{FormGlobal, true, true, "no hard boundary; needs backpressure and draining to contain failure"},
}

// ShapeOf returns the comparison entry for a form.
func ShapeOf(f Form) (Shape, bool) {
	for _, s := range shapes {
		if s.Form == f {
			return s, true
		}
	}
	return Shape{}, false
}

// file: internal/topology/topology_test.go
// tier: L1
// verify: go test ./internal/topology/
package topology

import "testing"

func TestFiveRolesArePresent(t *testing.T) {
	want := []Role{RoleGateway, RoleScene, RoleBattle, RoleWorld, RoleDirectory}
	got := AllRoles()
	if len(got) != len(want) {
		t.Fatalf("AllRoles() has %d roles, want %d", len(got), len(want))
	}
	for i := range want {
		if got[i] != want[i] {
			t.Errorf("AllRoles()[%d] = %s, want %s", i, got[i], want[i])
		}
	}
}

func TestSingleWriterRoles(t *testing.T) {
	// A role is single-writer when exactly one process may mutate the state it
	// holds. gateway owns per-connection state (each socket has its own copy),
	// and directory is a replicated control plane; both may hold more than one
	// copy. scene, battle and world are the single writers.
	single := map[Role]bool{
		RoleGateway:   false,
		RoleScene:     true,
		RoleBattle:    true,
		RoleWorld:     true,
		RoleDirectory: false,
	}
	for _, r := range AllRoles() {
		n, ok := RoleOf(r)
		if !ok {
			t.Fatalf("RoleOf(%s): not found", r)
		}
		if n.SingleWriter != single[r] {
			t.Errorf("RoleOf(%s).SingleWriter = %v, want %v", r, n.SingleWriter, single[r])
		}
	}
}

func TestGatewayAndWorldOwnDifferentKeys(t *testing.T) {
	gw, _ := RoleOf(RoleGateway)
	world, _ := RoleOf(RoleWorld)
	if gw.Ownership != OwnPerConnection {
		t.Errorf("gateway ownership = %s, want per-connection", gw.Ownership)
	}
	if world.Ownership != OwnPerPlayer {
		t.Errorf("world ownership = %s, want per-player", world.Ownership)
	}
	if gw.Ownership == world.Ownership {
		t.Fatal("gateway and world must not share an ownership scope")
	}
}

func TestEveryRoleScalesHorizontally(t *testing.T) {
	for _, r := range AllRoles() {
		n, _ := RoleOf(r)
		if !n.Horizontal {
			t.Errorf("role %s must scale out by adding nodes", r)
		}
	}
}

func TestOnlyGlobalShapeMeetsAnyPair(t *testing.T) {
	for _, f := range []Form{FormZone, FormServer, FormGlobal} {
		s, ok := ShapeOf(f)
		if !ok {
			t.Fatalf("ShapeOf(%s): not found", f)
		}
		wantMeet := f == FormGlobal
		if s.MeetAnyPair != wantMeet {
			t.Errorf("ShapeOf(%s).MeetAnyPair = %v, want %v", f, s.MeetAnyPair, wantMeet)
		}
	}
}

func TestGlobalShapeNeedsRouting(t *testing.T) {
	// The global single shard is the only shape where ownership is decided at
	// runtime, so it is the only one where a routing layer is mandatory.
	g, _ := ShapeOf(FormGlobal)
	if !g.NeedsRouting {
		t.Fatal("the global shape must require a routing layer")
	}
	z, _ := ShapeOf(FormZone)
	if z.NeedsRouting {
		t.Fatal("a hard zone boundary must not require a runtime routing layer")
	}
}

=== RUN   TestFiveRolesArePresent
--- PASS: TestFiveRolesArePresent (0.00s)
=== RUN   TestSingleWriterRoles
--- PASS: TestSingleWriterRoles (0.00s)
=== RUN   TestGatewayAndWorldOwnDifferentKeys
--- PASS: TestGatewayAndWorldOwnDifferentKeys (0.00s)
=== RUN   TestEveryRoleScalesHorizontally
--- PASS: TestEveryRoleScalesHorizontally (0.00s)
=== RUN   TestOnlyGlobalShapeMeetsAnyPair
--- PASS: TestOnlyGlobalShapeMeetsAnyPair (0.00s)
=== RUN   TestGlobalShapeNeedsRouting
--- PASS: TestGlobalShapeNeedsRouting (0.00s)
PASS
ok  	aegis/internal/topology	0.464s