QtC++ 中使用 qtwebsocket 开源库实现基于websocket的本地服务开发详解

前言

当前实时通信功能越来越受到重视，无论是在线聊天、实时数据监控还是多人协作工具，都离不开高效、稳定的实时通信技术。WebSocket 作为一种全双工通信协议，为实时通信提供了良好的解决方案。而在 QtC++ 开发环境中，qtwebsocket 开源库则是实现 WebSocket 通信的一个非常有效帮手。本文将详细介绍如何使用qtwebsocket 库来实现本地服务端的开发。

一、qtwebsocket 开源库介绍

1.1 基本概念

qtwebsocket 是一个基于 Qt 框架的开源库，它实现了 WebSocket 协议，允许在客户端和服务器之间建立持久的连接，进行双向的数据传输。WebSocket 协议不同于传统的 HTTP 协议，HTTP 是一种无状态的、单向的请求 - 响应协议，而 WebSocket 则是一种持久化的协议，一旦建立连接，客户端和服务器就可以随时向对方发送数据，大大提高了实时通信的效率。

qtwebsocket 库充分利用了 Qt 的特性，如信号与槽机制，使得开发者能够更加便捷地处理 WebSocket 通信过程中的各种事件，如连接建立、数据接收、连接断开等。它支持标准的 WebSocket 协议（RFC 6455），可以与各种遵循该标准的 WebSocket 客户端进行通信。

1.2 特点和优势

基于 Qt 框架：qtwebsocket 库深度集成了 Qt 框架，开发者可以利用 Qt 丰富的类库和工具，快速构建出跨平台的 WebSocket 应用程序。Qt 本身具有良好的跨平台特性，使得使用 qtwebsocket 开发的服务端可以轻松运行在 Windows、Linux、macOS 等多种操作系统上。
简单易用：该库提供了简洁明了的 API 接口，通过 Qt 的信号与槽机制来处理各种事件，开发者无需深入了解 WebSocket 协议的底层细节，就能够快速上手进行开发。例如，当有新的客户端连接时，服务端会发出相应的信号，开发者只需关联对应的槽函数即可进行处理。
高效稳定：qtwebsocket 库经过了广泛的测试和实际应用的检验，具有较高的效率和稳定性。它能够有效地处理多个客户端的并发连接，保证数据传输的及时性和准确性。
支持多种数据类型：该库支持文本数据和二进制数据的传输，满足不同场景下的数据通信需求。无论是简单的文本消息，还是复杂的二进制数据（如图片、音频等），都可以通过 qtwebsocket 库进行传输。
开源免费：qtwebsocket 是开源软件，遵循开源协议，开可以自由地使用、修改和分发该库，降低了开发成本。

1.3 核心类和函数

1.3.1 QWebSocketServer：

QWebSocketServer是 qtwebsocket 库中用于创建 WebSocket 服务端的核心类。它负责监听客户端的连接请求，管理已建立的连接。

主要函数：

QWebSocketServer(const QString &serverName, SslMode secureMode, QObject *parent = nullptr)：构造函数，用于创建一个 WebSocket 服务端实例。其中，serverName是服务端的名称，secureMode指定是否使用 SSL 加密，parent是父对象。
listen(const QHostAddress &address = QHostAddress::Any, quint16 port = 0)：开始监听指定地址和端口上的连接请求。address默认为任意地址，port默认为 0（随机端口）。如果监听成功，返回true，否则返回false。
newConnection()：信号，当有新的客户端连接到服务端时发出。开发者可以关联该信号到自定义的槽函数，在槽函数中获取新连接的客户端对象。
close()：关闭服务端，停止监听连接请求，并断开所有已建立的连接。

1.3.2 QWebSocket：

QWebSocket代表一个 WebSocket 连接，既可以是客户端连接，也可以是服务端接收到的客户端连接。在服务端开发中，当有新的客户端连接时，QWebSocketServer 会创建一个 QWebSocket 对象来表示该连接。

主要函数：

