QC++ / Qt 学习之路

实战项目二:局域网聊天室(Qt Network + Widgets)

用 QTcpServer/QTcpSocket 实现协议、服务端与客户端

进阶第 39 / 48 章第五篇 · QML 与实战项目

#需求与协议设计

第二个项目做局域网聊天室:一个服务端 + 多个客户端,支持登录、群聊、私聊、在线列表、上下线通知。它把第四篇的 Qt Network 知识串成完整链路,更重要的是训练两件事:协议设计和线程与 UI 的边界。

聊天室 · 在线 5 人 房间 好友 设置 邀请 文件 清屏 192.168.1.23:8888 在线成员 5 张 张伟 在线 · 主持人 李 李娜 在线 · 开发 王 王强 在线 · 开发 刘 刘洋 忙碌 · 会议中 赵 赵敏 离开 · 5 分钟前 李娜 大家好,今天的代码评审几点开始? 14:01 王强 三点,会议室 A。 14:03 我 Demo 编译好了,可以演示。 14:05 刘洋 好,我这边也准备好了。 14:06 顺便确认一下网络端口。 14:06 我 那我们三点会议室见。 14:07 输入消息… 发送 已连接 · 延迟 12ms Qt Widgets · QTcpSocket QListWidget · 在线成员 QScrollArea 消息区 QLineEdit 输入框
聊天室客户端界面结构

先把网络部分从需求里剥出来。TCP 是字节流协议,没有消息边界——你 write("hello") 对方可能收到 "hel" + "lo",也可能一次性收到 "hello" 加上后面三条消息粘在一起。这就是经典的粘包/拆包问题,也是新手写 socket 程序最常见的翻车点。因此必须先定协议。

采用长度前缀 + JSON 载荷的方案:4 字节大端长度 + UTF-8 JSON 文本。它兼顾了可读性(JSON 好调试)和可靠性(长度前缀解决粘包)。

Text
+----------+-----------------------------+
| 4 bytes  |  N bytes (UTF-8 JSON)       |
| length N |  {"type":"chat", ...}       |
| (大端)   |                             |
+----------+-----------------------------+

消息类型枚举:
  login      {type, name}                 客户端 → 服务端,请求昵称
  userlist   {type, users:[{id,name}]}    服务端 → 客户端,全量在线列表
  join       {type, id, name}             服务端 → 广播,有人上线
  leave      {type, id, name}             服务端 → 广播,有人下线
  chat       {type, from, fromName, text, ts}  双向,群聊消息
  private    {type, from, fromName, to, text, ts} 定向消息
  ping/pong  {type}                       心跳,每 10 秒一次
  error      {type, code, message}        服务端 → 客户端,错误反馈

为什么不用纯文本行协议(如 CHAT|张三|你好\n)?因为它遇到消息内容里含换行就崩,扩展字段时所有解析代码都要改。JSON 的代价是多几百字节,局域网内完全可以接受。用 QDataStream 时要固定 setVersion() 并用大端(setByteOrder(QDataStream::BigEndian)),否则不同平台间可能不兼容——本项目直接用 qToBigEndian 手写长度前缀,更可控。

#封装:一个可复用的协议层

把"收发一条消息"封装成 MessageFramer,服务端与客户端共用同一份代码。这是很值得养成习惯的做法:协议实现只有一份,两端行为必然一致。

C++
// protocol.h
#pragma once
#include <QJsonObject>
#include <QByteArray>

inline QByteArray encodeMessage(const QJsonObject &obj)
{
    const QByteArray body = QJsonDocument(obj).toJson(QJsonDocument::Compact);
    QByteArray out;
    out.resize(4 + body.size());
    const quint32 len = qToBigEndian(static_cast<quint32>(body.size()));
    memcpy(out.data(), &len, 4);
    memcpy(out.data() + 4, body.constData(), body.size());
    return out;
}

// 增量解析器:把任意长度的字节流喂进去,吐出完整消息
class MessageFramer
{
public:
    void append(const QByteArray &chunk) { m_buf.append(chunk); }

