网络编程
HTTP 请求、文件下载与 TCP/UDP 通信
#Qt Network 的设计前提:一切皆异步
Qt 的网络 API 有一个贯穿始终的设计原则:没有阻塞调用。你调用 manager->get(request),函数立即返回,真正的响应通过 QNetworkReply::finished() 信号送达。
这个设计不是偷懒,而是必然——网络延迟是几百毫秒到几十秒量级,如果 API 是同步的,每个请求都会冻结界面,用户会以为程序死了。Qt 选择把异步做成默认,代价是你必须习惯"发起请求 → 连接信号 → 在槽里处理结果"的思维模式,而不能再写 result = get(url) 这样的直线代码。
由此带来一个必须时刻记住的约束:发起请求后,你要保证相关对象在网络回调返回前仍然存活。QNetworkReply 是异步返回的,如果它的接收方(比如某个窗口)已经被关闭销毁,回调就会访问野指针——这是 Qt 网络编程最常见的崩溃来源,没有之一。
| 类 | 用途 |
|---|---|
QNetworkAccessManager | HTTP 请求总入口(GET/POST/PUT/DELETE) |
QNetworkRequest | 封装 URL、请求头、SSL 配置 |
QNetworkReply | 响应对象,继承 QIODevice |
QSslConfiguration | HTTPS 证书与协议配置 |
QTcpSocket / QTcpServer | TCP 客户端与服务器 |
QUdpSocket | UDP 数据报 |
QHostInfo / QNetworkInterface | DNS 解析与网卡信息 |
#CMake 配置
cmake_minimum_required(VERSION 3.16)
project(NetworkDemo LANGUAGES CXX)
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
find_package(Qt6 REQUIRED COMPONENTS Widgets Network)
qt_standard_project_setup()
qt_add_executable(NetworkDemo
main.cpp
mainwindow.cpp
mainwindow.h
)
target_link_libraries(NetworkDemo PRIVATE Qt6::Widgets Qt6::Network)#GET 请求:发起与处理
下面的代码把请求封装成 HttpClient 类,包含 GET 与 POST(JSON) 两种方式,统一通过 jsonReady() 信号把结果交给业务层:
// ===== 文件 1:httpclient.h =====
#pragma once
#include <QObject>
#include <QNetworkAccessManager>
#include <QNetworkReply>
#include <QJsonObject>
class HttpClient : public QObject
{
Q_OBJECT
public:
explicit HttpClient(QObject *parent = nullptr);
void get(const QString &url);
void postJson(const QString &url, const QJsonObject &body);
signals:
void jsonReady(const QJsonObject &obj);
private slots:
void onFinished(QNetworkReply *reply);
private:
QNetworkAccessManager *m_manager;
};
// ===== 文件 2:httpclient.cpp =====
#include "httpclient.h"
#include <QNetworkRequest>
#include <QJsonDocument>
#include <QJsonObject>
#include <QScopedPointer>
#include <QDebug>
HttpClient::HttpClient(QObject *parent) : QObject(parent)
{
m_manager = new QNetworkAccessManager(this);
connect(m_manager, &QNetworkAccessManager::finished,
this, &HttpClient::onFinished);
}
void HttpClient::get(const QString &url)
{
QNetworkRequest req{QUrl(url)};
// 设置超时(Qt 6.5+ 原生支持;低版本用 QTimer 手动处理)
req.setTransferTimeout(10000);
req.setRawHeader("User-Agent", "QtNetworkDemo/1.0");
req.setRawHeader("Accept", "application/json");
m_manager->get(req); // 立即返回,结果由 finished() 送达
}
void HttpClient::postJson(const QString &url, const QJsonObject &body)
{
QNetworkRequest req{QUrl(url)};
req.setTransferTimeout(15000);
req.setHeader(QNetworkRequest::ContentTypeHeader, "application/json");
const QByteArray data = QJsonDocument(body).toJson(QJsonDocument::Compact);
m_manager->post(req, data);
}
void HttpClient::onFinished(QNetworkReply *reply)
{
// RAII:作用域结束自动 deleteLater
QScopedPointer<QNetworkReply, QScopedPointerDeleteLater> guard(reply);
if (reply->error() != QNetworkReply::NoError) {
qWarning() << "网络错误:" << reply->errorString()
<< ",HTTP 状态:"
<< reply->attribute(QNetworkRequest::HttpStatusCodeAttribute).toInt();
return;
}
const QByteArray bytes = reply->readAll();
qDebug() << "响应长度:" << bytes.size();
// 解析 JSON
QJsonParseError err;
QJsonDocument doc = QJsonDocument::fromJson(bytes, &err);
if (err.error != QJsonParseError::NoError) {
qWarning() << "JSON 解析失败:" << err.errorString();
return;
}
if (!doc.isObject()) {
qWarning() << "响应不是 JSON 对象";
return;
}
emit jsonReady(doc.object()); // 通知业务层
}两个关键点:
第一,QNetworkReply 必须被释放。Qt 文档明确要求调用者负责 deleteLater()。上面的 QScopedPointer + QScopedPointerDeleteLater 是优雅的 RAII 写法,避免了每个 return 分支都要手动清理的麻烦。
第二,setTransferTimeout() 在不同 Qt 版本支持度不同。Qt 6.5 之前没有这个 API,需要自己用 QTimer 配合 reply->abort() 实现超时——这是个真实的痛点,生产代码要写兼容层。
#下载文件:进度与断点
下载本质是"边读边写"。QNetworkReply 继承 QIODevice,所以可以用 readyRead() 信号流式接收:
// downloader.h —— 简化版,聚焦核心逻辑
#pragma once
#include <QObject>
#include <QNetworkAccessManager>
#include <QFile>
#include <QUrl>
class Downloader : public QObject
{
Q_OBJECT
public:
explicit Downloader(QObject *parent = nullptr);
void start(const QUrl &url, const QString &savePath);
signals:
void progress(qint64 received, qint64 total);
void finished(bool ok, const QString &errorString);
private:
void onReadyRead();
void onDownloadProgress(qint64, qint64);
void onFinished();
QNetworkAccessManager *m_manager = nullptr;
QNetworkReply *m_reply = nullptr;
QFile m_file;
};
// ===== 文件 4:downloader.cpp =====
#include "downloader.h"
#include <QNetworkRequest>
#include <QFileInfo>
#include <QDir>
#include <QDebug>
Downloader::Downloader(QObject *parent) : QObject(parent)
{
m_manager = new QNetworkAccessManager(this);
}
void Downloader::start(const QUrl &url, const QString &savePath)
{
QDir().mkpath(QFileInfo(savePath).absolutePath()); // 确保目录存在
m_file.setFileName(savePath);
if (!m_file.open(QIODevice::WriteOnly)) {
emit finished(false, m_file.errorString());
return;
}
QNetworkRequest req{url};
req.setTransferTimeout(30000);
req.setAttribute(QNetworkRequest::RedirectPolicyAttribute,
QNetworkRequest::NoLessSafeRedirectPolicy); // 允许 HTTPS→HTTPS 跳转
m_reply = m_manager->get(req);
connect(m_reply, &QNetworkReply::readyRead,
this, &Downloader::onReadyRead);
connect(m_reply, &QNetworkReply::downloadProgress,
this, &Downloader::onDownloadProgress);
connect(m_reply, &QNetworkReply::finished,
this, &Downloader::onFinished);
}
void Downloader::onReadyRead()
{
// 流式写入,避免整个文件驻留内存
if (m_file.isOpen()) {
m_file.write(m_reply->readAll());
}
}
void Downloader::onDownloadProgress(qint64 received, qint64 total)
{
emit progress(received, total); // 可直接连 QProgressBar
}
void Downloader::onFinished()
{
if (m_reply->error() != QNetworkReply::NoError) {
m_file.close();
m_file.remove(); // 删掉半截文件
emit finished(false, m_reply->errorString());
} else {
m_file.write(m_reply->readAll()); // 收尾
m_file.flush();
m_file.close();
emit finished(true, {});
}
m_reply->deleteLater();
m_reply = nullptr;
}这段代码体现了三个下载最佳实践:
- 流式写入。不要
reply->readAll()存到内存再一次性写文件——1GB 的文件会直接撑爆内存。 - 失败清理。下载中断后删除半截文件,否则下次打开是一个损坏的文件,用户完全不知道发生了什么。
- 重定向策略。很多下载地址会 302 跳转,Qt 6 默认是
NoLessSafeRedirectPolicy(HTTPS 不能跳 HTTP),这是安全的默认行为;不要随意改成ManualRedirectPolicy除非你知道自己在做什么。
onFinished() 里最后那次 readAll() 是必要的兜底:readyRead() 可能没有覆盖最后一小块数据。
#同步等待的坑
"我就是要同步拿到结果"——这种需求很常见(单元测试、命令行工具)。Qt 6 之前的常见写法是:
#include <QEventLoop>
#include <QTimer>
#include <QNetworkReply>
#include <QNetworkAccessManager>
#include <QDebug>
// 反模式:嵌套事件循环,仅在没有其他办法时使用
QByteArray blockingGet(QNetworkAccessManager &mgr, const QUrl &url, int timeoutMs)
{
QNetworkReply *reply = mgr.get(QNetworkRequest{url});
QEventLoop loop;
QByteArray result;
QObject::connect(reply, &QNetworkReply::finished, &loop, [&] {
if (reply->error() == QNetworkReply::NoError) {
result = reply->readAll();
}
loop.quit(); // 退出嵌套循环
});
// 超时保护:不能让 loop 永远转下去
QTimer::singleShot(timeoutMs, &loop, &QEventLoop::quit);
loop.exec(); // 阻塞,但事件仍在被处理
reply->deleteLater();
return result;
}
// 正解:把"拿到结果后要做的事"写进槽,而不是阻塞等待
void fetchUserProfile(HttpClient *client, int userId)
{
QObject::connect(client, &HttpClient::jsonReady,
client, [userId](const QJsonObject &obj) {
qDebug() << "用户" << userId << "的资料:" << obj;
});
client->get(QString("https://api.example.com/users/%1").arg(userId));
}上面 blockingGet() 这段代码能工作,但有问题:嵌套事件循环会让当前调用栈暂停,而事件循环继续处理其他事件。如果在等待期间用户点了"关闭窗口",窗口被析构,而你还在它的栈帧上——回来时就访问野指针了。更糟的是,如果期间又触发了同样的 loop.exec(),会形成层层嵌套的循环。
更严重的陷阱是 waitForReadyRead() 和 waitForBytesWritten() 系列:它们在主线程调用会阻塞事件循环,界面彻底冻结,而且不处理任何重绘。任何情况下都不应在 GUI 线程调用它们。
如果确实需要"顺序化异步",可以用 QFuture/QPromise 或状态机,而不是嵌套 exec()。
#TCP:回显服务器与客户端
TCP 是面向流的,没有消息边界。这是和 UDP 最本质的区别,也是粘包问题的根源。
// ===== 文件 1:tcpechoserver.h =====
#pragma once
#include <QTcpServer>
#include <QTcpSocket>
#include <QList>
class EchoServer : public QTcpServer
{
Q_OBJECT
public:
explicit EchoServer(QObject *parent = nullptr) : QTcpServer(parent) {}
protected:
void incomingConnection(qintptr handle) override
{
auto *sock = new QTcpSocket(this);
sock->setSocketDescriptor(handle);
connect(sock, &QTcpSocket::readyRead, this, [sock] {
const QByteArray data = sock->readAll();
sock->write("echo: " + data); // 原样返回
});
connect(sock, &QTcpSocket::disconnected,
sock, &QTcpSocket::deleteLater);
connect(sock, &QTcpSocket::errorOccurred,
sock, [sock](QAbstractSocket::SocketError) {
qWarning() << "socket 错误:" << sock->errorString();
});
}
};
// ===== 文件 2:tcpclient.h =====
#pragma once
#include <QObject>
#include <QTcpSocket>
class EchoClient : public QObject
{
Q_OBJECT
public:
explicit EchoClient(QObject *parent = nullptr) : QObject(parent)
{
connect(&m_socket, &QTcpSocket::connected, this, [this] {
m_socket.write("Hello");
});
connect(&m_socket, &QTcpSocket::readyRead, this, [this] {
qDebug() << "收到:" << m_socket.readAll();
});
connect(&m_socket, &QTcpSocket::errorOccurred,
this, [this](QAbstractSocket::SocketError) {
qWarning() << "连接错误:" << m_socket.errorString();
});
}
void connectTo(const QString &host, quint16 port)
{
m_socket.connectToHost(host, port);
}
private:
QTcpSocket m_socket;
};
// ===== 文件 3:main.cpp =====
#include <QCoreApplication>
#include <QTimer>
#include <QDebug>
#include "tcpechoserver.h"
#include "tcpclient.h"
int main(int argc, char *argv[])
{
QCoreApplication app(argc, argv);
EchoServer server;
if (!server.listen(QHostAddress::LocalHost, 9000)) {
qWarning() << "监听失败:" << server.errorString();
return 1;
}
EchoClient client;
client.connectTo("127.0.0.1", 9000);
QTimer::singleShot(1000, &app, &QCoreApplication::quit);
return app.exec();
}#粘包与分包
TCP 只保证字节顺序,不保证消息边界。发两次 "Hello"(各 5 字节),对方可能一次收到 10 字节,也可能先收到 3 字节再收到 7 字节。
解决方法是定义应用层协议,常见两种:
| 方案 | 格式 | 适用 |
|---|---|---|
| 长度前缀 | [4字节长度][数据] | 二进制协议,最常用 |
| 分隔符 | 数据\n | 文本协议,简单 |
// 长度前缀协议的读取端
#include <QtEndian>
void onReadyRead(QTcpSocket *sock, QByteArray &buffer)
{
buffer.append(sock->readAll());
while (buffer.size() >= 4) { // 至少读到了长度字段
quint32 len = 0;
memcpy(&len, buffer.constData(), 4);
len = qFromBigEndian(len); // 网络字节序转换!
if (buffer.size() < 4 + static_cast<int>(len)) {
return; // 数据还没收全,等下次
}
QByteArray packet = buffer.mid(4, static_cast<int>(len));
buffer.remove(0, 4 + static_cast<int>(len));
handlePacket(packet); // 处理完整的一包
}
}qFromBigEndian() 那一步是关键:网络字节序是大端,x86 是小端。不转换的话,长度字段会读出一个天文数字。同理,发送端要用 qToBigEndian()。
#UDP:广播与数据报
UDP 无连接、不保证送达,但保留消息边界——一次 writeDatagram 对应一次 readDatagram,天然没有粘包问题。适合局域网发现、实时音视频。
// udpdemo.h —— 局域网设备发现
#pragma once
#include <QObject>
#include <QUdpSocket>
#include <QTimer>
#include <QDebug>
#include <QNetworkInterface>
#include <QHostInfo>
class DeviceBeacon : public QObject
{
Q_OBJECT
public:
explicit DeviceBeacon(QObject *parent = nullptr) : QObject(parent)
{
// 绑定固定端口,允许地址复用(多个实例可共存于同一台机器)
m_socket.bind(45454, QUdpSocket::ShareAddress | QUdpSocket::ReuseAddressHint);
connect(&m_socket, &QUdpSocket::readyRead, this, &DeviceBeacon::onReadyRead);
QTimer *t = new QTimer(this);
connect(t, &QTimer::timeout, this, [this] {
m_socket.writeDatagram("HELLO", QHostAddress::Broadcast, 45454);
});
t->start(2000);
}
private slots:
void onReadyRead()
{
while (m_socket.hasPendingDatagrams()) {
QByteArray data;
data.resize(m_socket.pendingDatagramSize());
QHostAddress sender;
quint16 port = 0;
m_socket.readDatagram(data.data(), data.size(), &sender, &port);
qDebug() << "来自" << sender.toString() << ":" << port << "→" << data;
}
}
private:
QUdpSocket m_socket;
};
// 枚举本机所有 IPv4 地址
static QStringList localAddresses()
{
QStringList out;
const QList<QHostAddress> all = QNetworkInterface::allAddresses();
for (const QHostAddress &a : all) {
if (a.protocol() == QAbstractSocket::IPv4Protocol && !a.isLoopback()) {
out << a.toString();
}
}
return out;
}
// DNS 解析(异步)
static void resolveHost(const QString &host)
{
QHostInfo::lookupHost(host, nullptr, [host](const QHostInfo &info) {
if (info.error() != QHostInfo::NoError) {
qWarning() << "解析失败:" << info.errorString();
return;
}
for (const QHostAddress &a : info.addresses()) {
qDebug() << host << "→" << a.toString();
}
});
}QHostInfo::lookupHost() 是异步的,结果通过回调返回——这与整个 Qt Network 的设计一致。对应的 QHostInfo::fromName() 是同步阻塞的,会卡住调用线程,GUI 程序中不要用。
#常见错误清单
网络代码的 bug 有个特点:开发环境几乎不出现,用户环境频繁出现。因为本地网络快、延迟低、几乎不丢包,而真实环境有超时、重定向、断线、弱网。下面这张表按"症状"索引,排查时从上往下对:
| 症状 | 原因 | 解法 |
|---|---|---|
| 界面在请求期间卡住 | 用了 waitForReadyRead() / 同步 DNS | 改用信号驱动 |
| 崩溃,提示对象已销毁 | reply 回调时接收方已析构 | 用 QPointer 或在析构时 disconnect |
| 内存持续增长 | 忘记 reply->deleteLater() | 用 RAII guard |
| 程序永不退出 | 没有超时保护 | setTransferTimeout 或 QTimer |
| HTTPS 报证书错误 | 自签名证书 | 正确配置 CA,而不是忽略错误 |
| 收到数据不完整 | TCP 无消息边界 | 用长度前缀协议 |
#小结
- Qt Network 是全异步设计,请求立即返回、结果由信号送达;发起后要保证对象存活。
QNetworkReply由调用者负责释放,推荐QScopedPointer+QScopedPointerDeleteLater的 RAII 写法。- 下载应流式写入磁盘(边收边写),失败时删除半截文件;注意重定向策略。
- 同步等待(
waitFor*、嵌套QEventLoop)会引发重入与冻结问题,应当改为槽函数处理。 - TCP 是字节流、无消息边界,需自定义长度前缀或分隔符协议,并做大小端转换;UDP 保留边界但不保证送达。
#练习
- 封装一个
HttpClient类,支持 GET/POST(JSON)、自定义请求头、超时取消,并通过信号返回结果。 - 实现一个断点续传下载器:用
QNetworkRequest::setRawHeader("Range", ...)请求剩余字节,以Append模式打开已有文件。 - 用
QTcpServer+QTcpSocket写一个支持多客户端的聊天室服务器:广播消息给所有连接,客户端断开时清理。 - 在第 3 题基础上实现长度前缀协议,解决 TCP 粘包,并编写测试:客户端快速连发 100 条消息,验证服务器能完整解析。