1. 附录

本附录为速查卡片：符号名、参数顺序以仓库当前版本为准；若与正文或 go doc 冲突，以 github.com/aiyang-zh/zhenyi / zhenyi-base 源码为准。附录与全书示例均不等同于经大规模线上验证的定型方案，生产环境请自行核对与压测（见前言「立场与局限」）。

1.1. 附录 A：核心 API 速查

1.1.1. Actor 与 Group（多进程 / 手写启动）

// Actor：由配置构造；业务里更常见的是 zstartup.App 注册工厂，由框架创建。
actor := zactor.NewActor(zmodel.ActorConfig{
    Id: 1, ActorType: 1, Name: "demo", Index: 1,
    Addr: "127.0.0.1:0", Process: 1,
})

group := zactor.NewGroup(processIndex, isSingle)
group.AddActor(actor)
group.SetDiscoverer(discoverer) // 多进程：zdiscovery.NewEtcdDiscovery 等

// NATS 总线：通常 znats.NewDefaultNats 会同时设置 zbus.DefaultBus
znats.NewDefaultNats(znats.DefaultURL, 1)
if err := znats.DefaultNatsClient.Connect(ctx); err != nil {
    panic(err)
}

actor.GetHandleMgr().RegisterHandle(msgId, func(ctx context.Context, msg *zmsg.Message) {
    // ...
})
actor.Run(ctx)

1.1.2. 消息发送（Actor 上）

// Fire-and-forget：request 需实现 ziface.IMessage
actor.SendActor(targetActorId, request)

// RPC：reply 为预先分配或可解码的 IMessage；返回 RpcReply（非 (reply, error)）
rpcRes := actor.CallActor(targetActorId, request, reply, 5*time.Second)
if rpcRes.Code != ziface.ErrCode_Success {
    // rpcRes.Msg
}

// 异步任务（不阻塞 Actor 主循环）
actor.AsyncRun(func() {
    actor.SendActor(resultActorId, resultMsg)
})

1.1.3. Gate（zgate.Server）

监听地址来自 zmodel.ActorConfig.Addr（在 NewServer 传入的配置里），没有单独的 gate.Addr 字段。

cfg := zmodel.ActorConfig{
    Id: 1, ActorType: 1, Name: "gate", Index: 1,
    Addr: "0.0.0.0:8001", Process: 1,
    IsLimiter: true, Rate: 1000, Burst: 2000, // 嵌入 ActorConfig，OnAccept 里 SetLimit
}
gate := zgate.NewServer(cfg, znet.TCP)

gate.SetHTTPAddr(":8080") // 可选：非空则 RunServer 时自动起 HTTP

// 标准 TLS / 国密 GM-TLS 二选一按需
_ = gate.SetStandardTLS("server.crt", "server.key")

gate.OnNoRoute(func(orig *zmsg.Message) (*zmsg.Message, bool) {
    return nil, false
})

gate.GetHandleMgr().RegisterHandle(msgId, handler)

gate.SetRemoteRouteStrategy(&zroute.RendezvousHashStrategy{})

1.1.4. 指标与健康检查（zmetrics）

ctx, cancel := context.WithCancel(context.Background())
defer cancel()
metricsSrv := zmetrics.Enable(ctx, ":9090")
defer metricsSrv.Shutdown(context.Background())

metricsSrv.RegisterHealthCheck("etcd", func() error {
    if etcdCli == nil {
        return errors.New("etcd client nil")
    }
    // 可按 clientv3 的 Status 或业务约定探测
    return nil
})

1.1.5. 链路（zactor.SetTraceHooks）

须在任意 Actor Run 之前调用一次（内部 sync.Once）。参数为四个函数指针，不是带名字的结构体字面量。

zactor.SetTraceHooks(
    func() bool { return true },
    func(ctx context.Context, name string) (context.Context, func()) {
        ctx, span := tracer.Start(ctx, name)
        return ctx, span.End
    },
    func(ctx context.Context, msg *zmsg.Message) context.Context {
        // 从 msg 还原或注入 trace context，按你所用 SDK 实现
        return ctx
    },
    func(msg *zmsg.Message) {
        // 例如：msg.TraceIdHi/Lo、SpanId 与 tracer 对齐；具体字段见 zmsg.Message
    },
)

1.1.6. 热更新（*zactor.Actor）

actor.UpdateWorkerPoolSize(64)
actor.UpdateRateLimit(10000, 20000)
actor.UpdateMaxRPCPending(8192)

1.1.7. 消息对象池（*zmsg.Message）

msg := zmsg.GetMessage()
defer msg.Release()
// 发往其他 Actor 且异步存活时先 Retain，对方处理完 Release

buf, err := msg.MarshalPooled()
if err != nil {
    return err
}
defer buf.Release()

1.2. 附录 B：术语表

术语	英文	说明
Actor	Actor	状态 + 行为 + 邮箱的计算单元
Mailbox	Mailbox	Actor 的消息队列
Supervisor	Supervisor	监督者，负责重启出错的 Actor
监督策略	Supervision Strategy	出错后如何处理（重启/停止/升级）
Fire-and-Forget	Fire-and-Forget	发后不管，异步投递
Request-Response	Request-Response	请求-回复，RPC
位置透明	Location Transparency	本地/远程对调用方形态一致
对象级 Actor	Entity Actor	一实体一 Actor（常见于 Erlang/Akka）
服务级 Actor	Service Actor	一服务一 Actor（zhenyi 默认粒度）
RingBuffer	RingBuffer	环形缓冲，网络 I/O 常用
零拷贝	Zero-Copy	减少复制，降低 CPU 与 GC 压力
熔断器	Circuit Breaker	快速失败，抑制级联故障
一致性哈希	Consistent Hashing	节点变化时尽量减少 key 迁移
RendezvousHash	HRW	最高随机权重哈希，扩缩容友好
对象池	Object Pool	复用对象，减轻 GC
MPSC	MPSC	多生产者单消费者队列
Slot	Slot	RPC 等待槽位

1.3. 附录 C：参考资料

1.3.1. 项目地址

zhenyi：https://github.com/aiyang-zh/zhenyi
zhenyi-base：https://github.com/aiyang-zh/zhenyi-base
官网（展示）：https://zhenyi-site.pages.dev/

1.3.2. 设计与学习来源

zinx：https://github.com/aceld/zinx — 网络层与协议封包思路的入门参考
ET（游戏框架）：https://github.com/egametang/ET — Actor + Mailbox + Send/Call 等实践参考（不是 etcd）

1.3.3. 基础设施

NATS：https://nats.io — 跨进程 TopicBus 常用实现
etcd：https://etcd.io — 服务发现常用后端

附录