Croupier C++ SDKCroupier C++ SDK
指南
API 参考
示例
配置
Croupier 主项目
  • Go SDK
  • Java SDK
  • JavaScript SDK
  • Python SDK
GitHub
指南
API 参考
示例
配置
Croupier 主项目
  • Go SDK
  • Java SDK
  • JavaScript SDK
  • Python SDK
GitHub
  • API 参考

    • API 参考
    • CroupierClient API 详解
    • ClientConfig API 详解
    • 函数 API 详解
    • 虚拟对象 API 详解

ClientConfig API 详解

ClientConfig 结构定义了 Croupier 客户端的所有配置选项。

结构定义

namespace croupier::sdk {

struct ClientConfig {
    // 基础连接配置
    std::string agent_addr = "127.0.0.1:19090";
    std::string game_id;
    std::string env = "development";
    std::string service_id = "cpp-service";

    // 超时配置
    int timeout_seconds = 30;

    // TLS 配置
    bool insecure = true;
    struct Security {
        std::string cert_file;
        std::string key_file;
        std::string ca_file;
        std::string server_name;
    } security;

    // 重连配置
    bool auto_reconnect = true;
    int reconnect_interval_seconds = 5;
    int reconnect_max_attempts = 0;  // 0 = 无限重试

    // 认证配置
    struct Auth {
        std::string token;
        std::map<std::string, std::string> headers;
    } auth;
};

} // namespace croupier::sdk

配置字段详解

基础连接配置

agent_addr

Agent 服务器地址,格式为 host:port。

config.agent_addr = "127.0.0.1:19090";           // 本地 Agent
config.agent_addr = "croupier-agent:19090";      // Kubernetes 服务
config.agent_addr = "10.0.0.5:19090";            // IP 地址

game_id

游戏/项目唯一标识符。

config.game_id = "my-mmorpg";
config.game_id = "production-game-2024";

env

部署环境标识。

config.env = "development";  // 开发环境
config.env = "staging";      // 预发布环境
config.env = "production";   // 生产环境

service_id

服务实例标识符,用于区分同一服务的多个实例。

config.service_id = "game-server-01";
config.service_id = "backend-service-" + std::to_string(GetProcessID());

超时配置

timeout_seconds

网络操作超时时间(秒)。

config.timeout_seconds = 30;   // 默认 30 秒
config.timeout_seconds = 60;   // 1 分钟
config.timeout_seconds = 300;  // 5 分钟(长操作)

TLS 配置

insecure

是否跳过 TLS 验证(仅用于开发)。

config.insecure = true;   // 开发环境:跳过验证
config.insecure = false;  // 生产环境:启用 TLS

security.cert_file

客户端证书文件路径。

config.security.cert_file = "/etc/tls/client.crt";
config.security.cert_file = "./certs/client-cert.pem";

security.key_file

客户端私钥文件路径。

config.security.key_file = "/etc/tls/client.key";
config.security.key_file = "./certs/client-key.pem";

security.ca_file

CA 证书文件路径。

config.security.ca_file = "/etc/tls/ca.crt";
config.security.ca_file = "./certs/ca-bundle.crt";

security.server_name

TLS 服务器名称验证(SNI)。

config.security.server_name = "croupier.internal";
config.security.server_name = "agent.production.com";

重连配置

auto_reconnect

是否自动重连。

config.auto_reconnect = true;   // 连接断开时自动重连
config.auto_reconnect = false;  // 连接断开时退出

reconnect_interval_seconds

重连尝试间隔(秒)。

config.reconnect_interval_seconds = 5;   // 每 5 秒重试一次
config.reconnect_interval_seconds = 30;  // 每 30 秒重试一次

reconnect_max_attempts

最大重连次数(0 表示无限重试)。

config.reconnect_max_attempts = 0;    // 无限重试
config.reconnect_max_attempts = 10;   // 最多尝试 10 次
config.reconnect_max_attempts = -1;   // 不重连

认证配置

auth.token

JWT 认证令牌。

config.auth.token = "Bearer eyJhbGciOiJIUzI1NiIs...";

auth.headers

额外的 HTTP 头部。

config.auth.headers = {
    {"X-Game-Version", "0.1.0"},
    {"X-Service-Region", "us-west-2"},
    {"X-Cluster", "production-01"}
};

配置加载

从文件加载

#include "croupier/sdk/config/client_config_loader.h"

ClientConfigLoader loader;
ClientConfig config = loader.LoadFromFile("./config.json");

从环境变量覆盖

ClientConfig config = loader.LoadWithEnvironmentOverrides(
    "./config.json",
    "CROUPIER_"  // 环境变量前缀
);

// 环境变量:
// CROUPIER_GAME_ID=override-game
// CROUPIER_ENV=staging
// CROUPIER_AGENT_ADDR=10.0.0.5:19090

配置验证

ClientConfigLoader loader;
auto errors = loader.ValidateConfig(config);

if (!errors.empty()) {
    for (const auto& error : errors) {
        std::cerr << "配置错误: " << error << std::endl;
    }
    return 1;
}

配置示例

开发环境

{
  "game_id": "dev-game",
  "env": "development",
  "service_id": "dev-backend",
  "agent_addr": "127.0.0.1:19090",
  "insecure": true,
  "timeout_seconds": 30,
  "auto_reconnect": true
}

生产环境

{
  "game_id": "prod-game",
  "env": "production",
  "service_id": "prod-backend-01",
  "agent_addr": "croupier-agent.internal:19090",
  "insecure": false,
  "timeout_seconds": 60,
  "security": {
    "cert_file": "/etc/tls/client.crt",
    "key_file": "/etc/tls/client.key",
    "ca_file": "/etc/tls/ca.crt",
    "server_name": "croupier.internal"
  },
  "auth": {
    "token": "Bearer ${JWT_TOKEN}",
    "headers": {
      "X-Game-Version": "2.1.0",
      "X-Service-Region": "us-west-2"
    }
  },
  "auto_reconnect": true,
  "reconnect_interval_seconds": 10,
  "reconnect_max_attempts": 0
}

Kubernetes 环境

{
  "game_id": "${GAME_ID}",
  "env": "production",
  "service_id": "${HOSTNAME}",
  "agent_addr": "croupier-agent:19090",
  "insecure": false,
  "security": {
    "cert_file": "/etc/tls/client.crt",
    "key_file": "/etc/tls/client.key",
    "ca_file": "/etc/tls/ca.crt"
  },
  "auth": {
    "token": "Bearer ${JWT_TOKEN}"
  }
}
在 GitHub 上编辑此页
最后更新: 2026/1/9 14:14
Prev
CroupierClient API 详解
Next
函数 API 详解