实战项目二:局域网聊天室(Qt Network + Widgets)
用 QTcpServer/QTcpSocket 实现协议、服务端与客户端
#需求与协议设计
第二个项目做局域网聊天室:一个服务端 + 多个客户端,支持登录、群聊、私聊、在线列表、上下线通知。它把第四篇的 Qt Network 知识串成完整链路,更重要的是训练两件事:协议设计和线程与 UI 的边界。
先把网络部分从需求里剥出来。TCP 是字节流协议,没有消息边界——你 write("hello") 对方可能收到 "hel" + "lo",也可能一次性收到 "hello" 加上后面三条消息粘在一起。这就是经典的粘包/拆包问题,也是新手写 socket 程序最常见的翻车点。因此必须先定协议。
采用长度前缀 + JSON 载荷的方案:4 字节大端长度 + UTF-8 JSON 文本。它兼顾了可读性(JSON 好调试)和可靠性(长度前缀解决粘包)。
+----------+-----------------------------+
| 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,服务端与客户端共用同一份代码。这是很值得养成习惯的做法:协议实现只有一份,两端行为必然一致。
// 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 读写)。
// 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;
};三个要点:
incomingConnection的参数是 socket 描述符,不是QTcpSocket*。重写它才能拿到setSocketDescriptor;如果只想被动接受,也可以连newConnection+nextPendingConnection()。write()是异步的,它返回后数据不一定已发出。不要立刻deleteLatersocket;需要确保发送完成时用disconnectFromHost(),它会等缓冲区排空后再关闭。- 服务端必须补全
from/ts,绝不信任客户端传来的身份字段,否则任何人都能冒充他人发言。
#客户端:收发、心跳与断线重连
// 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 里同样适用):
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"。
// 正确示范:把耗时/阻塞操作放进 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)。
#小结
- TCP 是字节流,必须自己定义帧边界;本项目用"4 字节大端长度 + JSON",解析器要能处理粘包与半包,且一次
readyRead要循环取完所有消息。 - 服务端用
incomingConnection+setSocketDescriptor接管连接,单线程事件循环即可支撑大量聊天连接。 - 心跳(ping/pong)+ 看门狗定时器是检测"假连接"的唯一可靠手段;重连必须指数退避。
- 身份字段(
from/ts)由服务端补全,绝不信任客户端;write()异步,关闭用disconnectFromHost。 - 线程边界:socket 可在工作线程,但 model 与 UI 只能在主线程,跨线程靠
QueuedConnection信号传递。
#练习
- 在协议中增加
typing(正在输入)消息类型:客户端停止输入 1.5 秒后发送,接收方在列表下方显示"某某正在输入…"并在 3 秒后自动消失。 - 实现断线重连后的消息补偿:客户端记录最后收到的消息序号,重连后请求缺失部分(提示:服务端保留最近 200 条历史)。
- 把 socket 挪到独立
QThread,用moveToThread重构,并验证跨线程信号确实在主线程执行(在槽里打印QThread::currentThreadId()对比)。 - 增加文件传输:先用
chat消息发送文件元信息(名、大小),再用独立 TCP 连接分块传输,进度条实时更新。