sendTextMessage(const QString &message)：向对方发送文本消息。
sendBinaryMessage(const QByteArray &data)：向对方发送二进制消息。
textMessageReceived(const QString &message)：信号，当接收到文本消息时发出。
binaryMessageReceived(const QByteArray &data)：信号，当接收到二进制消息时发出。
disconnected()：信号，当连接断开时发出。
close()：关闭当前连接。

1.3.2 QHostAddress：

用于表示网络地址，在服务端开发中，用于指定服务端监听的地址。例如，QHostAddress::Any表示监听所有可用的网络接口。

1.3.3 quint16：

这里专门对一个无符号 16 位整数类型的quint16说明，只是想说，它在这里主要用于表示端口号，WebSocket 服务端需要监听一个特定的端口来接收客户端的连接请求。

二、本地服务端开发准备

2.1 开发环境搭建

安装 Qt：可以从 Qt 官方网站（https://www.qt.io/）下载 Qt 安装包，根据自己的操作系统选择合适的版本。在安装过程中，需要选择相应的 Qt 版本（建议选择 5.10 及以上版本，因为这些版本对 qtwebsocket 库的支持更加完善）和组件，确保勾选了 "Qt WebSockets" 组件，这样在安装完成后就会自动包含 qtwebsocket 库。
配置 Qt Creator：安装完成后，打开 Qt Creator 集成开发环境。在 Qt Creator 中，需要确保项目的构建套件（Kit）配置正确，选择安装好的 Qt 版本作为构建套件。
验证 qtwebsocket 库是否可用：可以创建一个新的 Qt 控制台应用程序项目，在项目文件（.pro 文件）中添加QT += websockets，然后尝试包含 qtwebsocket 库的头文件（如#include 、#include ），如果没有出现编译错误，则说明 qtwebsocket 库已经正确安装并可以使用。

2.2 相关知识储备

WebSocket 协议基础：虽然 qtwebsocket 库已经封装了 WebSocket 协议的底层细节，但了解 WebSocket 协议的基本原理还是很有必要的，如握手过程、数据帧格式等，这有助于更好地理解和使用 qtwebsocket 库进行开发，以下再进行详细介绍。

三、本地服务端开发全过程

3.1 创建 Qt 项目

打开 Qt Creator，点击 "文件"->"新建文件或项目"。

在弹出的对话框中，选择 "应用程序"->"Qt Widgets 应用程序"（也可以根据实际需求选择其他类型的应用程序，如控制台应用程序），然后点击 "选择"。

进入项目名称和路径设置页面，输入项目名称（如 "LocalWebSocketServer"），选择项目保存的路径，点击 "下一步"。

在 "类信息" 页面，设置主窗口类的名称（如 "MainWindow"），基类选择 "QMainWindow"，点击 "下一步"，"下一步"， "下一步"。。。

最后点击 "完成"，创建项目。

3.2 配置项目文件（.pro 文件）

在创建好的项目中，找到项目文件（LocalWebSocketServer.pro），打开并添加以下内容：

cpp 复制代码

QT       += core gui websockets

greaterThan(QT_MAJOR_VERSION, 4): QT += widgets

TARGET = LocalWebSocketServer
TEMPLATE = app

SOURCES += \
        main.cpp \
        mainwindow.cpp

HEADERS += \
        mainwindow.h

FORMS += \
        mainwindow.ui

其中，QT += websockets是关键，用于告诉 Qt 构建系统在项目中包含 qtwebsocket 库。

3.3 设计服务端界面

如果创建的是 Qt Widgets 应用程序，可以通过 Qt Designer 来设计服务端的界面，用于显示服务端的运行状态、客户端连接信息、接收和发送的消息等。例如，咱就简单的添加以下控件：

QLabel：用于显示服务端的状态（如 "未启动"、"正在监听" 等）、监听的地址和端口等信息。
QTextEdit：用于显示日志信息，如客户端连接、断开连接、消息接收等。
QPushButton：用于启动服务端、停止服务端、向客户端发送消息等操作。
QLineEdit：用于输入要发送的消息内容或指定客户端。

