WebSocket 客户端 DLL 模块设计说明（基于 WebSocket++ + Boost.Asio）

WebSocket 客户端 DLL 模块设计说明（基于 WebSocket++ + Boost.Asio）

📌 目录

• 一、模块总览
• 二、导出接口说明（EXPORTS）
• 三、状态变量功能解读
• 四、连接启动流程详解
• 五、事件回调说明
• 六、消息发送流程
• [七、心跳与断连 JSON 数据格式](#七、心跳与断连 JSON 数据格式)
• 八、自动重连机制
• 九、首次连接与重连回调机制对比
• 十、完整调用示例

---

一、模块总览

本模块为一个跨平台可复用的 WebSocket 客户端库，支持 C 风格导出接口，供第三方程序以 DLL 动态链接方式调用。

💡 模块组成

┌──────────────────────────────┐
│ WebSocketClientExport.h/cpp │ ← DLL 导出函数（外部调用）
├──────────────────────────────┤
│ WebSocketClientLibrary.h/cpp│ ← C++ 单例封装（中转层）
├──────────────────────────────┤
│ WebSocketImpl.h/cpp         │ ← 实现类（使用 WebSocket++ + Boost.Asio）
└──────────────────────────────┘

---

二、导出接口说明（EXPORTS）

ini复制代码LIBRARY "WebScoket"

EXPORTS
    CreateWebSocketClient          @1  NONAME
    StartWebSocketClient           @2  NONAME
    StopWebSocketClient            @3  NONAME
    RegisterMessageCallback        @4  NONAME
    RegisterReconnectCallback      @5  NONAME
    SendHeartbeat                  @6  NONAME
    SendDisconnectNotice           @7  NONAME
    IsWebSocketClientConnecting    @8  NONAME
    IsWebSocketClientConnected     @9  NONAME
    RegisterConnectedCallback      @10 NONAME

---

三、状态变量功能解读

变量名	类型	作用说明
is_connected_	std::atomic<bool>	是否连接成功（open 状态）
is_connecting_	std::atomic<bool>	是否正在连接中
connect_failed_	std::atomic<bool>	本次连接是否失败
user_requested_stop_	std::atomic<bool>	标记是否是手动断开
is_reconnecting_	std::atomic<bool>	当前是否处于自动重连中
auto_reconnect_enabled_	bool	是否启用自动重连逻辑
has_reported_reconnect_result_	std::atomic<bool>	避免 reconnect_callback 多次调用
last_disconnect_reason_	enum 枚举	上一次断开的原因
last_uri_	std::string	上次连接地址，便于重连复用

---

四、连接启动流程详解

A[调用 StartWebSocketClient()] --> B[设置连接标志 is_connecting_]
B --> C[获取 ws 连接对象]
C --> D{是否成功？}
D -- 否 --> E[返回 false]
D -- 是 --> F[发起连接 ws_client.connect(con)]
F --> G[创建线程 run io_context]
G --> H[等待连接成功（最多 3 秒）]
H --> I{is_connected_ 是否为 true}
I -- 否 --> E
I -- 是 --> J[返回 true，连接建立成功]

---

五、事件回调说明

✅ on_open

• 设置状态 is_connected_ = true
• 若当前是重连阶段，则回调 reconnect_callback_(true)
• 否则（首次连接）调用 connected_callback_()

✅ on_fail

• 设置 connect_failed_ = true
• 若当前是重连阶段，则回调 reconnect_callback_(false)

✅ on_close

• 若 user_requested_stop_ == true，表示手动断开 → 不自动重连
• 若不是手动断开，等待 30 秒后触发自动重连 StartWebSocketClient(last_uri_, true)

---

六、消息发送流程

void WebSocketImpl::Send(const std::string& message)

步骤：

1. 判断是否已连接 is_connected_
2. 获取连接对象 get_con_from_hdl
3. 检查状态是否为 open
4. 使用 ws_client.send() 发送消息

---

七、心跳与断连 JSON 数据格式

🔁 心跳请求（msgType: 1）

{
  "msgType": 1,
  "deviceKey": "xxx",
  "tgt": "xxx",
  "sndaId": "xxx"
}

❌ 主动断连通知（msgType: 2）

{
  "msgType": 2,
  "deviceKey": "xxx",
  "tgt": "xxx",
  "sndaId": "xxx"
}

---

八、自动重连机制

✅ 触发条件：

• 非 Stop() 主动断开
• 设置了 auto_reconnect_enabled_ = true
• 当前不是重连中（避免重复）

✅ 重连逻辑：

std::thread([this] {
    ::Sleep(30000); // 延迟 30 秒
    bool success = this->StartWebSocketClient(this->last_uri_, true);
    if (!success && reconnect_callback_) {
        reconnect_callback_(false);
    }
}).detach();

---

九、首次连接与重连回调机制对比

情况	回调函数	是否只触发一次
首次连接成功	connected_callback_()	是
重连成功	reconnect_callback_(true)	是（防止重复通过标志）
重连失败	reconnect_callback_(false)	是（只触发一次）

通过 has_reported_reconnect_result_ 原子变量保证任意一次连接尝试最多调用一次回调。

---

十、完整调用示例

WebSocketHandle* handle = nullptr;

// 创建客户端
CreateWebSocketClient(&handle);

// 注册回调
RegisterMessageCallback(handle, [](const char* msg) {
    printf("收到消息：%s\n", msg);
});

RegisterConnectedCallback(handle, []() {
    printf("首次连接成功\n");
});

RegisterReconnectCallback(handle, [](bool success) {
    printf("重连%s\n", success ? "成功" : "失败");
});

// 启动连接（支持重连）
StartWebSocketClient(handle, "ws://127.0.0.1:9000/ws", true);

// 心跳
SendHeartbeat(handle, "TGT-XYZ", "device-key", "user-id");

// 主动断连
SendDisconnectNotice(handle, "TGT-XYZ", "device-key", "user-id");

// 查询连接状态
bool isConnected = IsWebSocketClientConnected(handle);
bool isConnecting = IsWebSocketClientConnecting(handle);

// 停止连接
StopWebSocketClient(handle);