《MMO 服务器开发》18.2 承载数字汇总

// file: internal/summary/ledger.go
// tier: L1
// verify: go test ./internal/summary/
package summary

// Row 是承载数字总表的一行：指标、数值、成立条件、出处节号。
// 表里每一个数字都必须在对应节里查得到原文——这是本节唯一的纪律。
type Row struct {
	Metric    string
	Value     string
	Condition string
	Source    string
}

// Ledger 是数字账本：按指标名索引，同时保留写入顺序。
type Ledger struct {
	order []string
	rows  map[string]Row
}

// NewLedger 建一个空账本。
func NewLedger() *Ledger { return &Ledger{rows: make(map[string]Row)} }

// Add 追加一行。同名指标只保留第一次写入，避免重复定义被悄悄覆盖。
func (l *Ledger) Add(r Row) {
	if _, ok := l.rows[r.Metric]; ok {
		return
	}
	l.rows[r.Metric] = r
	l.order = append(l.order, r.Metric)
}

// Len 返回账本里的指标数。
func (l *Ledger) Len() int { return len(l.order) }

// Get 按指标名取行。
func (l *Ledger) Get(metric string) (Row, bool) {
	r, ok := l.rows[metric]
	return r, ok
}

// Metrics 按写入顺序返回全部指标名。
func (l *Ledger) Metrics() []string {
	out := make([]string, len(l.order))
	copy(out, l.order)
	return out
}

// VolumeOne 把正文总表里最值得跨章复用的那批数字编码成账本。
// 每一行的出处都是正文里能查到的那一节——没有出处的数字不许进表。
func VolumeOne() *Ledger {
	l := NewLedger()
	add := func(metric, value, cond, src string) {
		l.Add(Row{Metric: metric, Value: value, Condition: cond, Source: src})
	}

	// 第 2 章 网络 I/O 与并发模型
	add("goroutine 每实例栈内存", "约 2053 B", "10 万 goroutine 停在 channel 上，宿主 10 核", "2.2 / 2.3")
	add("虚拟线程每实例内存", "约 1006 B", "10 万虚拟线程，Colima 6 核容器", "2.3")
	add("2000 连接建立", "零失败，拨号 P50 约 15 ms", "错峰 64 条/批、批间隔 15 ms", "2.2")
	add("echo 往返 RTT", "8 连接 1.087 ms → 2000 连接 1.34 s", "本机 10 核，负载均值 57–66", "2.2")
	add("echo 吞吐", "8 连接 4159 → 2000 连接 1008 往返/秒", "同上，波动 982–1207", "2.2")

	// 第 4 章 序列化与编解码
	add("同一条 MoveNotify 字节数", "JSON 95 / 扁平化 32 / varint 30", "定长 vs varint，同机同结构体", "4.1 / 4.3")
	add("JSON 编解码", "编码 ~296 ns / 解码 ~1137 ns，128/248 B，5 allocs", "-benchmem -count=5", "4.3")
	add("扁平化定长编解码", "编码 ~17 ns / 解码 ~14 ns，32/0 B，0 allocs", "同上", "4.3")
	add("varint 二进制编解码", "编码 ~45 ns / 解码 ~22 ns，64/0 B，1/0 allocs", "容量调 64→32 后编码 ~39 ns", "4.3")

	// 第 5 章 可靠 UDP 与 KCP
	add("KCP 报文头 / mss", "24 B / 488 B", "MTU 固定 512", "5.2")
	add("RTO 收敛", "200 ms → 82 ms", "链路真实 RTT 60 ms", "5.2")
	add("队头阻塞（5% 丢包）", "单流 P90 120.1 ms vs 多流 39.5 ms", "600 条 30Hz、RTT 60 ms", "5.1")
	add("KCP vs TCP 式尾部延迟（5% 丢包）", "P99 155 ms vs 239.6 ms", "300 条 30Hz、RTT 60 ms、种子固定", "5.3")
	add("20% 丢包冗余发包", "1.49×", "KCP 快速重传，无 cwnd 兜底", "5.3")

	// 第 6–9 章 长连接、路由与定时
	add("心跳超时精度", "配置 300 ms，实测 304–305 ms", "看门狗节拍 37.5 ms", "6.2")
	add("1000 空连接内存", "约 6.5 KB/连接", "HeapAlloc 增量 / 1000", "6.2")
	add("会话表 Bind", "单锁 495.2 ns → 64 分片 102.6 ns", "10 核、1000 账号并行 Bind", "7.1")
	add("单帧去重判定", "约 7.3 ns/op，0 allocs", "32 位滑窗位图", "8.2")
	add("广播编一次发 N 次", "16.5–22.9 µs / 3 allocs", "1000 连接一次广播，假连接", "8.3")
	add("时间轮挂载", "77.29 ns/op，79 B", "vs time.AfterFunc 约 120 ns", "9.1 / 9.2")

	// 第 10–11 章 Actor 与幂等
	add("Actor Send", "有界 channel 39–44 ns vs 无界队列 102–117 ns", "30 万次/轮，3 轮", "10.3")
	add("邮箱背压上界", "尾巴卡住 50 ms 内源头仅发 4 条", "A→B→C 各 cap 1，上界 Σcap+1", "10.2")
	add("幂等窗口单键内存", "37.8 B/key", "500k 活键 HeapAlloc 增量 / 键数", "11.1")
	add("Window.Seen", "134 ns/op，0 allocs", "单次探测", "11.1")
	add("Settle 命中 / 首次", "37 ns/op（0 allocs）/ 321 ns/op（151 B）", "窗口命中 vs 落 store", "11.3")

	// 第 12–13 章 同步与预测
	add("全量 vs 增量字节", "691020 B vs 2716 B（254.4×）", "500 实体 × 60 tick，每 tick 2 新实体移动", "12.2")
	add("AOI 每客户端带宽", "r=32 1245 B/s；r=64 4958 B/s；r=128 19698 B/s", "100 万实体、工作集 15.5 MB", "12.3")
	add("AOI 扇出总量", "1187 / 4728 / 18785 MB/s", "同上，半径平方级放大", "12.3")
	add("本地预测省下", "约 44 ms（60 ms RTT → 下一帧 16 ms）", "60Hz、RTT 60 ms", "13.1")

	// 第 16–17 章 安全与端到端
	add("fuzz 5 秒执行", "约 150 万次（154 万 / 183 万）", "10 个 worker，零崩溃", "16.1")
	add("封包加解密往返", "620 ns/op，约 413 MB/s，565 B/op 5 allocs", "256 字节明文", "16.3")
	add("端到端 QPS 天花板", "约 3000–3200（50×400 与 100×200）", "world -aoi-radius 1，单机单世界", "17.3")
	add("端到端 P50/P99", "100×200：26.1 / 124–171 ms；1000×10：283.8 / 1642.1 ms", "同机，失败 1（1000 连接组）", "17.3")

	return l
}

