QC++ / Qt 学习之路

网络编程

HTTP 请求、文件下载与 TCP/UDP 通信

进阶第 33 / 48 章第四篇 · Qt 进阶

#Qt Network 的设计前提:一切皆异步

Qt 的网络 API 有一个贯穿始终的设计原则:没有阻塞调用。你调用 manager->get(request),函数立即返回,真正的响应通过 QNetworkReply::finished() 信号送达。

这个设计不是偷懒,而是必然——网络延迟是几百毫秒到几十秒量级,如果 API 是同步的,每个请求都会冻结界面,用户会以为程序死了。Qt 选择把异步做成默认,代价是你必须习惯"发起请求 → 连接信号 → 在槽里处理结果"的思维模式,而不能再写 result = get(url) 这样的直线代码。

由此带来一个必须时刻记住的约束:发起请求后,你要保证相关对象在网络回调返回前仍然存活。QNetworkReply 是异步返回的,如果它的接收方(比如某个窗口)已经被关闭销毁,回调就会访问野指针——这是 Qt 网络编程最常见的崩溃来源,没有之一。

类用途
QNetworkAccessManagerHTTP 请求总入口(GET/POST/PUT/DELETE)
QNetworkRequest封装 URL、请求头、SSL 配置
QNetworkReply响应对象,继承 QIODevice
QSslConfigurationHTTPS 证书与协议配置
QTcpSocket / QTcpServerTCP 客户端与服务器
QUdpSocketUDP 数据报
QHostInfo / QNetworkInterfaceDNS 解析与网卡信息

#CMake 配置

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() 信号把结果交给业务层:

C++
// ===== 文件 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() 信号流式接收:

C++
// 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;
}

这段代码体现了三个下载最佳实践:

  1. 流式写入。不要 reply->readAll() 存到内存再一次性写文件——1GB 的文件会直接撑爆内存。
  2. 失败清理。下载中断后删除半截文件,否则下次打开是一个损坏的文件,用户完全不知道发生了什么。
  3. 重定向策略。很多下载地址会 302 跳转,Qt 6 默认是 NoLessSafeRedirectPolicy(HTTPS 不能跳 HTTP),这是安全的默认行为;不要随意改成 ManualRedirectPolicy 除非你知道自己在做什么。

onFinished() 里最后那次 readAll() 是必要的兜底:readyRead() 可能没有覆盖最后一小块数据。

QNetworkAccessManager 异步 HTTP 请求get() 立刻返回,结果通过 finished 信号回调,全程不阻塞界面① manager->get(request) 发起请求② 立即返回 QNetworkReply*(不阻塞)③ 事件循环继续,UI 正常响应④ 网络完成 → 触发 finished 信号⑤ Lambda:reply->readAll() 解析 JSON错误做法:同步等待while (!reply->isFinished()) qApp->processEvents();后果:界面卡死、CPU 空转正确做法:等信号,不等待connect(finished, Lambda)reply->deleteLater();请求在内部线程完成,finished 信号回到主线程;同步等待会阻塞事件循环,界面失去响应
QNetworkAccessManager 的异步 HTTP 流程——调用后立刻返回,结果通过信号回调

#同步等待的坑

"我就是要同步拿到结果"——这种需求很常见(单元测试、命令行工具)。Qt 6 之前的常见写法是:

C++
#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 最本质的区别,也是粘包问题的根源。

TCP 通信时序(QTcpServer / QTcpSocket)自上而下表示时间;服务端先 listen,客户端再 connectToHostQTcpServer服务端QTcpSocket客户端生命线 = 对象存活自上而下 = 时间箭头 = 消息流向1server->listen(Any, 8888)2socket->connectToHost(ip, 8888)3newConnection() 信号 → 槽4nextPendingConnection()5write("hello") 发送数据6readyRead() 信号 → 槽7readAll() 读取数据8disconnectFromHost()QTcpServer 只负责监听;每来一个连接产出一个 QTcpSocket,读写都通过它完成
TCP 服务端与客户端的交互时序
C++
// ===== 文件 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文本协议,简单
C++
// 长度前缀协议的读取端
#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,天然没有粘包问题。适合局域网发现、实时音视频。

C++
// 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 无消息边界用长度前缀协议

#小结

  1. Qt Network 是全异步设计,请求立即返回、结果由信号送达;发起后要保证对象存活。
  2. QNetworkReply 由调用者负责释放,推荐 QScopedPointer + QScopedPointerDeleteLater 的 RAII 写法。
  3. 下载应流式写入磁盘(边收边写),失败时删除半截文件;注意重定向策略。
  4. 同步等待(waitFor*、嵌套 QEventLoop)会引发重入与冻结问题,应当改为槽函数处理。
  5. TCP 是字节流、无消息边界,需自定义长度前缀或分隔符协议,并做大小端转换;UDP 保留边界但不保证送达。

#练习

  1. 封装一个 HttpClient 类,支持 GET/POST(JSON)、自定义请求头、超时取消,并通过信号返回结果。
  2. 实现一个断点续传下载器:用 QNetworkRequest::setRawHeader("Range", ...) 请求剩余字节,以 Append 模式打开已有文件。
  3. 用 QTcpServer + QTcpSocket 写一个支持多客户端的聊天室服务器:广播消息给所有连接,客户端断开时清理。
  4. 在第 3 题基础上实现长度前缀协议,解决 TCP 粘包,并编写测试:客户端快速连发 100 条消息,验证服务器能完整解析。
我的学习笔记笔记总览
笔记保存在本机浏览器(localStorage),换设备或清理缓存会丢失;重要内容请点「导出全部笔记」存成 .md 文件。