《MMO 服务器开发》附录 A aegis 卷一 API 与模块速查

固定头（HeaderSize = 11）
  length  uint32  大端   bytes 0..3    length = 7 + N
  cmd     uint16  大端   bytes 4..5    命令号
  seq     uint32  大端   bytes 6..9    连接内自增序号
  flags   uint8          byte 10       标志位
载荷 N 字节             bytes 11..11+N
帧总长 = 11 + N     MaxPayload = 1 << 20

// file: api_reference_test.go
// tier: L1
// verify: go test ./...
package appendix

import (
	"os"
	"path/filepath"
	"strings"
	"testing"
)

// apiTable 钉死每个 internal 包的一个代表导出符号，签名逐字取自正文代码块。
var apiTable = []struct{ pkg, sig string }{
	{"proto", "type Frame struct { Cmd Cmd Seq uint32 Flags Flags Payload []byte }"},
	{"proto", "const HeaderSize = 11"},
	{"proto", "const MaxPayload = 1 << 20"},
	{"proto", "func DecodeFrom(buf []byte) (Frame, int, error)"},
	{"codec", "func NewWriter(capacity int) *Writer"},
	{"codec", "func SplitFrame(raw []byte) (payload []byte, err error)"},
	{"kcp", "func (k *KCP) Input(data []byte) int"},
	{"ws", "func ReadFrame(r io.Reader, maxPayload uint64) (*Frame, error)"},
	{"session", "func (t *Table) Bind(account string, c *Conn) (evicted *Conn)"},
	{"router", "type Handler func(*Context) error"},
	{"timing", "func (w *Wheel) After(d time.Duration, fn func()) uint64"},
	{"actor", "type Msg struct { Cmd uint16 Seq uint32 From EntityID Payload []byte }"},
	{"idem", "func FingerprintOf(cmd uint16, actor, token uint64, args ...uint64) Fingerprint"},
	{"sync", "type Vec2 struct{ X, Y float32 }"},
	{"predict", "const Speed = 5.0"},
	{"clock", "func Measure(t1, t2, t3, t4 time.Duration) Offset"},
	{"rewind", "func RewindTo(serverNow, rtt, interp time.Duration) time.Duration"},
	{"fairness", "func NewLagTracker(baseline, spike time.Duration, window int) *LagTracker"},
	{"authority", "func ValidateMove(p MoveProposal, cfg MoveConfig) MoveVerdict"},
	{"guard", "func NewSealer(key []byte) (*Sealer, error)"},
	{"gateway", "func DefaultConfig() Config"},
}

// fold 折叠空白，使「逐字一致」在 token 层面成立而不苛求排版。
func fold(s string) string { return strings.Join(strings.Fields(s), " ") }

// inPackage 在任意 ../chNN/internal/<pkg> 下折叠源码，查找签名是否逐字出现。
func inPackage(root, pkg, sig string) bool {
	found := false
	_ = filepath.Walk(root, func(p string, info os.FileInfo, err error) error {
		if err != nil || info.IsDir() || !strings.HasSuffix(p, ".go") || strings.HasSuffix(p, "_test.go") {
			return nil
		}
		if filepath.Base(filepath.Dir(p)) != pkg {
			return nil
		}
		b, _ := os.ReadFile(p)
		if strings.Contains(fold(string(b)), sig) {
			found = true
		}
		return nil
	})
	return found
}

func TestAPIListMatchesSource(t *testing.T) {
	root, _ := filepath.Abs("..")
	if _, err := os.Stat(filepath.Join(root, "ch03", "internal", "proto", "header.go")); err != nil {
		t.Skip("卷一源码树不在 ../chNN，跳过符号核对")
	}
	for _, e := range apiTable {
		if !inPackage(root, e.pkg, fold(e.sig)) {
			t.Errorf("%s: 源码里找不到签名 %s", e.pkg, e.sig)
		}
	}
}