C++ 快速接入

WuKongEasySDK-CPP 参考 JS v2.0.4 实现 WebSocket JSON-RPC CONNECT、在线收发、自动 RECVACK、心跳、重连和自定义事件。使用 C++17、Boost.Beast、OpenSSL 与 nlohmann/json。

1. 先准备 Alice 和 Bob

按认证与 Token让受信业务后端分别提供两人的 uid、token 和 websocketUrl。客户端只连接 Gateway，不调用 Product HTTP 管理接口。设备线路值为 APP 0、WEB 1、PC/Desktop 2；C++ 默认 Desktop，后端保存 Token 时必须使用相同设备类别。

开发机默认示例地址为 ws://127.0.0.1:5200，路径是 /。如果 listener 或代理配置了 /ws，才使用 ws://127.0.0.1:5200/ws。跨机器时用客户端实际可达地址，生产使用 wss://。通用环境步骤见运行官方示例。

2. 推荐：vcpkg + CMake

先安装 vcpkg， 将 VCPKG_ROOT 指向安装目录。准备 Git、CMake 3.20+ 和 C++17 编译器： Windows 使用 Visual Studio 2022，macOS 使用 Xcode 命令行工具，Linux 使用 GCC/Clang。 验证使用的 vcpkg 工具版本为 04a9d8e5212d01ee1dd9478eadd9caade4f8b0d4。

在你的应用目录创建 vcpkg.json：

{"dependencies": ["wukong-easy-sdk"]}

vcpkg-configuration.json:

{
  "default-registry": {
    "kind": "git",
    "repository": "https://github.com/microsoft/vcpkg",
    "baseline": "04a9d8e5212d01ee1dd9478eadd9caade4f8b0d4"
  },
  "registries": [
    {
      "kind": "git",
      "repository": "https://github.com/WuKongIM/WuKongEasySDK-CPP.git",
      "baseline": "63ec99d34c7605b64e2173d201639042e0e49de9",
      "packages": [
        "wukong-easy-sdk"
      ]
    }
  ]
}

在自己的 main.cpp 旁添加 CMakeLists.txt：

cmake_minimum_required(VERSION 3.20)
project(my_app LANGUAGES CXX)
find_package(WuKongEasySDK 0.1 CONFIG REQUIRED)
add_executable(my_app main.cpp)
target_link_libraries(my_app PRIVATE WuKongEasySDK::WuKongEasySDK)

# Linux / macOS
cmake -S . -B build -DCMAKE_TOOLCHAIN_FILE="$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake" -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release --parallel 2

# Windows / Visual Studio 2022
cmake -S . -B build -DCMAKE_TOOLCHAIN_FILE="$env:VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake" -DVCPKG_TARGET_TRIPLET=x64-windows
cmake --build build --config Release --parallel 2

vcpkg 会自动安装 SDK、Boost、OpenSSL 和 JSON，无需手动逐个安装。 首次构建可能需要编译依赖并耗时数分钟，这不是预编译压缩包。 SDK port 为静态库；Windows 使用 x64-windows 时，分发应用需要携带构建时复制到程序旁的依赖 DLL。

这是 WuKongIM 在本仓库维护的公开 Git registry，不是微软默认目录中的包， 因此必须同时提供 registry 配置和依赖声明。SDK 源码固定为 3e367a908f42385ab9306f9708b7456399cace7d，与 registry baseline 分别固定。 将两个 JSON 文件提交到应用仓库；已有 manifest 的项目应合并字段，不要覆盖原有依赖。

截至 2026-09-08，微软默认目录的收录申请已提交到 microsoft/vcpkg#53837，尚未合并。申请中的 port 从正式 v0.1.0 标签构建；上面的安装方式仍使用 WuKongIM 自定义 registry，当前不能省略 vcpkg-configuration.json。

独立消费端示例 · Registry 维护说明

备选：下载预编译包，解压接入

希望跳过依赖编译时，从 C++ SDK v0.1.0 Release 下载匹配的 ZIP 和 SHA256SUMS，验证 SHA-256 后解压。只需准备 CMake 3.20+ 和匹配的 C++ 开发环境，无需另装 vcpkg。

包名统一以 WuKongEasySDK-CPP-0.1.0- 开头。包内包含 Debug/Release 静态 SDK、Boost/JSON 头文件、OpenSSL 库、许可文件和最小示例。在解压目录执行：

# Linux / macOS
cmake -S example -B build -DCMAKE_TOOLCHAIN_FILE="$PWD/wukong-sdk.cmake" -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release --parallel 2
ctest --test-dir build -C Release --output-on-failure

# Windows / Visual Studio 2022
cmake -S example -B build -A x64 -DCMAKE_TOOLCHAIN_FILE="$PWD/wukong-sdk.cmake"
cmake --build build --config Release --parallel 2
ctest --test-dir build -C Release --output-on-failure

wukong_example 验证初始化和销毁；wukong_chat 可使用下节的 Alice/Bob 凭据交互收发。接入自己的应用时，保持上面的 find_package 和 target_link_libraries，将 CMake 的 toolchain 指向解压目录中的 wukong-sdk.cmake。

