《MMO 服务器开发》18.3 进入玩法卷

// file: internal/handoff/handoff.go
// tier: L1
// verify: go test ./internal/handoff/
// Package handoff encodes the contract between volume one (《网络与并发内核》)
// and volume two (《单服架构与玩法系统》): which reusable part each volume-two
// chapter consumes, and which topics volume two deliberately leaves to volumes
// three and four. Section 18.3's tables are for humans; this file is the
// machine-readable version, so the handoff is a thing a test can fail on
// instead of a promise nobody re-reads.
package handoff

// Part is a reusable piece of the network/concurrency core that volume one
// hands over.
type Part struct {
	// Name is the part, e.g. "会话表".
	Name string
	// From is where volume one built it, e.g. "第 7 章".
	From string
}

// Use says how one volume-two chapter consumes a part.
type Use struct {
	// Chapter must name a chapter in VolumeTwoChapters.
	Chapter string
	// How is the one-line "what it does with it".
	How string
}

// Row is one line of the handoff table: a part and every chapter that uses it.
type Row struct {
	Part Part
	Uses []Use
}

// VolumeTwoChapters is volume two's table of contents. Every Use.Chapter must
// appear here; a Use naming a chapter that does not exist is a dangling
// reference — the "I'll wire it up later" promise that rots.
var VolumeTwoChapters = []string{
	"第 1 章 分层与状态归属",
	"第 2 章 实体运行时",
	"第 3 章 场景实例",
	"第 4 章 AOI 与兴趣管理",
	"第 5 章 战斗管线",
	"第 6 章 掉落与背包",
	"第 7 章 任务系统",
	"第 8 章 聊天",
	"第 9 章 组队",
	"第 10 章 公会",
	"第 11 章 排行榜",
	"第 12 章 邮件",
	"第 13 章 交易",
	"第 14 章 匹配与房间",
}

// Table is the handoff table, in code. Order follows volume one's chapters.
var Table = []Row{
	{
		Part: Part{Name: "会话表", From: "第 7 章"},
		Uses: []Use{
			{Chapter: "第 1 章 分层与状态归属", How: "在线态挂会话上，玩法逻辑用 sessionID 定位玩家实体"},
			{Chapter: "第 2 章 实体运行时", How: "连接断开时摘除运行时实体，但保留其落库状态"},
			{Chapter: "第 8 章 聊天", How: "私聊按会话定位接收者，离线则转邮件"},
			{Chapter: "第 14 章 匹配与房间", How: "房间成员靠会话表判在线，掉线即退出队列"},
		},
	},
	{
		Part: Part{Name: "路由表", From: "第 8 章"},
		Uses: []Use{
			{Chapter: "第 2 章 实体运行时", How: "每种玩法命令注册一个 handler，复用卷一的 cmd→handler 分发"},
			{Chapter: "第 5 章 战斗管线", How: "攻击 / 施法命令走同一张路由表进管线"},
			{Chapter: "第 7 章 任务系统", How: "任务事件（击杀 / 拾取 / 到达）注册成路由的回调"},
		},
	},
	{
		Part: Part{Name: "Actor 邮箱", From: "第 10 章"},
		Uses: []Use{
			{Chapter: "第 3 章 场景实例", How: "一个场景实例 = 一个 actor，玩法消息串行进邮箱，免锁"},
			{Chapter: "第 2 章 实体运行时", How: "每个实体一个邮箱，状态只被自己的消息推进"},
			{Chapter: "第 10 章 公会", How: "公会是一个 actor，成员操作在公会邮箱里串行"},
			{Chapter: "第 14 章 匹配与房间", How: "房间是一个 actor，匹配成功后成员消息进房间邮箱"},
		},
	},
	{
		Part: Part{Name: "定时器", From: "第 9 章"},
		Uses: []Use{
			{Chapter: "第 5 章 战斗管线", How: "技能冷却与 buff 到期挂时间轮，按 tick 推进"},
			{Chapter: "第 6 章 掉落与背包", How: "掉落物过期回收走时间轮，不占场景主循环"},
			{Chapter: "第 11 章 排行榜", How: "周期结算与刷新用时间轮的周期任务"},
			{Chapter: "第 12 章 邮件", How: "邮件过期与附件退回挂定时器"},
		},
	},
	{
		Part: Part{Name: "幂等窗口", From: "第 11 章"},
		Uses: []Use{
			{Chapter: "第 6 章 掉落与背包", How: "防重复拾取：同一掉落物只入一次背包"},
			{Chapter: "第 9 章 组队", How: "防重复邀请 / 重复入队请求"},
			{Chapter: "第 13 章 交易", How: "防重复扣款：同一笔交易只结算一次"},
		},
	},
	{
		Part: Part{Name: "同步模型", From: "第 12–14 章"},
		Uses: []Use{
			{Chapter: "第 4 章 AOI 与兴趣管理", How: "AOI 是兴趣过滤的具体实现，决定谁收到谁的快照"},
			{Chapter: "第 5 章 战斗管线", How: "战斗结果按快照 / 增量下发给兴趣范围内的玩家"},
		},
	},
	{
		Part: Part{Name: "权威校验", From: "第 15 章"},
		Uses: []Use{
			{Chapter: "第 5 章 战斗管线", How: "伤害裁决在服务端算，客户端只上报意图"},
			{Chapter: "第 6 章 掉落与背包", How: "拾取合法性（距离 / 归属 / 冷却）在服务端校验"},
		},
	},
}

// Volume identifies which book owns a topic.
type Volume int

const (
	// Vol1 is 《网络与并发内核》 (this book).
	Vol1 Volume = 1
	// Vol2 is 《单服架构与玩法系统》.
	Vol2 Volume = 2
	// Vol3 is the distributed / cross-server volume.
	Vol3 Volume = 3
	// Vol4 is the operations / live-ops volume.
	Vol4 Volume = 4
)

// OutOfScope is what volume two deliberately does NOT cover, and which volume
// does. This is the "don't wander into the next book" guard: a topic that
// shows up in volume two's outline but belongs here is a scope leak.
var OutOfScope = []struct {
	Topic string
	Owner Volume
}{
	{"跨服传送", Vol3},
	{"分布式一致性与分服", Vol3},
	{"分库分表与合服迁移", Vol3},
	{"压测与承载数字", Vol4},
	{"线上运营与热更新", Vol4},
	{"监控告警与故障演练", Vol4},
}

// Consumes returns the chapters of volume two that consume the named part.
func Consumes(part string) []string {
	for _, r := range Table {
		if r.Part.Name == part {
			out := make([]string, 0, len(r.Uses))
			for _, u := range r.Uses {
				out = append(out, u.Chapter)
			}
			return out
		}
	}
	return nil
}

=== RUN   TestEveryPartHasAtLeastOneUse
--- PASS: TestEveryPartHasAtLeastOneUse (0.00s)
=== RUN   TestEveryUsePointsAtARealChapter
--- PASS: TestEveryUsePointsAtARealChapter (0.00s)
=== RUN   TestPartNamesAreUnique
--- PASS: TestPartNamesAreUnique (0.00s)
=== RUN   TestEveryVolumeTwoChapterConsumesSomething
--- PASS: TestEveryVolumeTwoChapterConsumesSomething (0.00s)
=== RUN   TestOutOfScopeBelongsToOtherVolumes
--- PASS: TestOutOfScopeBelongsToOtherVolumes (0.00s)
=== RUN   TestConsumes
--- PASS: TestConsumes (0.00s)
PASS
ok  	aegis/internal/handoff	0.263s