    // 可能一次返回多条(粘包),也可能返回 0 条(半包)
    QList<QJsonObject> takeMessages()
    {
        QList<QJsonObject> result;
        while (true) {
            if (m_buf.size() < 4) break;                 // 还不够读长度
            quint32 len;
            memcpy(&len, m_buf.constData(), 4);
            len = qFromBigEndian(len);
            if (len > 1024 * 1024) { m_buf.clear(); break; }  // 防恶意超大包
            if (m_buf.size() < 4 + (int)len) break;      // 还没收全
            QJsonParseError err;
            QJsonDocument doc = QJsonDocument::fromJson(
                m_buf.mid(4, (int)len), &err);
            m_buf.remove(0, 4 + (int)len);               // 消费掉这一帧
            if (err.error == QJsonParseError::NoError && doc.isObject())
                result.append(doc.object());
        }
        return result;
    }
private:
    QByteArray m_buf;
};

注意 while 循环:一次 readyRead 里可能同时到达 3 条完整消息,必须全部取出,否则剩下的会一直等到下一次数据到达才被处理——表现为"消息偶尔延迟几秒才显示"。这是粘包处理最典型的 bug。

#服务端:QTcpServer + 客户端管理

服务端不需要多线程。QTcpServer 与 QTcpSocket 都工作在事件循环里,单线程足以支撑上百个聊天连接(真正的瓶颈是数据库或 CPU 密集计算,不是 socket 读写)。

C++
// chatserver.h/.cpp(核心)
class ChatServer : public QTcpServer
{
    Q_OBJECT
public:
    explicit ChatServer(QObject *parent = nullptr) : QTcpServer(parent) {}

protected:
    void incomingConnection(qintptr handle) override
    {
        auto *sock = new QTcpSocket(this);
        if (!sock->setSocketDescriptor(handle)) { delete sock; return; }

        Client c;
        c.id   = m_nextId++;
        c.sock = sock;
        m_clients.insert(c.id, c);

        connect(sock, &QTcpSocket::readyRead, this, [this, sock] { onReadyRead(sock); });
        connect(sock, &QTcpSocket::disconnected, this, [this, sock] { onDisconnected(sock); });

        qInfo() << "新连接 id=" << (m_nextId - 1) << sock->peerAddress().toString();
    }

private slots:
    void onReadyRead(QTcpSocket *sock)
    {
        m_framers[sock].append(sock->readAll());
        for (const QJsonObject &msg : m_framers[sock].takeMessages())
            handleMessage(sock, msg);
    }

    void onDisconnected(QTcpSocket *sock)
    {
        int id = idOf(sock);
        if (id < 0) return;
        QString name = m_clients[id].name;
        m_clients.remove(id);
        m_framers.remove(sock);
        sock->deleteLater();

        broadcast({{"type","leave"},{"id",id},{"name",name}});
        qInfo() << name << "离开";
    }

private:
    int idOf(QTcpSocket *s) const { /* 遍历 m_clients 查找,略 */ return -1; }

    void handleMessage(QTcpSocket *sock, const QJsonObject &msg)
    {
        const QString type = msg.value("type").toString();
        if (type == "login") {
            int id = idOf(sock);
            m_clients[id].name = msg.value("name").toString().trimmed();
            if (m_clients[id].name.isEmpty()) m_clients[id].name = "匿名";

            // 1. 先给新用户发全量在线列表
            sock->write(encodeMessage({{"type","userlist"},{"users", buildUserList()}}));
            // 2. 再广播他上线
            broadcast({{"type","join"},{"id",id},{"name",m_clients[id].name}});
            return;
        }
        if (type == "ping") { sock->write(encodeMessage({{"type","pong"}})); return; }
        if (type == "chat" || type == "private") {
            // 服务端补全来源与时间戳,防止客户端伪造
            QJsonObject out = msg;
            out["from"]     = idOf(sock);
            out["fromName"] = m_clients[idOf(sock)].name;
            out["ts"]       = QDateTime::currentSecsSinceEpoch();
            if (type == "chat") broadcast(out);
            else if (int to = msg.value("to").toInt(); m_clients.contains(to))
                m_clients[to].sock->write(encodeMessage(out));
        }
    }