Unix 的 OpenSSL 为静态库；Windows 使用包内 DLL，发布应用时携带 CMake 复制到可执行文件旁的 DLL，并安装匹配的 Visual C++ Redistributable。Debug 运行库只用于开发。预编译包使用 WSS 时，通过 Options::caFile（交互示例为 WKIM_CA_FILE）显式提供受维护的 CA 证书包，不要依赖 OpenSSL 构建机的默认证书路径。

BUILD_INFO.json 记录 SDK 源码、registry 和打包提交；FILES.sha256.json 校验解压内容。升级时下载到新目录、校验哈希、使用新的 build 目录重新构建和验收，将应用与依赖一起更新，保留旧版本以便回滚。其他编译器、架构、CRT 或依赖组合使用 vcpkg/源码方式，不能任意混用二进制依赖。

三个平台的独立任务下载 ZIP 后，在新的目录编译 Debug/Release 消费端并运行生命周期与 26 项 WS/WSS 场景；Linux/macOS 另以固定 WuKongIM 服务端验收双向消息、重连和在线清理。Windows 的证据为协议夹具，未运行 Windows 服务端。完整兼容范围和发布验收见 预编译包说明。

备选：获取和编译固定源码

要求 CMake 3.20+、C++17 编译器、Boost 1.74+、OpenSSL 1.1.1+、nlohmann/json 3.11+。实际产品应选择仍受维护并包含安全修复的版本。

git clone https://github.com/WuKongIM/WuKongEasySDK-CPP.git
cd WuKongEasySDK-CPP
git checkout 3e367a908f42385ab9306f9708b7456399cace7d

# macOS
brew install cmake boost openssl@3 nlohmann-json
# Ubuntu / Debian
sudo apt-get install g++ cmake libboost-dev libssl-dev nlohmann-json3-dev

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release --parallel 2
ctest --test-dir build -C Release --output-on-failure

只执行与你的平台匹配的依赖安装命令。缺少 JSON 系统包时 CMake 获取固定的上游 3.11.3 commit；离线构建请预装依赖并设置 WUKONG_FETCH_JSON=OFF。

Windows 使用 Visual Studio 2022 和 vcpkg，仓库 vcpkg.json 固定 baseline：

git -C "$env:VCPKG_ROOT" fetch origin 04a9d8e5212d01ee1dd9478eadd9caade4f8b0d4
cmake -S . -B build -DCMAKE_TOOLCHAIN_FILE="$env:VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake" -DVCPKG_TARGET_TRIPLET=x64-windows
cmake --build build --config Release --parallel 2
ctest --test-dir build -C Release --output-on-failure

在应用 CMake 中接入源码：

add_subdirectory(external/WuKongEasySDK-CPP)
target_link_libraries(my_app PRIVATE WuKongEasySDK::WuKongEasySDK)

也可执行 cmake --install build --config Release --prefix /path/to/sdk-prefix，在下游用 find_package(WuKongEasySDK 0.1 CONFIG REQUIRED)，并将 CMAKE_PREFIX_PATH 指向安装目录。静态库导出保留第三方依赖；Windows 分发需要携带所用的动态依赖。

3. 先运行交互示例

两个终端分别通过环境变量 WKIM_TOKEN 提供各自后端签发的 Token，然后运行：

# Alice 的终端
./build/wukong_chat ws://127.0.0.1:5200 alice bob
# Bob 的终端
./build/wukong_chat ws://127.0.0.1:5200 bob alice

两端都显示 Connected 后输入文本，观察对端的 Message，再反向发送。SEND completed 代表 SENDACK 成功。输入 /quit 断开并释放资源。Windows 可执行文件位于 build/Release/wukong_chat.exe。

示例主动展示业务消息内容；SDK 自身不输出日志。不要把示例终端内容直接接入生产日志采集。

4. 在应用中连接、监听和发送

下面代码从环境取得 Alice 的 Token，发送一条消息，等待按 Enter 后退出。Bob 必须已经在线。

#include <wukong/wkim.hpp>
#include <cstdlib>
#include <iostream>

int main() {
    const char* token = std::getenv("WKIM_TOKEN");
    if (!token) return 2;
    try {
        wukong::Options options;
        options.connectionTimeout = std::chrono::seconds(10);
        options.requestTimeout = std::chrono::seconds(15);
        wukong::WKIM im("ws://127.0.0.1:5200", {"alice", token}, options);

        auto messageListener = im.on(wukong::WKIMEvent::Message,
            [](const wukong::Json& message) {
                // Copy message.at("payload") into your application's UI/event queue.
                // This callback runs on the SDK I/O thread.
                (void)message;
            });
        auto errorListener = im.on(wukong::WKIMEvent::Error,
            [](const wukong::Json&) {
                // Dispatch a sanitized failure state to the application.
            });

        im.connect().get();
        wukong::SendOptions sendOptions;
        // Supply a stable clientMsgNo when the application needs reconciliation.
        auto ack = im.send("bob", wukong::WKIMChannelType::Person,
                          {{"type", 1}, {"content", "Hello from C++!"}},
                          sendOptions).get();
        if (ack.reasonCode == 1) std::cout << "SEND completed\n";
        std::cin.get();

        im.off(messageListener);
        im.off(errorListener);
        im.disconnect().get();
        im.destroy().get();
    } catch (const wukong::Error&) {
        std::cerr << "EasySDK operation failed\n";
        return 1;
    }
}

