Qt WebSocket 协议编程实战1. WebSocket 协议概述WebSocket 是一种基于单个 TCP 连接提供全双工Full-Duplex通信信道的网络技术。与传统的 HTTP 请求/响应模型不同WebSocket 在连接建立后客户端与服务器可以双向、实时、低延迟地收发数据无需反复握手。标准化IETF 将其标准化为RFC 6455握手通过 HTTP 的Upgrade头完成协议升级HTTP/1.1 101 Switching Protocols握手完成后数据在同一个 TCP 连接上以**帧frame**的形式传输协议标识ws://明文与wss://基于 TLS 加密默认端口 443默认端口ws为 80wss为 443典型用途实时聊天、股票/行情推送、在线游戏、服务端主动推送通知等在 Qt 中QWebSocket既可用于客户端应用程序也可用于服务器端配合QWebSocketServer构建 WebSocket 服务。2. QWebSocket Class客户端QWebSocket继承自QObject用于在客户端发起并管理一个 WebSocket 连接。2.1 头文件与链接#includeQWebSocket需要在.pro文件中添加QT websocketsCMake 中find_package(Qt6 COMPONENTS WebSockets REQUIRED)并链接Qt6::WebSockets2.2 连接与断开QWebSocket socket;// 发起连接异步socket.open(QUrl(ws://localhost:1234));// 连接成功信号connect(socket,QWebSocket::connected,this,[](){qDebug()Connected;});// 可选设置是否忽略 SSL 错误仅用于测试环境生产谨慎connect(socket,QWebSocket::sslErrors,socket,QOverloadconstQListQSslError::of(QWebSocket::ignoreSslErrors));// 主动关闭socket.close();2.3 收发数据// 发送文本消息socket.sendTextMessage(QStringLiteral(Hello, Server!));// 发送二进制消息QByteArray dataQByteArray::fromHex(48656c6c6f);socket.sendBinaryMessage(data);// 接收文本消息connect(socket,QWebSocket::textMessageReceived,this,[](constQStringmsg){qDebug()Text received:msg;});// 接收二进制消息connect(socket,QWebSocket::binaryMessageReceived,this,[](constQByteArraydata){qDebug()Binary received, size:data.size();});3. QWebSocketServer Class服务器QWebSocketServer用于在服务器端监听并接受 WebSocket 客户端连接创建一个 WebSocket 服务。3.1 启动服务器#includeQWebSocketServerQWebSocketServerserver(QStringLiteral(My Server),QWebSocketServer::NonSecureMode);// 明文模式// 或使用 SecureMode需要配置 SSL 证书// QWebSocketServer server(QStringLiteral(My Server),// QWebSocketServer::SecureMode);if(server.listen(QHostAddress::Any,1234)){qDebug()Listening on portserver.serverPort();}3.2 处理新连接与消息// 新客户端接入connect(server,QWebSocketServer::newConnection,this,[server](){QWebSocket*clientserver.nextPendingConnection();qDebug()New client:client-peerAddress().toString();connect(client,QWebSocket::textMessageReceived,this,[client](constQStringmsg){client-sendTextMessage(Echo: msg);// 回显});connect(client,QWebSocket::disconnected,client,QObject::deleteLater);});4. 相关 API 一览4.1 QWebSocket 主要方法方法说明open(const QUrl url)发起连接到指定 WebSocket 地址close(CloseCode code NormalClosure)关闭连接sendTextMessage(const QString message)发送文本消息sendBinaryMessage(const QByteArray data)发送二进制消息abort()立即中止连接requestUrl()返回请求的 URLstate()返回当前连接状态QAbstractSocket::SocketStateerror()/errorString()获取错误信息4.2 QWebSocket 主要信号信号说明connected()连接建立成功disconnected()连接断开textMessageReceived(const QString )收到文本消息binaryMessageReceived(const QByteArray )收到二进制消息stateChanged(QAbstractSocket::SocketState)连接状态变化errorOccurred(QAbstractSocket::SocketError)发生错误sslErrors(const QListQSslError )SSL 错误4.3 QWebSocketServer 主要方法方法说明listen(const QHostAddress , quint16 port)开始监听nextPendingConnection()取出下一个待处理的客户端连接close()停止监听hasPendingConnections()是否有待处理的连接serverPort()返回实际监听的端口4.4 QWebSocketServer 主要信号信号说明newConnection()有新客户端连接closed()服务器关闭acceptError(QAbstractSocket::SocketError)接受连接出错4.5 重要枚举QWebSocketProtocol::Version协议版本VersionLatest/Version13等QWebSocketServer::SslModeNonSecureMode/SecureModeQWebSocketProtocol::CloseCode关闭码NormalClosure、GoingAway等5. 完整实战示例下面是一个同时包含客户端与服务器的完整示例便于快速验证。5.1 服务器端main.cpp#includeQCoreApplication#includeQWebSocketServer#includeQWebSocket#includeQDebugintmain(intargc,char*argv[]){QCoreApplicationa(argc,argv);QWebSocketServerserver(QStringLiteral(Echo Server),QWebSocketServer::NonSecureMode);QObject::connect(server,QWebSocketServer::newConnection,[server](){QWebSocket*clientserver.nextPendingConnection();qDebug()Client connected:client-peerAddress().toString();QObject::connect(client,QWebSocket::textMessageReceived,[client](constQStringmsg){qDebug()Received:msg;client-sendTextMessage(QStringLiteral(Echo: )msg);});QObject::connect(client,QWebSocket::disconnected,client,QObject::deleteLater);});if(server.listen(QHostAddress::Any,1234)){qDebug()Server listening on portserver.serverPort();}else{qDebug()Listen failed;return1;}returna.exec();}5.2 客户端端main.cpp#includeQCoreApplication#includeQWebSocket#includeQDebugintmain(intargc,char*argv[]){QCoreApplicationa(argc,argv);QWebSocket socket;QObject::connect(socket,QWebSocket::connected,[socket](){qDebug()Connected, sending message...;socket.sendTextMessage(QStringLiteral(Hello, Server!));});QObject::connect(socket,QWebSocket::textMessageReceived,[](constQStringmsg){qDebug()Server said:msg;});QObject::connect(socket,QWebSocket::disconnected,a,QCoreApplication::quit);// 连接过程中发生错误QObject::connect(socket,QWebSocket::errorOccurred,[](QAbstractSocket::SocketError e){qDebug()Error:e;});socket.open(QUrl(QStringLiteral(ws://localhost:1234)));returna.exec();}5.3 .pro 文件QT core websockets CONFIG c17 SOURCES main.cppQt WebSocket 聊天系统 — 服务端 客户端案例项目角色说明QWebsocketServerPrs服务端消息中转站监听 8899 端口管理连接、群发/私发/转发消息untitled40客户端聊天界面连接服务器、发送/接收消息两个项目配套使用才能组成一个完整的多人聊天系统。1. 两个项目是什么关系┌─────────────────────┐ ws://192.168.x.x:8899 ┌─────────────────────┐ │ QWebsocketServerPrs │ ◄──────────────────────────────► │ untitled40 │ │ 服务端 │ │ 客户端 │ │ 监听 8899 端口 │ 可有多个客户端同时连接 │ 填写地址名称连接 │ └─────────────────────┘ └─────────────────────┘QWebsocketServerPrs服务端untitled40客户端核心类QWebSocketServerQWebSocket数量1 个可以开很多个多个人聊天职责监听端口、管理连接、群发/私发/转发发起连接、发送消息、接收并显示消息客户端把自己的名字当 origin 传给服务器服务器靠socket-origin()认人、靠 JSON 里的dst转发消息。整体代码仓库地址HTTPShttps://github.com/wuyongGitHub/qt-websocket-chat.gitSSHgitgithub.com:wuyongGitHub/qt-websocket-chat.git多客户端连接服务端效果群发消息效果私发消息效果客户端相互发消息效果整体效果6. 常见问题与注意事项根据前端开发业务流总结一下websocket使用事项心跳保活长时间空闲的连接可能被中间设备断开建议定期发送 pingQt 会自动响应 ping/pong可手动ping()检测存活。线程模型QWebSocket非线程安全跨线程使用时需通过信号槽或QMetaObject::invokeMethod调度到所属线程。错误处理务必连接errorOccurred信号网络异常时才能及时感知并重连。大文件传输二进制消息适合传输大块数据但需注意分帧与内存占用必要时自行设计分片协议。安全生产环境应使用wss://SecureMode并正确配置证书避免明文传输敏感数据。释放时机客户端断开连接后服务器端应及时deleteLater释放QWebSocket对象防止内存泄漏。