3.4 实现服务端核心功能

包含必要的头文件：在 mainwindow.h 文件中，包含 qtwebsocket 库的相关头文件和其他需要的头文件。

cpp 复制代码

#ifndef MAINWINDOW_H
#define MAINWINDOW_H

#include <QMainWindow>
#include <QWebSocketServer>
#include <QWebSocket>
#include <QList>
#include <QString>

namespace Ui {
class MainWindow;
}

class MainWindow : public QMainWindow
{
    Q_OBJECT

public:
    explicit MainWindow(QWidget *parent = nullptr);
    ~MainWindow();

private slots:
    void on_startServerBtn_clicked();
    void on_stopServerBtn_clicked();
    void on_sendMessageBtn_clicked();
    void onNewConnection();
    void onTextMessageReceived(const QString &message);
    void onDisconnected();

private:
    Ui::MainWindow *ui;
    QWebSocketServer *m_webSocketServer;
    QList<QWebSocket *> m_clients;
    void logMessage(const QString &message);
};

#endif // MAINWINDOW_H

初始化服务端对象：在 mainwindow.cpp 文件的构造函数中，初始化 QWebSocketServer 对象，并关联相关的信号与槽。

cpp 复制代码

#include "mainwindow.h"
#include "ui_mainwindow.h"
#include <QHostAddress>
#include <QDebug>

MainWindow::MainWindow(QWidget *parent) :
    QMainWindow(parent),
    ui(new Ui::MainWindow),
    m_webSocketServer(nullptr)
{
    ui->setupUi(this);
    setWindowTitle("本地WebSocket服务端");

    // 初始化服务端状态
    ui->statusLabel->setText("服务端未启动");
    ui->startServerBtn->setEnabled(true);
    ui->stopServerBtn->setEnabled(false);
    ui->sendMessageBtn->setEnabled(false);

    // 关联按钮点击信号与槽函数
    connect(ui->startServerBtn, &QPushButton::clicked, this, &MainWindow::on_startServerBtn_clicked);
    connect(ui->stopServerBtn, &QPushButton::clicked, this, &MainWindow::on_stopServerBtn_clicked);
    connect(ui->sendMessageBtn, &QPushButton::clicked, this, &MainWindow::on_sendMessageBtn_clicked);
}

MainWindow::~MainWindow()
{
    stopServer();
    delete ui;
}

实现启动服务端功能：在启动服务端的槽函数中，创建 QWebSocketServer 实例，并调用 listen () 函数开始监听客户端的连接请求。

cpp 复制代码

void MainWindow::on_startServerBtn_clicked()
{
    // 停止已有的服务端（如果存在）
    if (m_webSocketServer) {
        stopServer();
    }

    // 创建WebSocket服务端，不使用SSL加密
    m_webSocketServer = new QWebSocketServer(QStringLiteral("Local WebSocket Server"),
                                             QWebSocketServer::NonSecureMode, this);

    // 监听所有地址，端口号为8080
    if (m_webSocketServer->listen(QHostAddress::Any, 8080)) {
        ui->statusLabel->setText(QStringLiteral("服务端正在监听，地址：%1，端口：%2")
                                 .arg(m_webSocketServer->serverAddress().toString())
                                 .arg(m_webSocketServer->serverPort()));
        logMessage("服务端启动成功");

        // 关联新连接信号
        connect(m_webSocketServer, &QWebSocketServer::newConnection,
                this, &MainWindow::onNewConnection);

        ui->startServerBtn->setEnabled(false);
        ui->stopServerBtn->setEnabled(true);
        ui->sendMessageBtn->setEnabled(true);
    } else {
        ui->statusLabel->setText(QStringLiteral("服务端启动失败：%1").arg(m_webSocketServer->errorString()));
        logMessage("服务端启动失败：" + m_webSocketServer->errorString());
        delete m_webSocketServer;
        m_webSocketServer = nullptr;
    }
}

