运行时语义决策稿
本文记录 Shield 重构后的运行时语义决策。当前仍处于设计阶段，本文是编码实现的目标契约，不代表源码已经全部完成。
目标是让后续实现者不需要重新讨论基础语义，可以按本文拆分任务、补测试、替换旧实现。
设计原则
shield_core只承载 Actor/Service 核心语义。- CAF 是内部机制，不出现在 Lua API 和 public C++ API。
- Lua 是默认业务语言，C++ 负责运行时和少量性能敏感扩展。
- 本地、IPC、cluster 的消息语义必须尽量一致。
- 最小部署路径优先单节点稳定；
shield_cluster是官方可选模块，不进入shield_core，但需要提前冻结地址、超时和错误语义。
语义文档索引
运行时语义已按专题拆分为独立文档。当前阅读和实现时按以下优先级处理。
权威契约
| 文档 | 内容 |
|---|---|
| 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、TaskHandle |
| Lua VM 语义 | Lua VM 模型、热更新策略、Blue-Green 替换 |
| 网络语义 | shield_net、shield_transport、gateway、SessionHandle、Phase 1 TCP 范围、deferred UDP/KCP/WebSocket |
| 数据语义 | shield_data、连接池、Phase 1 DB/Redis API、Phase 2+ data 扩展、错误处理 |
| 日志语义 | 日志级别、结构化格式、上下文注入、轮转、审计日志 |
| Starter 系统 | BootstrapContext、Starter 顺序、ScriptStarter、旧 DI/插件设计删除 |
| 启动流程 | 启动顺序、关闭顺序、超时、信号处理、优雅重启 |
| 错误码参考 | 所有运行时错误码汇总：消息、服务、资源、数据库、Redis、网络 |
| 安全语义 | Lua 沙箱、服务间权限、网络安全、敏感数据保护 |
官方可选模块
| 文档 | 内容 |
|---|---|
| 集群语义 | 可选 shield_cluster：节点发现、远端路由、节点心跳、旧代码处理 |
| 全局数据 | 可选 shield_global：GlobalData、跨进程共享数据、分布式锁（重入、续期）、排行榜、限流器、Pub/Sub |
| 玩家生命周期 | 可选 shield_player：PlayerSession、PlayerManager、认证、断线重连、离线消息缓存、多设备策略 |
| 服务器状态 | 可选 shield_server：ServerManager、服务器状态、运行时信息、状态变更通知 |
| 运维语义 | 可选 shield_ops：运维端点、metrics、健康检查 |
草案与业务模式
| 文档 | 内容 |
|---|---|
| 实体与组件 | 游戏实体抽象、组件化设计、Entity/Component/Room 模式；不属于当前 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
- 实现 coroutine-aware
spawn。 - 实现 non-blocking
send。 - 实现
callpending registry。 - 实现 timeout 和 late response 丢弃。
- 增加 self-send、stale handle、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。 - 实现
sleep。 - 实现
fork和TaskHandle。 - 增加 fixed-delay、timer error stop、service exit auto-cancel 测试。
M7. net/gateway/data/ops
- 整理
shield_transport和shield_net边界。 - 实现 gateway Lua callback 草图。
- 保留 data 原始 DB/Redis API。
- 实现 ops snapshot 和本地 diagnostics。
M8. 可选 cluster/global/ops
- 不把 cluster 放进 core。
- 为 route key 保留
node_epoch。 - 为 ops 增加 node heartbeat 状态模型。
- 后续独立实现
shield_cluster，并让shield_global、shield_ops只依赖公开 snapshot/handle 语义。