    void broadcast(const QJsonObject &msg)
    {
        const QByteArray data = encodeMessage(msg);
        for (auto it = m_clients.cbegin(); it != m_clients.cend(); ++it)
            it->sock->write(data);
    }

    struct Client { QTcpSocket *sock = nullptr; QString name; };
    QHash<int, Client>          m_clients;
    QHash<QTcpSocket*, MessageFramer> m_framers;
    int m_nextId = 1;
};

三个要点:

  1. incomingConnection 的参数是 socket 描述符,不是 QTcpSocket*。重写它才能拿到 setSocketDescriptor;如果只想被动接受,也可以连 newConnection + nextPendingConnection()。
  2. write() 是异步的,它返回后数据不一定已发出。不要立刻 deleteLater socket;需要确保发送完成时用 disconnectFromHost(),它会等缓冲区排空后再关闭。
  3. 服务端必须补全 from/ts,绝不信任客户端传来的身份字段,否则任何人都能冒充他人发言。

#客户端:收发、心跳与断线重连

C++
// chatclient.cpp
void ChatClient::connectToHost(const QString &host, quint16 port)
{
    m_socket->connectToHost(host, port);
}

void ChatClient::onConnected()
{
    m_retryDelay = 1000;
    sendLogin();
    m_heartbeat->start(10000);     // 每 10 秒
    m_watchdog->start(15000);      // 15 秒未收到任何数据则判定掉线
    emit connectedChanged(true);
}

void ChatClient::onDisconnected()
{
    m_heartbeat->stop();
    m_watchdog->stop();
    emit connectedChanged(false);

    if (m_autoReconnect) {
        // 指数退避:1s, 2s, 4s, ... 上限 30s,避免服务端重启时被疯狂重连
        QTimer::singleShot(m_retryDelay, this, &ChatClient::reconnect);
        m_retryDelay = qMin(m_retryDelay * 2, 30000);
    }
}

void ChatClient::reconnect()
{
    if (m_socket->state() != QAbstractSocket::UnconnectedState)
        m_socket->abort();          // 关键:abort() 立即释放,close() 会等待
    m_socket->connectToHost(m_host, m_port);
}

void ChatClient::sendChat(const QString &text)
{
    if (m_socket->state() != QAbstractSocket::ConnectedState) {
        emit errorOccurred("未连接");
        return;
    }
    m_socket->write(encodeMessage({{"type","chat"},{"text",text}}));
}

为什么需要心跳:TCP 连接断开时,如果中间链路(例如笔记本合盖、WiFi 断开、NAT 超时)没有正常四次挥手,操作系统可能几十分钟都感知不到连接已死,state() 仍返回 Connected。心跳 + 看门狗是唯一可靠的探测手段:客户端定时发 ping,同时启动一个"超过 N 秒没收到任何字节就认为掉线"的定时器,两者配合。重连时用指数退避,否则服务端短暂重启会让所有客户端同时疯狂重连,形成重连风暴。

#消息模型与界面绑定

聊天记录不要用 QListWidget 直接 addItem——那样数据散在控件里,既不能持久化也不能过滤。用 QAbstractListModel(我们在 p5-03 学过的同一套机制,它在 Widgets 里同样适用):

C++
class MessageModel : public QAbstractListModel
{
    Q_OBJECT
public:
    enum Role { TextRole = Qt::UserRole, SenderRole, TimeRole, MineRole };

    int rowCount(const QModelIndex &p = {}) const override { return p.isValid() ? 0 : m_items.size(); }

    QVariant data(const QModelIndex &i, int role) const override {
        if (!i.isValid() || i.row() >= m_items.size()) return {};
        const Msg &m = m_items.at(i.row());
        switch (role) {
        case TextRole:   return m.text;
        case SenderRole: return m.sender;
        case TimeRole:   return QDateTime::fromSecsSinceEpoch(m.ts).toString("HH:mm:ss");
        case MineRole:   return m.mine;      // 委托据此决定左右对齐
        }
        return {};
    }