connect() 只在鉴权完成后成功。群聊使用 WKIMChannelType::Group，由业务后端预先建立 Channel 和成员关系。Payload 接受 JSON 对象或数组，按 UTF-8 JSON 编码为 Base64；接收兼容对象、JSON 文本和 Base64 JSON。消息 ID 保持字符串，避免 64 位整数精度损失。

发送结果包括 messageId、messageSeq 和 reasonCode。接收事件还包含 header、秒级 timestamp、channelId、channelType、fromUid 和 payload。自动 RECVACK 携带 messageId 与 messageSeq；这是传输确认，不能代替业务已读。发送成功、对端接收和业务处理的区别见消息收发。

5. 管理线程与账号生命周期

每个实例拥有一个身份和一条 I/O 线程，没有全局单例。公共操作支持应用线程并发调用；事件在 I/O 线程串行分发。回调可以发起异步操作，但不能在回调中等待 SDK future。将 UI 更新和耗时工作交给应用自己的执行器。

回调捕获的数据应活到客户端关闭之后。捕获 SDK 自身时使用 weak_ptr 防止引用环。移除监听后仍需完成关闭，才能释放被捕获的应用状态。SDK 直接取消 socket，清理不等待对端的 close 握手。

6. 心跳、重连、错误与 WSS

默认连接总超时 10 秒，请求超时 15 秒，心跳间隔 25 秒，Pong 超时 10 秒。同 ID 的 result: null 满足心跳确认。曾成功鉴权的连接意外断开后最多重试 5 次，指数退避从 1 秒增长到最多 30 秒并加入抖动。首次连接失败交还调用方；鉴权失败、服务端主动断开、畸形协议和手动退出停止自动重试。

默认最多 1,024 个待处理请求，命令队列和 WebSocket 写队列分别限制为 4 MiB，单条线路消息限制为 1 MiB。容量不足返回 ErrorCode::QueueFull；本地错误使用负数，服务端原因码保留在 Error::code()。超时和断线可能导致发送结果未知，应按 clientMsgNo 对账。SDK 不离线排队或自动重发。

WSS 默认启用证书链和主机名验证，最低 TLS 1.2。私有 CA 可通过 Options::caFile 指定 PEM 文件；控制台读取 WKIM_CA_FILE。没有跳过证书校验的配置。SDK 默认静默，不记录 Token、Payload、URL、原始帧、服务端响应文本或底层异常对象。

通过 Event::CustomEvent 接收 id、type、毫秒级 timestamp 和 data；JSON 字符串 data 会被解析。事件接收能力仍取决于服务端是否产生对应通知。

正式包三节点验收

公开的 v0.1.0 Linux x64 和 macOS arm64 压缩包已通过独立消费端的 Debug/Release 验收，服务端固定为 WuKongIM 5f5003778ccee6786591ed9968a5185e9213ea55：三节点集群、256 个 Hash Slot、12 个逻辑 Slot、三个 Slot 副本，开启 Token 鉴权。C++ 和真实 JS 2.0.4 SDK 经带临时可信证书的 WSS 分别连接不同节点，验证双向消息及 SENDACK/接收消息标识对应、回包丢失后的请求超时、断网后不自动重发 SEND、接入节点退出与重启、存活节点持续通信，以及退出后的在线路由清理。查看精确版本、验收记录和复现方法及通过的 Linux/macOS 工作流。

超时或连接错误不代表消息没有送达。故障测试中，接收方已收到消息，发送方却无法收到 SENDACK；应用应结合 clientMsgNo 和业务后端的历史记录核对不确定结果。重连会回到配置的 Gateway URL，不会自动发现替代地址或同步离线历史。

本次是同一台主机上的三个进程和 TLS 终止代理的有界测试，不覆盖跨主机网络分区、生产 CA 配置、Windows 服务端行为、容量或长时间稳定性。

上线前检查

早期源码验收另外覆盖协议与 WS/WSS 测试、内存与未定义行为检测、安装后的下游编译，以及真实单节点集群上的双向消息、重连、错误 Token 拒绝和在线清理。上面的正式包三节点验收单独记录产物和服务端版本，不能把源码测试归于其他二进制版本。

继续验收实际目标系统、真实网络 WSS、代理路径、Token 轮换、重复投递、容量、监控与回滚。SDK 不提供离线恢复、会话、未读或推送；这些需求请使用完整版 SDK。回到 WuKongEasySDK 概览，或继续上线检查。