处理新连接：当有新的客户端连接到服务端时，QWebSocketServer 会发出 newConnection () 信号，在对应的槽函数中获取客户端对象，并关联该客户端的消息接收和断开连接信号。

cpp 复制代码

void MainWindow::onNewConnection()
{
    QWebSocket *pSocket = m_webSocketServer->nextPendingConnection();
    if (!pSocket) {
        return;
    }

    logMessage(QStringLiteral("新客户端连接，地址：%1，端口：%2")
               .arg(pSocket->peerAddress().toString())
               .arg(pSocket->peerPort()));

    // 关联客户端的信号
    connect(pSocket, &QWebSocket::textMessageReceived,
            this, &MainWindow::onTextMessageReceived);
    connect(pSocket, &QWebSocket::disconnected,
            this, &MainWindow::onDisconnected);

    // 将客户端添加到客户端列表
    m_clients << pSocket;
}

处理接收的消息：当服务端接收到客户端发送的文本消息时，会触发 textMessageReceived () 信号，在槽函数中处理接收到的消息，如显示在日志中，或向其他客户端转发等。

cpp 复制代码

void MainWindow::onTextMessageReceived(const QString &message)
{
    QWebSocket *pSender = qobject_cast<QWebSocket *>(sender());
    if (pSender) {
        logMessage(QStringLiteral("收到来自 %1:%2 的消息：%3")
                   .arg(pSender->peerAddress().toString())
                   .arg(pSender->peerPort())
                   .arg(message));

        // 可以在这里将消息转发给其他客户端
        foreach (QWebSocket *pClient, m_clients) {
            if (pClient != pSender && pClient->state() == QAbstractSocket::ConnectedState) {
                pClient->sendTextMessage(message);
            }
        }
    }
}

处理连接断开：当客户端与服务端断开连接时，会发出 disconnected () 信号，在槽函数中将该客户端从客户端列表中移除，并释放资源。

cpp 复制代码

void MainWindow::onDisconnected()
{
    QWebSocket *pSocket = qobject_cast<QWebSocket *>(sender());
    if (pSocket) {
        logMessage(QStringLiteral("客户端断开连接，地址：%1，端口：%2")
                   .arg(pSocket->peerAddress().toString())
                   .arg(pSocket->peerPort()));

        m_clients.removeAll(pSocket);
        pSocket->deleteLater();
    }
}

实现停止服务端功能：在停止服务端的槽函数中，关闭服务端，断开所有客户端的连接，并释放相关资源。

cpp 复制代码

void MainWindow::on_stopServerBtn_clicked()
{
    stopServer();
}

void MainWindow::stopServer()
{
    if (m_webSocketServer) {
        // 关闭所有客户端连接
        foreach (QWebSocket *pClient, m_clients) {
            pClient->close();
            pClient->deleteLater();
        }
        m_clients.clear();

        // 关闭服务端
        m_webSocketServer->close();
        delete m_webSocketServer;
        m_webSocketServer = nullptr;

        ui->statusLabel->setText("服务端已停止");
        logMessage("服务端已停止");

        ui->startServerBtn->setEnabled(true);
        ui->stopServerBtn->setEnabled(false);
        ui->sendMessageBtn->setEnabled(false);
    }
}

实现发送消息功能：服务端可以向连接的客户端发送消息，在发送消息的槽函数中，获取输入的消息内容，并发送给指定的客户端或所有客户端。

cpp 复制代码

void MainWindow::on_sendMessageBtn_clicked()
{
    QString message = ui->messageLineEdit->text();
    if (message.isEmpty()) {
        logMessage("消息内容不能为空");
        return;
    }

    // 向所有连接的客户端发送消息
    foreach (QWebSocket *pClient, m_clients) {
        if (pClient->state() == QAbstractSocket::ConnectedState) {
            pClient->sendTextMessage(message);
        }
    }

    logMessage("发送消息：" + message);
    ui->messageLineEdit->clear();
}

日志显示功能：实现一个辅助函数，用于将各种事件和消息显示在日志控件中。

cpp 复制代码

