《MMO 服务器开发》18.1 卷一回顾：我们造出了什么

// file: internal/review/ledger.go
// tier: L1
// verify: go test ./internal/review/

// Package review is the machine-readable version of section 18.1's recap: one
// entry per chapter recording the part volume one built, the package it lives
// in, the artifact to reach for first, and the command that proves it runs.
// Two invariants a recap is most likely to break — every chapter left
// something behind, and a thread only points at chapters that exist — become
// assertions instead of promises.
package review

// Part is one reusable part a chapter left behind.
type Part struct {
	Chapter  int    // 1..17
	Slug     string // section that first builds it, as a relref target
	Pkg      string // import path under the aegis module root
	Artifact string // exported type or file to reach for first
	Verify   string // command that runs from the module root
}

// Ledger is every part volume one builds, in chapter order. Chapter 18 adds no
// part of its own; it only points back at these.
var Ledger = []Part{
	{1, "mmo-net-01-1-layered-responsibilities", "internal/overview", "Layer / Component / Server", "go test ./internal/overview/"},
	{2, "mmo-net-02-1-blocking-nonblocking-reactor", "internal/netio", "Reactor.Run", "go test ./internal/netio/"},
	{3, "mmo-net-03-2-length-prefix-and-framing", "internal/proto", "Frame / ReadFrame", "go test ./internal/proto/"},
	{4, "mmo-net-04-1-binary-codec-from-scratch", "internal/codec", "Writer / Reader", "go test ./internal/codec/"},
	{5, "mmo-net-05-2-kcp-from-scratch", "internal/kcp", "KCP / Input", "go test ./internal/kcp/"},
	{6, "mmo-net-06-1-websocket-handshake", "internal/ws", "ReadFrame / WriteFrame", "go test ./internal/ws/"},
	{7, "mmo-net-07-1-session-table", "internal/session", "Table / ShardedTable", "go test ./internal/session/"},
	{8, "mmo-net-08-1-routing-table", "internal/router", "Router / Dispatch", "go test ./internal/router/"},
	{9, "mmo-net-09-2-time-wheel-from-scratch", "internal/timing", "Wheel / After", "go test ./internal/timing/"},
	{10, "mmo-net-10-1-message-driven-entity", "internal/actor", "Entity / Registry", "go test ./internal/actor/"},
	{11, "mmo-net-11-1-idempotency-window", "internal/idem", "Window / Settler", "go test ./internal/idem/"},
	{12, "mmo-net-12-1-state-sync-vs-lockstep", "internal/sync", "World / Step", "go test ./internal/sync/"},
	{13, "mmo-net-13-1-input-buffer-and-prediction", "internal/predict", "Predictor / Reconcile", "go test ./internal/predict/"},
	{14, "mmo-net-14-1-server-timeline", "internal/clock", "Timeline / Estimator", "go test ./internal/clock/"},
	{15, "mmo-net-15-1-authority-boundary", "internal/authority", "Registry / Check", "go test ./internal/authority/"},
	{16, "mmo-net-16-2-flood-and-conn-exhaustion", "internal/guard", "Gate / Limiter / Sealer", "go test ./internal/guard/"},
	{17, "mmo-net-17-1-assemble-aegis", "cmd/aegis", "gateway.Config + main", "go build ./cmd/aegis/"},
}

// Station is one chapter on a thread.
type Station struct {
	Chapter int
	Note    string
}

// Thread is one idea carried from chapter to chapter: where it is first stated,
// and every later chapter that reuses or sharpens it.
type Thread struct {
	Name     string
	Stations []Station
}

