1. 功能库跑通回显不算上线:WebSocket++ 双端 Demo 最怕「假在线」
WebSocket++ 是个 header-only 的 C++ 功能库,服务端和客户端各写几十行,一条实时通信的回显链路当天就能跑起来。也正因为它把握手、帧解析、关闭流程都封装了,很容易给人「连接建立就万事大吉」的错觉:日志里连接数一直是 1,界面也显示在线,直到现场的客户端断电重启,服务端还在往一个早已消失的句柄发消息,业务侧毫不知情。这个功能库替我们省掉的是协议细节,没省掉的是半开连接、定时器生命周期和重连节奏这三件事。下面这条线只做一件事:在已经跑通的双端 Demo 上补心跳与断线重连,让它扛得住现场网络抖动。适合 Demo 已跑通、准备接真实客户端的 C++ 开发者。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 功能库接入与最小闭环:init_asio 之后先让一条回显链路稳定跑起来
把 Demo 跑到能接真实客户端,第一步是先把启动顺序和事件循环固定下来。很多连接问题追到最后,根因都是 init_asio 之后又从别的线程操作 endpoint,或者定时器排在 run 之后根本没进循环。这一段先把服务端和客户端各自的最小闭环摆出来,后面心跳和重连都挂在这条闭环上。
2.1 事件循环归谁管:不要在定时器里另起 sleep 线程
WebSocket++ 服务端调用 init_asio 之后,run 会进入事件循环;连接回调、定时器回调、ping/pong 的处理都在这个循环里派发。新手常见的写法是「心跳我自己起个 std::thread,sleep 一秒发一次 ping」,Demo 阶段能工作,一旦接入真实客户端就会暴露问题:业务线程手里的连接句柄可能已经被事件循环回收,ping 出去就是一次未定义行为,表现是偶发崩溃或者日志里出现莫名其妙的关闭帧。
我的习惯是心跳、超时判定、重连排期全部用库的定时器接口排进同一个循环,业务线程只负责投递任务,不直接碰连接句柄。这样做的代价是定时器回调里不能做阻塞操作,一次回调卡住,整个事件循环的心跳都会跟着延迟,半开连接的判定也会失准。所以回调里只做「遍历连接、发 ping、记录时间戳」这三件轻活,重活丢给业务队列。
日志是这条闭环上最便宜的可观测手段。把库的日志级别调高,先看清握手成功、关闭码、失败原因这三类记录,再谈心跳。很多「连接莫名其妙断了」的问题,在高日志级别下都能看到是服务端主动 close 还是对端关闭。
2.2 服务端启动顺序:端口、监听与事件循环的先后不能乱
服务端的启动顺序是有讲究的,init_asio 必须最先,监听和 accept 在它之后,run 之前要把所有定时器排进去,run 之后代码就阻塞在事件循环里了。
cpp复制using websocketpp::lib::error_code;
websocketpp::server<websocketpp::config::asio> srv;
srv.init_asio(); // 装 Asio transport、建 io_service,必须最先做
srv.set_reuse_addr(true); // 服务重启时少踩端口被 TIME_WAIT 占住的坑
srv.listen(port); // port 来自配置,不写死在源码里
srv.start_accept(); // 开始接受连接,此时还没进入事件循环
// 心跳、超时检查都要在 run 之前排进循环
srv.run(); // 阻塞,直到 srv.stop()
逻辑说明:init_asio 负责把传输层装好,后面的 listen 只创建监听 socket,start_accept 才开始接受连接,真正驱动这一切的是 run。顺序反了,典型现象是 accept 不报错但连接永远进不来。
参数说明:port 从配置文件或启动参数读入,不写死在源码里,现场换端口不用重新编译;set_reuse_addr 建议常开,服务重启后立刻能重新绑定;回调里不要做磁盘写入或长耗时计算,事件循环是单线程在跑。
2.3 客户端连接与 fail_handler 的落点:两类失败不能混在一起
客户端这边最容易犯的错,是把 URL 解析失败和网络连接失败塞进同一个重试分支。前者是配置错误,重试一万次也不会成功;后者才是网络抖动,值得退避重连。
cpp复制websocketpp::client<websocketpp::config::asio> cli;
cli.init_asio();
websocketpp::lib::error_code ec;
auto con = cli.get_connection(url, ec);
if (ec) {
// URL/协议写错属于配置错误,直接退出,别丢进重连流程
return;
}
cli.connect(con);
cli.set_fail_handler([](websocketpp::connection_hdl hdl) {
// 网络失败、握手超时都会落到这里,重连入口就放这
});
cli.run();
逻辑说明:get_connection 返回的 error_code 是「连接对象都没造出来」级别的错误,fail_handler 收到的是「对象有了但连不上」级别的错误。两者混在一起,日志里就会看到重连计数器一路涨、配置却一直错。
参数说明:url 里带不带路径、服务端有没有注册对应路径的处理器,都要提前对齐;fail_handler 里只记录失败原因和触发退避排期,不要在里面同步调用连接接口,否则失败回调会自己套自己,形成同步递归。
3. 心跳与断线重连:把一次性 Demo 变成会自愈的实时服务
Demo 的回显链路跑通之后,真正的分水岭是「连接断了以后会怎样」。WebSocket++ 不会自动判断半开连接,也不会帮你重连;它只提供定时器和回调,剩下的策略得自己定。这一章把心跳循环和客户端退避重连拆开写,两段都能直接落到代码里。
3.1 set_timer 只触发一次:回调里必须再排下一次
这是我在这个功能库上踩过最隐蔽的坑。set_timer 不是周期定时器,它触发一次就结束,回调里如果忘了重新注册,心跳只会发一轮,之后连接看起来还在,实际上再没有任何保活报文。
cpp复制// 心跳循环:handler 的生命周期要跟服务端一样长
struct Heartbeat {
websocketpp::server<websocketpp::config::asio> &srv;
explicit Heartbeat(websocketpp::server<websocketpp::config::asio> &s) : srv(s) {}
void arm() {
srv.set_timer(1000, [this](websocketpp::lib::error_code const &ec) {
if (ec) {
return; // 定时器被取消(服务停止)时不再重排
}
for (auto hdl : srv.get_connections()) {
srv.ping(hdl, "hb"); // 控制帧载荷保持短小
}
arm(); // set_timer 只触发一次,这里再排下一轮
});
}
};
逻辑说明:arm 先排一轮,回调里遍历当前连接发 ping,然后调自己再排下一轮,形成循环;ec 非空说明定时器被取消或出错,这时直接返回,避免服务停了还在重排。把 handler 放进一个生命周期跟服务端一样长的结构体里,是为了避开 lambda 捕获自身导致的悬垂引用。
参数说明:1000 是毫秒,也就是一秒一轮;ping 的载荷用 "hb" 这种短字符串,控制帧载荷本身很小,别把业务 JSON 塞进去;如果业务对断线更敏感,可以把间隔调小,但要跟后面说的超时判定一起改,只改一边等于没改。
3.2 遍历连接集合的边界:ping 发出去之后要看什么
get_connections 返回的是当前连接句柄的集合,它不保证遍历期间每个句柄都还有效。事件循环里可能正好有连接在关闭,你的 ping 就打到了一条正在收尸的连接上。这个功能库通常不会因此崩掉,但会产生一次失败日志,如果业务侧把「ping 失败」直接当成「客户端掉线」,就会误杀。
处理办法是:遍历时只发 ping,不在循环里做任何可能阻塞或抛异常的操作;把连接的有效性判断放在关闭回调和 pong 回调里,用一个自己的在线表记录每个连接最后一次收到 pong 的时间。这样 ping 只是一个探针,判定逻辑集中在时间戳比较上,出问题时有据可查。
集合的大小本身也是个观察指标:正常情况下它应该跟真实客户端数量对得上,如果只增不减,说明关闭回调没把连接从你的在线表里摘掉,多半是句柄比较或容器键类型写错了。
3.3 客户端重连:1 秒起步、30 秒封顶的退避曲线
客户端侧在 fail_handler 里重连,最忌讳的就是「失败就立刻重连」。服务端刚重启、端口还没起来的那几秒,客户端会在一秒内发起上百次连接,把 accept 队列打满,服务端起来后反而更慢恢复。
cpp复制// 指数退避:1s 起步,翻倍,30s 封顶
long backoff_ms(int attempt) {
const long base = 1000;
const long cap = 30000;
long delay = base << std::min(attempt, 5); // 1s,2s,4s,8s,16s,32s
return std::min(delay, cap); // 封顶 30s
}
逻辑说明:失败次数每加一,延迟翻倍,超过上限就固定在 30 秒。这个函数只负责算时长,真正的延迟连接要用库的定时器接口排进同一个事件循环,不要在 fail_handler 里 sleep 或者同步 connect。
参数说明:base 取 1 秒,是给对端留出释放旧连接的时间;cap 取 30 秒,是避免网络恢复后还要等太久;attempt 必须在连接成功的回调里清零,否则一次长时间断网之后,退避会一直停在 30 秒,重连看起来很慢。
4. 避坑排查:心跳与重连最容易翻车的五个现场
下面五条都是围绕这套心跳与重连方案在实际联调里会碰到的现象,按「现象、原因、解决」拆开写,对着日志一条条比对即可。
4.1 心跳只发了一轮,连接数没变但业务已经断了
现象:服务端日志里能看到第一轮 ping,之后再也没有心跳记录,连接数还是 1,业务侧却反馈收不到推送。
原因:set_timer 只触发一次,回调里没有重新注册,或者重排时用的不是同一个可调用对象,导致第二次注册失败。另一种情况是重排代码写在 ec 判断之后但被提前 return 跳过了。
解决:把「发 ping」和「再排下一轮」放在同一个回调里,且放在 ec 判断之后;用一个生命周期足够长的 handler 对象,别在局部函数里临时构造 lambda 就返回。
4.2 断网恢复后重连风暴,服务端 accept 被打满
现象:网络恢复的头几秒,客户端连接数暴涨,服务端日志里大量握手,业务请求反而超时。
原因:fail_handler 里同步重连,失败一次立刻再连,没有任何延迟和次数约束;多个客户端同时恢复时,连接请求叠加。
解决:换成指数退避,初始 1 秒、上限 30 秒,延迟通过定时器排队而不是阻塞线程;连接成功后在 open 回调里把失败计数清零。
4.3 客户端断电,服务端还在 ping:半开连接没人收尸
现象:现场设备直接断电,服务端连接数不降,ping 照发,业务侧认为设备还在线。
原因:TCP 层没有收到 FIN,事件循环不会自动
