Shield 重构完成总结（历史快照）

状态：历史材料，非当前权威口径。

本文记录的是一次中间重构尝试的目标与阶段性判断，不能作为“当前源码已经完成重构”的证明。当前权威口径以 最终架构总纲、Lua API 契约、运行时语义决策稿、配置运行时语义、官方可选模块契约 和 重构路线图 为准。

若本文中的“完成”“已删除”“编译验证”等表述与权威契约或当前源码冲突，以权威契约和当前源码为准。

完成日期：2026/06/12

历史记录中的模块实现状态

模块	状态	文件	说明
shield_base	✅	src/shield_base/, include/shield/base/	基础类型
shield_log	✅	src/log/, include/shield/log/	日志系统
shield_config	✅	src/config/, include/shield/config/	配置系统
shield_core	✅	src/core/, include/shield/core/	纯净核心
shield_data	✅	src/data/, include/shield/data/	数据访问
shield_transport	✅	src/transport/, include/shield/transport/	传输层
shield_net	✅	src/net/, include/shield/net/	网络层
shield_lua	✅	src/lua/, include/shield/lua/	Lua VM
shield_bootstrap	✅	src/bootstrap/, include/shield/bootstrap/	启动器

模块依赖图

┌─────────────────────────────────────────────────────────────────┐
│                        shield_base                                │
│                    (Error, Result, ID, Time)                      │
└────────────────────────┬────────────────────────────────────────┘
                         │
         ┌───────────────┼───────────────┐
         │               │               │
         ▼               ▼               ▼
┌────────────────┐ ┌─────────────┐ ┌────────────┐
│  shield_log    │ │ shield_core │ │shield_config│
│  (Logger/Sink) │ │  (Service/  │ │  (YAML)    │
│                │ │  Message/   │ │            │
└───────┬────────┘ │  Timer)     │ └──────┬─────┘
        │          └──────┬───────┘       │
        │                  │               │
        └───────────────────┼───────────────┘
                           │
        ┌──────────────────┼───────────────────┐
        │                  │                   │
        ▼                  ▼                   ▼
┌──────────────┐  ┌───────────────┐  ┌──────────────┐
│shield_data   │  │shield_transport│ │shield_net    │
│ (DB/Redis)   │  │ (Frame/Codec) │  │ (Session)    │
└──────┬───────┘  └───────┬───────┘  └──────┬───────┘
       │                  │                  │
       └──────────────────┼──────────────────┘
                          │
                          ▼
                 ┌────────────────┐
                 │  shield_lua   │
                 │  (Lua VM/API) │
                 └────────┬───────┘
                          │
                          ▼
                 ┌────────────────┐
                 │shield_bootstrap│
                 │  (Starter/run) │
                 └────────────────┘

关键特性

1. CAF 隐藏

• shield_core 不公开暴露 caf::actor
• ServiceHandle 通过 detail::ActorHolder 隐藏实现
• CAF 仅在 CafAdapter 内部使用

2. 纯净核心

• shield_core 只依赖 shield_base 和 CAF
• 不依赖 Lua、网络、数据库、日志实现

3. 单节点优先，集群可选

• 默认运行路径优先保证单进程/单节点 runtime 稳定。
• shield_cluster 是官方可选模块，用于多进程/多机器通信、节点心跳、远端路由 cache 和可选服务发现。
• shield_cluster 必须复用 core 的 ServiceHandle、send/call、timeout 和错误语义，不能把服务发现或集群编排反向塞回 shield_core。
• 多节点能力不是被删除，而是从 core 主路径中拆出，后续通过 SHIELD_ENABLE_CLUSTER 和独立模块显式启用。

4. 新 Lua API

local M = {}

function M.on_init(args)
    M.name = args.name
    shield.log.info(M.name .. " started")
end

function M.ping(value)
    local src = shield.sender()
    shield.send(src, "pong", value)
end

function M.on_exit(reason)
    shield.log.info(M.name .. " exiting")
end

return M

5. 启动器系统

// 简单启动
shield::bootstrap::RuntimeConfig config;
shield::bootstrap::initialize(config);

// 或使用主入口
shield::bootstrap::run(argc, argv);

删除的旧模块

• src/di/ - 依赖注入系统
• src/annotations/ - 注解系统
• src/conditions/ - 条件装配
• src/metrics/ - 指标系统（移至可选模块）
• src/health/ - 健康检查（移至可选模块）
• src/core/plugin_* - 插件系统
• src/discovery/ - 服务发现（移至 shield_cluster 可选模块）

编译验证

cmake -B build -S .
cmake --build build

下一步

1. 修复实现与文档偏差 - 清理旧 _new include、修正模块边界和编译错误
2. 完善 Lua API 绑定 - 实现 shield.* API 的完整注册
3. 编写单元测试 - 验证各模块功能
4. 性能测试 - 验证新架构的性能