void MainWindow::logMessage(const QString &message)
{
    ui->logTextEdit->appendPlainText(QDateTime::currentDateTime().toString("yyyy-MM-dd hh:mm:ss") + " " + message);
}

3.5 编译和运行

点击 Qt Creator 中的 "构建"->"构建项目"（或按下 Ctrl+B），对项目进行编译。如果编译过程中出现错误，根据错误提示进行修改。
编译成功后，点击 "运行" 按钮（或按下 Ctrl+R），运行服务端程序。此时，服务端程序启动，点击 "启动服务端" 按钮，服务端开始监听 8080 端口。

3.6 测试服务端

使用 WebSocket 客户端工具：可以使用一些在线的 WebSocket 测试工具（如https://wstool.js.org/）或专门的客户端软件来测试服务端。在客户端工具中，输入服务端的地址（如 ws://localhost:8080），点击连接按钮。
发送消息：连接成功后，在客户端工具中输入消息并发送，服务端的日志控件中会显示收到的消息，同时客户端也会收到服务端转发的消息（如果服务端实现了转发功能）。
多客户端测试：打开多个客户端工具，都连接到服务端，然后从一个客户端发送消息，观察其他客户端是否能收到消息，以测试服务端的多客户端处理和消息转发功能。
断开连接测试：关闭客户端工具，观察服务端的日志是否显示客户端断开连接的信息。

3.7 优化和扩展

错误处理：在实际开发中，需要加强错误处理，如处理服务端监听失败、客户端连接异常、消息发送失败等情况，提高服务端的稳定性。
配置化：将服务端的监听地址、端口等参数配置到配置文件中，使得服务端可以灵活配置，而不需要修改代码重新编译。
认证和授权：对于一些需要安全验证的应用，可以在客户端连接时进行认证和授权，只有通过验证的客户端才能与服务端进行通信。
数据加密：如果对数据安全性要求较高，可以使用 SSL/TLS 对 WebSocket 连接进行加密，qtwebsocket 库支持 SSL 模式，只需在创建 QWebSocketServer 时选择 SecureMode，并配置相应的证书即可。
性能优化：对于需要处理大量并发连接的服务端，可以进行性能优化，如使用多线程处理客户端连接、限制单个客户端的消息频率等。

四、qtwebsocket 库的实际应用案例

4.1 实时聊天系统

在实时聊天系统中，服务端需要处理多个客户端的连接，接收客户端发送的聊天消息，并将消息转发给其他客户端。使用 qtwebsocket 库可以很方便地实现这一功能。服务端通过 QWebSocketServer 监听客户端连接，当有新客户端连接时，将其加入客户端列表。当收到某个客户端的消息时，遍历客户端列表，将消息转发给其他所有在线的客户端，实现实时聊天功能。

4.2 实时数据监控系统

在工业监控、环境监测等领域，需要实时将设备采集的数据发送到监控中心。服务端可以使用 qtwebsocket 库接收设备（客户端）发送的实时数据，并将数据展示在监控界面上，同时可以向设备发送控制指令。通过 WebSocket 的实时通信特性，能够保证数据的及时性和准确性，满足实时监控的需求。

4.3 多人协作编辑工具

在多人协作编辑文档、表格等工具中，多个用户可以同时编辑同一个文件，每个用户的修改需要实时同步给其他用户。服务端使用 qtwebsocket 库接收用户的修改操作消息，然后将这些消息广播给其他用户，使得所有用户的界面保持一致，实现多人实时协作。

五、常见问题及解决方法

5.1 服务端启动失败

端口被占用：这是最常见的一种情况，如果服务端启动时提示端口被占用，可以尝试更换一个未被占用的端口。可以通过命令行工具（如 Windows 的 netstat -ano 命令）查看端口的占用情况，然后在服务端代码中修改监听的端口号。
权限不足：在某些操作系统上，监听低于 1024 的端口需要管理员权限。如果服务端需要监听这些端口，可以以管理员身份运行服务端程序，或者更换为高于 1024 的端口。
网络配置问题：检查服务端的监听地址是否正确，如果设置为特定的网络接口地址，确保该网络接口正常工作。可以尝试使用 QHostAddress::Any 监听所有地址。

