WebSocket 客户端 DLL 模块设计说明（基于 WebSocket++ + Boost.Asio）
WebSocket 客户端 DLL 模块设计说明（基于 WebSocket++ + Boost.Asio）
📌 目录
- 一、模块总览
- 二、导出接口说明（EXPORTS）
- 三、状态变量功能解读
- 四、连接启动流程详解
- 五、事件回调说明
- 六、消息发送流程
- 七、心跳与断连 JSON 数据格式
- 八、自动重连机制
- 九、首次连接与重连回调机制对比
- 十、完整调用示例
一、模块总览
本模块为一个跨平台可复用的 WebSocket 客户端库，支持 C 风格导出接口，供第三方程序以 DLL 动态链接方式调用。
💡 模块组成
┌──────────────────────────────┐
│ WebSocketClientExport.h/cpp │ ← DLL 导出函数（外部调用）
├──────────────────────────────┤
│ WebSocketClientLibrary.h/cpp│ ← C++ 单例封装（中转层）
├──────────────────────────────┤
│ WebSocketImpl.h/cpp │ ← 实现类（使用 WebSocket++ + Boost.Asio）
└──────────────────────────────┘
二、导出接口说明（EXPORTS）
ini复制代码LIBRARY "WebScoket"EXPORTSCreateWebSocketClient @1 NONAMEStartWebSocketClient @2 NONAMEStopWebSocketClient @3 NONAMERegisterMessageCallback @4 NONAMERegisterReconnectCallback @5 NONAMESendHeartbeat @6 NONAMESendDisconnectNotice @7 NONAMEIsWebSocketClientConnecting @8 NONAMEIsWebSocketClientConnected @9 NONAMERegisterConnectedCallback @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)
步骤：
- 判断是否已连接
is_connected_ - 获取连接对象
get_con_from_hdl - 检查状态是否为
open - 使用
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);