运行时语义决策稿

本文记录 Shield 重构后的运行时语义决策，是编码实现的目标契约；个别条目的落地状态以各节标注为准。

目标是让后续实现者不需要重新讨论基础语义，可以按本文补测试、迭代。

设计原则

• shield_core 只承载 Actor/Service 核心语义。
• CAF 是内部机制，不出现在 Lua API 和 public C++ API。
• Lua 是默认业务语言，C++ 负责运行时和少量性能敏感扩展。
• 本地、IPC、cluster 的消息语义必须尽量一致。
• 最小部署路径优先单节点稳定；shield_cluster 是官方可选模块，不进入 shield_core，但需要提前冻结地址、超时和错误语义。

语义文档索引

运行时语义已按专题拆分为独立文档。当前阅读和实现时按以下优先级处理。

当前收敛顺序：

• Phase 1 最小闭环覆盖单节点 Lua service、registry、基础 send/call 返回形态、TCP gateway、插件系统 v1 的显式实例/binding、配置验证和 shield::run 入口。
• handler 内 coroutine-aware call/sleep 已进入当前实现路径；timer callback 和 fork task 同样以协程方式执行（invoke_coroutine），挂起语义与 handler 一致。真实 DB/Redis 驱动连接、UDP/KCP/WebSocket、ops snapshot 和官方可选模块不作为当前最小验收阻塞项。
• schema/tooling、mapper、entity/component 等文档是后续草案；除非路线图重新纳入，否则不能反向扩大当前 runtime 范围。

权威契约

文档	内容
Lua API 契约	shield.* 用户 API、service module 形态、旧 API 删除清单
Lua API 测试用例	API 测试矩阵，示例不替代测试
配置语义	YAML 配置 schema（权威来源）、配置验证、环境差异
官方可选模块契约	cluster/global/player/server/ops 的边界、owner、依赖方向
官方可选模块验收矩阵	optional module 测试矩阵，防止反向污染 core

Core 与第一方运行时模块

文档	内容
服务语义	ServiceHandle、ServiceId、Service Registry、spawn、self、Lua service module、handler 上下文、exit
消息语义	MessageEnvelope、MessagePayload、send、call、背压、QoS、超时、nested call、coroutine 调度、错误处理
定时器语义	timer API、时间语义、错误语义、sleep、fork、Task ID
Lua VM 语义	Lua VM 模型、热更新策略、Blue-Green 替换
网络语义	shield_net、shield_transport、gateway、ClientContext/ClientRef、Phase 1 TCP 范围、deferred UDP/KCP/WebSocket
数据访问架构	core 零数据、插件数据接口、binding 调用形态、连接池归插件自治
日志语义	日志级别、结构化格式、上下文注入、轮转、审计日志
Starter 系统	BootstrapContext、Starter 顺序、ScriptStarter、旧 DI/插件设计删除
启动流程	启动顺序、关闭顺序、超时、信号处理、优雅重启
错误码参考	所有运行时错误码汇总：消息、服务、资源、数据库、Redis、网络
安全语义	Lua 沙箱、服务间权限、网络安全、敏感数据保护

官方可选模块

文档	内容
集群语义	可选 shield_cluster：节点发现、远端路由、节点心跳、旧代码处理
全局数据	可选 shield_global：GlobalData、跨进程共享数据、分布式锁（重入、续期）、排行榜、限流器、Pub/Sub
玩家生命周期	可选 shield_player：PlayerSession、PlayerManager、认证、断线重连、离线消息缓存、多设备策略
服务器状态	可选 shield_server（P0 已落地）：ServerManager 进程级单例、四态状态机、维护模式、shutdown(ms) 关闭交接、watch 状态通知、运行时信息
运维语义	可选 shield_ops：运维端点、metrics、健康检查

草案与业务模式

文档	内容
实体与组件	游戏实体抽象、组件化设计、Entity/Component/Room 模式；不属于当前 core 或 Phase 1 最小运行时契约
游戏状态持久化与回档	游戏业务存储模式、内存快照、增量日志、回档、事务和灾备设计；不属于当前 core 或 Phase 1 最小运行时契约

实现顺序建议

后续编码按以下顺序推进，避免循环依赖。

M1. 基础类型与 target

• 建立 shield_base。
• 按 CMake 重构策略 拆分 target。
• 定义 Result<T>、Error、ByteBuffer、TimePoint。
• 定义 ServiceId、NodeId、ServiceAddress。
• 增加 public header forbidden CAF 检查。

M2. Service identity 与 registry

• 实现 ServiceHandle。
• 实现 ServiceRegistry。
• 支持 name reserve/publish/unregister/query。
• 支持 owner exit 自动清理。
• 增加 name conflict、invalid name、stale handle 测试。

M3. Envelope 与 payload

• 实现 MessageEnvelope。
• 实现 MessagePayload。
• 实现 LuaPack 编码接口。
• 支持 method、argc、args。
• 增加 nil、false、多返回值、ServiceHandle 编码测试。

M4. spawn/send/call

• 实现 spawn ready/rollback 语义。
• 实现 non-blocking send。
• 实现 call pending registry。
• 实现 timeout 和 late response 丢弃。
• 增加 self-send、stale handle 测试（CAF actor mailbox 无界，无 mailbox full 用例）。

M5. Lua service lifecycle

• 实现 module table loader。
• 实现 on_init / method dispatch / on_exit。
• 实现 shield.self、shield.sender、shield.names。
• 按 Lua API 契约 删除 legacy API。
• 增加 init failure rollback、method_not_found、handler_error 测试。

M6. timer、sleep、fork

• 实现 TimerId。
• 实现 timer_once、timer、cancel_timer。
• 实现 handler coroutine-aware sleep。
• 实现 fork 和 task id；task body 以协程方式执行（invoke_coroutine 包裹）。
• 增加 fixed-delay、timer error stop、service exit auto-cancel 测试。

M7. net/gateway/plugins

• 整理 shield_transport 和 shield_net 边界。
• 实现 gateway Lua callback 草图。
• 接入插件系统 v1 的 manifest scan、instance、binding 和 register_lua 分发。
• 数据访问通过插件 namespace 暴露；真实 MySQL/Redis 连接、订阅生命周期和压力验证独立推进，不阻塞最小 Lua runtime。

ops snapshot 和本地 diagnostics 属于 shield_ops 可选模块，除非显式启用 shield_ops，不得进入最小 runtime 验收。

M8. 可选 cluster/global/ops

• 不把 cluster 放进 core。
• 为 route key 保留 node_epoch。
• 为 ops 增加 node heartbeat 状态模型。
• 后续独立实现 shield_cluster，并让 shield_global、shield_ops 只依赖公开 snapshot/handle 语义。