    void append(const Msg &m) {
        beginInsertRows({}, m_items.size(), m_items.size());
        m_items.append(m);
        endInsertRows();
    }
private:
    QList<Msg> m_items;
};

配合 QStyledItemDelegate 自定义气泡样式(重写 paintEvent 画圆角气泡、sizeHint 返回随文本长度变化的高度)。QListView 只创建可见项的委托,上万条聊天记录也不卡。

线程安全的铁律:所有涉及 QWidget、QAbstractListModel 的操作只能在主线程执行。如果客户端把 socket 放到工作线程(大项目常见),则:

  • 工作线程里 readAll() 出数据后,通过 emit messageReceived(obj) 把结果送回主线程——跨线程信号槽默认是 QueuedConnection,会自动排队,安全;
  • 绝不能在工作线程里直接 model->append() 或 ui->listView->update();
  • 反过来,主线程调工作线程对象的方法要用 QMetaObject::invokeMethod(obj, "connectToHost", Qt::QueuedConnection, ...),否则你会在错误的线程里操作 socket,Qt 会报 "QSocketNotifier: cannot be enabled from another thread"。
C++
// 正确示范:把耗时/阻塞操作放进 worker,结果用信号回传
void ChatController::startInThread()
{
    auto *thread = new QThread(this);
    auto *worker = new SocketWorker;          // 不能有 parent
    worker->moveToThread(thread);
    connect(thread, &QThread::finished, worker, &QObject::deleteLater);
    connect(worker, &SocketWorker::messageReceived,
            this, &ChatController::onMessage, Qt::QueuedConnection);  // 回到主线程改 UI
    thread->start();
}

#测试与联调

  • 先用 telnet/nc 验证服务端:nc 127.0.0.1 8888 后手工粘贴一段 JSON(需要自己先算长度前缀,可用脚本生成),确认服务端不会崩且无内存泄漏。
  • 用 Qt Creator 同时开两个客户端实例:菜单"运行 → 运行多个实例",验证广播、上下线通知是否对称。
  • 弱网模拟:Linux 上用 tc qdisc add dev lo root netem delay 200ms loss 5%,观察心跳与重连行为;Windows/macOS 可用 Clumsy、Network Link Conditioner。
  • 检查泄漏:关掉所有客户端后看服务端 m_clients 是否归零(加个定时器打印 size())。长期运行用 Valgrind 或 Qt Creator 内置的 Heob 检测。
  • 边界用例:昵称重复、昵称为空、超长消息(1MB)、消息含换行与 emoji、客户端强制 kill(不发 FIN)。

#小结

  1. TCP 是字节流,必须自己定义帧边界;本项目用"4 字节大端长度 + JSON",解析器要能处理粘包与半包,且一次 readyRead 要循环取完所有消息。
  2. 服务端用 incomingConnection + setSocketDescriptor 接管连接,单线程事件循环即可支撑大量聊天连接。
  3. 心跳(ping/pong)+ 看门狗定时器是检测"假连接"的唯一可靠手段;重连必须指数退避。
  4. 身份字段(from/ts)由服务端补全,绝不信任客户端;write() 异步,关闭用 disconnectFromHost。
  5. 线程边界:socket 可在工作线程,但 model 与 UI 只能在主线程,跨线程靠 QueuedConnection 信号传递。

#练习

  1. 在协议中增加 typing(正在输入)消息类型:客户端停止输入 1.5 秒后发送,接收方在列表下方显示"某某正在输入…"并在 3 秒后自动消失。
  2. 实现断线重连后的消息补偿:客户端记录最后收到的消息序号,重连后请求缺失部分(提示:服务端保留最近 200 条历史)。
  3. 把 socket 挪到独立 QThread,用 moveToThread 重构,并验证跨线程信号确实在主线程执行(在槽里打印 QThread::currentThreadId() 对比)。
  4. 增加文件传输:先用 chat 消息发送文件元信息(名、大小),再用独立 TCP 连接分块传输,进度条实时更新。
我的学习笔记笔记总览
笔记保存在本机浏览器(localStorage),换设备或清理缓存会丢失;重要内容请点「导出全部笔记」存成 .md 文件。