// file: internal/summary/ledger_test.go
// tier: L1
// verify: go test ./internal/summary/
package summary

import "testing"

// TestVolumeOneIsCompleteAndSourced 断言账本覆盖了必查指标，且每一行都带
// 非空的条件与出处节号——没有出处的数字不许进表。
func TestVolumeOneIsCompleteAndSourced(t *testing.T) {
	l := VolumeOne()
	if l.Len() < 30 {
		t.Fatalf("账本只有 %d 行，期望 >= 30", l.Len())
	}
	required := []string{
		"同一条 MoveNotify 字节数", "JSON 编解码",
		"KCP vs TCP 式尾部延迟（5% 丢包）", "时间轮挂载", "邮箱背压上界",
		"幂等窗口单键内存", "全量 vs 增量字节", "AOI 每客户端带宽",
		"虚拟线程每实例内存", "端到端 QPS 天花板",
	}
	for _, m := range required {
		if _, ok := l.Get(m); !ok {
			t.Errorf("账本缺指标 %q", m)
		}
	}
	for _, m := range l.Metrics() {
		r, _ := l.Get(m)
		if r.Value == "" || r.Condition == "" || r.Source == "" {
			t.Errorf("指标 %q 缺值/条件/出处", m)
		}
	}
}

// TestLedgerRejectsDuplicate 断言同名指标不会被覆盖：一条指标只应出现一次。
func TestLedgerRejectsDuplicate(t *testing.T) {
	l := NewLedger()
	l.Add(Row{Metric: "x", Value: "1", Condition: "c", Source: "1.1"})
	l.Add(Row{Metric: "x", Value: "2", Condition: "c", Source: "1.1"})
	if l.Len() != 1 {
		t.Fatalf("Len = %d, want 1", l.Len())
	}
	if r, _ := l.Get("x"); r.Value != "1" {
		t.Fatalf("重复写入覆盖了首值：%q", r.Value)
	}
}

// TestRelativeInvariants 断言几组「同机相对关系」——它们是本节允许带走的结论，
// 而绝对数值不可移植。
func TestRelativeInvariants(t *testing.T) {
	if !(95 > 32 && 32 > 30) {
		t.Fatal("编解码字节数关系不成立")
	}
	const fullBytes, deltaBytes = 691020, 2716
	if ratio := float64(fullBytes) / float64(deltaBytes); ratio < 200 {
		t.Fatalf("全量/增量 = %.1f，期望 > 200", ratio)
	}
	if !(155.0 < 239.6) {
		t.Fatal("KCP 5% 丢包 P99 应低于 TCP 式")
	}
	if !(1245.0 < 4958.0 && 4958.0 < 19698.0) {
		t.Fatal("AOI 带宽应随半径单调增")
	}
}

$ go test -count=1 -v ./internal/summary/
=== RUN   TestVolumeOneIsCompleteAndSourced
--- PASS: TestVolumeOneIsCompleteAndSourced (0.00s)
=== RUN   TestLedgerRejectsDuplicate
--- PASS: TestLedgerRejectsDuplicate (0.00s)
=== RUN   TestRelativeInvariants
--- PASS: TestRelativeInvariants (0.00s)
PASS
ok  	aegis/internal/summary	0.445s