5.2 客户端无法连接到服务端

服务端未启动：确保服务端已经成功启动并正在监听指定的端口，在一些真正的项目中，实际上是需要在开发一个监听服务，专门用于监查服务端是否在正常工作。
地址或端口错误：检查客户端连接时使用的地址和端口是否与服务端的监听地址和端口一致。
防火墙设置：防火墙可能会阻止客户端与服务端之间的连接。可以暂时关闭防火墙进行测试，如果问题解决，则需要在防火墙中添加规则，允许 WebSocket 通信的端口通过。
跨域问题：这也是一个很常见的问题，如果客户端是网页应用，可能存在跨域问题。在服务端需要设置适当的跨域资源共享（CORS）头部，允许客户端所在的域名进行连接。

5.3 消息发送或接收异常

消息格式错误：确保客户端和服务端发送的消息格式一致，如文本消息使用正确的编码，二进制消息的格式符合双方的约定。
连接状态异常：在发送消息前，检查客户端或服务端的连接状态是否为已连接（QAbstractSocket::ConnectedState），只有在连接状态下才能发送消息。
消息过大：WebSocket 协议对单条消息的大小有一定的限制，如果消息过大，可能会导致发送或接收失败。可以将大消息分割成多个小消息进行发送，在接收端再进行合并。

六、总结

本文详细介绍了 qtwebsocket 开源库，包括其基本概念、特点优势和核心类函数，并全程讲解了使用该库实现本地服务端开发的过程。

qtwebsocket 库凭借其基于 Qt 框架、简单易用、高效稳定等特点，为 QtC++ 开发者提供了便捷的 WebSocket 通信解决方案。通过本文的学习，开发者可以快速上手使用 qtwebsocket 库进行本地服务端开发，满足实时通信的需求。

同时，结合 Qt 的其他技术，如 Qt Quick、Qt Network 等，开发者可以构建出更加丰富、高效的实时应用程序。例如，使用 Qt Quick 构建跨平台的客户端界面，结合 qtwebsocket 库实现与服务端的实时通信，为用户提供更好的体验。

QtC++ 中使用 qtwebsocket 开源库实现基于websocket的本地服务开发详解

前言

一、qtwebsocket 开源库介绍​

1.1 基本概念​

1.2 特点和优势​

1.3 核心类和函数​

1.3.1 QWebSocketServer：

1.3.2 QWebSocket：

1.3.2 QHostAddress：

1.3.3 quint16：

二、本地服务端开发准备​

2.1 开发环境搭建​

2.2 相关知识储备​

三、本地服务端开发全过程​

3.1 创建 Qt 项目​

3.2 配置项目文件（.pro 文件）​

3.3 设计服务端界面

3.4 实现服务端核心功能​

3.5 编译和运行​

3.6 测试服务端​

3.7 优化和扩展​

四、qtwebsocket 库的实际应用案例​

4.1 实时聊天系统​

4.2 实时数据监控系统​

4.3 多人协作编辑工具​

五、常见问题及解决方法​

5.1 服务端启动失败​

5.2 客户端无法连接到服务端​

5.3 消息发送或接收异常​

六、总结

一、qtwebsocket 开源库介绍

1.1 基本概念

1.2 特点和优势

1.3 核心类和函数

二、本地服务端开发准备

2.1 开发环境搭建

2.2 相关知识储备

三、本地服务端开发全过程

3.1 创建 Qt 项目

3.2 配置项目文件（.pro 文件）

3.4 实现服务端核心功能

3.5 编译和运行

3.6 测试服务端

3.7 优化和扩展

四、qtwebsocket 库的实际应用案例

4.1 实时聊天系统

4.2 实时数据监控系统

4.3 多人协作编辑工具

五、常见问题及解决方法

5.1 服务端启动失败

5.2 客户端无法连接到服务端

5.3 消息发送或接收异常