架构设计

本文档介绍 Croupier C++ SDK 的架构设计。

四层组件化架构

Component Level    ← economy-system (可分发模块)
     ↓
Resource Level     ← 钱包管理面板 (UI 资源组织)
     ↓
Entity Level       ← wallet.entity (业务对象模型)
     ↓
Function Level     ← wallet.transfer (具体函数实现)

Function Level（函数层）

最底层的执行单元，实现具体的业务逻辑：

std::string TransferHandler(const std::string& context, const std::string& payload) {
    // 具体的转账逻辑
    return R"({"success": true})";
}

Entity Level（实体层）

业务对象的抽象，定义对象的操作：

VirtualObjectDescriptor wallet_entity;
wallet_entity.id = "wallet.entity";
wallet_entity.operations["transfer"] = "wallet.transfer";
wallet_entity.operations["get"] = "wallet.get";

Resource Level（资源层）

UI 和资源的组织单位，定义管理界面：

ResourceDescriptor wallet_resource;
wallet_resource.id = "wallet.resource";
wallet_resource.entities = {"wallet.entity"};
wallet_resource.ui_path = "/ui/wallet/panel";

Component Level（组件层）

可分发的模块，包含完整的业务功能：

ComponentDescriptor economy_component;
economy_component.id = "economy-system";
economy_component.resources = {"wallet.resource", "currency.resource"};
economy_component.version = "0.1.0";

ID 引用模式

设计理念

传统的对象传递会携带完整状态，导致网络开销大且线程安全问题。Croupier 采用 ID 引用模式：

// 传统方式（不推荐）
Wallet wallet = GetWallet(player_id);  // 包含完整状态
ProcessTransfer(wallet, to_player, amount);

// ID 引用方式（推荐）
std::string wallet_id = "wallet.entity:" + player_id;
ProcessTransferById(wallet_id, to_player, amount);

优势

优势说明
🚀 极致性能网络传输只有几十字节
🛡️ 线程安全无状态函数，天然支持并发
🔄 水平扩展函数可以部署到任意节点
🧩 松耦合对象管理与业务逻辑完全分离

通信架构

┌─────────────────┐
│   Game Server   │
│   (C++ SDK)     │
└────────┬────────┘
         │ gRPC
         ▼
┌─────────────────┐
│  Croupier Agent │ (本地/远程)
└────────┬────────┘
         │ mTLS
         ▼
┌─────────────────┐
│  Croupier Server│ (控制面)
└─────────────────┘

连接流程

  1. 初始化: 创建 CroupierClient，配置连接参数
  2. 注册: 向 Agent 注册函数和虚拟对象
  3. 心跳: 定期发送心跳保持连接
  4. 调用: 接收并处理来自 Agent 的函数调用请求
  5. 重连: 连接断开时自动重连并重新注册

核心组件

CroupierClient

主客户端类，负责：

  • 连接管理
  • 函数注册
  • 虚拟对象注册
  • 生命周期管理

GrpcService

gRPC 通信层，负责：

  • Protobuf 消息序列化/反序列化
  • gRPC 通道管理
  • 异步调用处理

ConfigManager

配置管理器，负责：

  • 配置文件加载
  • 环境变量覆盖
  • 配置验证

数据流

请求流

┌─────────┐    ┌──────────┐    ┌─────────┐
│  Web UI │───▶│  Server  │───▶│  Agent  │
└─────────┘    └──────────┘    └────┬────┘
                                    │
                                    ▼
                              ┌──────────┐
                              │C++ SDK   │
                              │Function  │
                              └──────────┘

响应流

┌──────────┐                    ┌────┐
│C++ SDK   │───Response─────────▶│Agnt│
│Function  │                    └────┘
└──────────┘                      │
                                  ▼
                            ┌──────────┐
                            │  Server  │
                            └────┬─────┘
                                 │
                                 ▼
                           ┌─────────┐
                           │  Web UI │
                           └─────────┘

线程模型

SDK 采用单线程事件循环模型：

  • 主线程: 运行 Serve() 方法，处理所有网络 I/O
  • 工作线程: 可选，用于执行 CPU 密集型任务
// 单线程模式（默认）
client.Serve();  // 阻塞在当前线程

// 多线程模式
std::thread server_thread([&client]() {
    client.Serve();
});
// ... 其他工作
server_thread.join();

错误处理

错误传播

Function Handler
       ↓
   Error JSON
       ↓
gRPC Status
       ↓
Agent
       ↓
Server
       ↓
Web UI

错误格式

return R"({
    "success": false,
    "error": {
        "code": "INSUFFICIENT_BALANCE",
        "message": "玩家余额不足"
    }
})";