// Threads are the ideas that appear in more than one chapter — the spine of the
// recap.
var Threads = []Thread{
	{"延迟是排队，不是协议栈", []Station{
		{2, "2000 连接把往返从 1.087ms 抬到 1.34s，Little 定律 2000 = 1008 × 1.98s 对得上"},
		{8, "广播编一次发 N 次：1000 连接 16.5µs vs 逐条编 67.5µs"},
		{9, "积压要丢帧，不能追赶成死亡螺旋（maxSteps 默认 8）"},
		{15, "令牌桶把在途请求压回队列容量内"},
	}},
	{"容量的单位是请求/秒，不是连接数", []Station{
		{2, "8 连接 4159 rt/s → 2000 连接 1008 rt/s，挂机连接几乎不花钱"},
		{7, "网关按账号限流：NewLimiter(10, 3)"},
		{15, "Throttle 时令牌桶容量与回填一起降"},
		{16, "每 IP 上限 64、全局 10000、握手令牌桶 burst 5 / refill 200ms"},
	}},
	{"11 字节帧头是全书共享的契约", []Station{
		{3, "固定头 11 字节，length = 7 + N"},
		{4, "编解码复用同一 wire 顺序，越界返回错误而非 panic"},
		{12, "增量编码复用同一头，CmdAttrSync = 0x0103"},
		{16, "fuzz 直接打 DecodeFrom：5 秒约 150 万次、0 崩溃"},
	}},
	{"客户端只提意图，服务端裁决", []Station{
		{13, "本地预测先走一步，服务端回 ack 后裁剪重放"},
		{14, "延迟补偿回退到射手当时看到的那一刻再判命中"},
		{15, "信任三分：客户端发 Derived 字段即违规；Tolerance 1.1、TeleportThreshold 40"},
	}},
	{"Actor 邮箱把锁消掉", []Station{
		{10, "8 发送者 × 2000 条在 -race 下无竞争；背压上界 Σcap + 1"},
		{17, "world 单 goroutine 消费邮箱，sessions / byName / grid 一把锁不用"},
	}},
}

// AssembleOrder is the dependency order chapter 17.1 fixed for the assembly.
var AssembleOrder = []string{"internal/proto", "internal/session", "internal/router", "internal/timing", "internal/actor"}

// snippet: internal/review/ledger_test.go（节选）
func TestEveryPartIsCompleteAndRunnable(t *testing.T) {
	for _, p := range Ledger {
		if p.Slug == "" || strings.Contains(p.Slug, ".md") || strings.HasPrefix(p.Slug, "/") {
			t.Errorf("chapter %d slug %q must be a bare same-volume relref target", p.Chapter, p.Slug)
		}
		if !strings.HasPrefix(p.Pkg, "internal/") && p.Pkg != "cmd/aegis" {
			t.Errorf("chapter %d package %q is neither under internal/ nor cmd/aegis", p.Chapter, p.Pkg)
		}
		if p.Artifact == "" {
			t.Errorf("chapter %d has no artifact", p.Chapter)
		}
		if !strings.HasPrefix(p.Verify, "go test") && !strings.HasPrefix(p.Verify, "go build") {
			t.Errorf("chapter %d verify %q is not a go command", p.Chapter, p.Verify)
		}
	}
}

func TestThreadsStayOnChaptersThatExist(t *testing.T) {
	inLedger := map[int]bool{}
	for _, p := range Ledger {
		inLedger[p.Chapter] = true
	}
	for _, th := range Threads {
		for _, s := range th.Stations {
			if !inLedger[s.Chapter] {
				t.Errorf("thread %q points at chapter %d, which left no part behind", th.Name, s.Chapter)
			}
		}
	}
}

=== RUN   TestLedgerCoversEveryChapterOnce
--- PASS: TestLedgerCoversEveryChapterOnce (0.00s)
=== RUN   TestEveryPartIsCompleteAndRunnable
--- PASS: TestEveryPartIsCompleteAndRunnable (0.00s)
=== RUN   TestThreadsStayOnChaptersThatExist
--- PASS: TestThreadsStayOnChaptersThatExist (0.00s)
=== RUN   TestAssembleOrderMatchesLedger
--- PASS: TestAssembleOrderMatchesLedger (0.00s)
PASS
ok  	aegis/internal/review	0.504s