当前位置：首页 > ops >正文

Qt 网络编程进阶：RESTful API 调用

ops 2025/7/27 5:06:55

在现代软件开发中，RESTful API 已成为服务间通信的标准方式。Qt 提供了强大的网络模块，使开发者能够轻松实现 RESTful API 的调用与交互。本文将深入探讨 Qt 网络编程中 RESTful API 调用的进阶实现，包括请求构建、响应处理、认证机制、错误处理以及最佳实践等方面。

一、RESTful API 基础调用

1. 基本 GET 请求

#include <QNetworkAccessManager>
#include <QNetworkRequest>
#include <QNetworkReply>
#include <QJsonDocument>
#include <QJsonObject>
#include <QEventLoop>
#include <QUrlQuery>class RestClient : public QObject {Q_OBJECT
public:explicit RestClient(QObject *parent = nullptr) : QObject(parent) {manager = new QNetworkAccessManager(this);}// 同步 GET 请求QJsonObject getSync(const QString &url, const QMap<QString, QString> &params = {}) {QUrl fullUrl(url);if (!params.isEmpty()) {QUrlQuery query;for (auto it = params.begin(); it != params.end(); ++it) {query.addQueryItem(it.key(), it.value());}fullUrl.setQuery(query);}QNetworkRequest request(fullUrl);request.setHeader(QNetworkRequest::ContentTypeHeader, "application/json");QNetworkReply *reply = manager->get(request);QEventLoop loop;connect(reply, &QNetworkReply::finished, &loop, &QEventLoop::quit);loop.exec();QJsonObject result;if (reply->error() == QNetworkReply::NoError) {QByteArray data = reply->readAll();QJsonDocument doc = QJsonDocument::fromJson(data);if (doc.isObject()) {result = doc.object();}} else {result["error"] = reply->errorString();}reply->deleteLater();return result;}private:QNetworkAccessManager *manager;
};

2. 异步 GET 请求

// 异步 GET 请求
void getAsync(const QString &url, const QMap<QString, QString> &params = {}) {QUrl fullUrl(url);if (!params.isEmpty()) {QUrlQuery query;for (auto it = params.begin(); it != params.end(); ++it) {query.addQueryItem(it.key(), it.value());}fullUrl.setQuery(query);}QNetworkRequest request(fullUrl);request.setHeader(QNetworkRequest::ContentTypeHeader, "application/json");QNetworkReply *reply = manager->get(request);connect(reply, &QNetworkReply::finished, this, [this, reply]() {QJsonObject result;if (reply->error() == QNetworkReply::NoError) {QByteArray data = reply->readAll();QJsonDocument doc = QJsonDocument::fromJson(data);if (doc.isObject()) {result = doc.object();}} else {result["error"] = reply->errorString();}emit requestFinished(result);reply->deleteLater();});
}signals:void requestFinished(const QJsonObject &result);

二、处理不同类型的 REST 请求

1. POST 请求

// 发送 POST 请求
QJsonObject post(const QString &url, const QJsonObject &data, const QMap<QString, QString> &headers = {}) {QUrl fullUrl(url);QNetworkRequest request(fullUrl);request.setHeader(QNetworkRequest::ContentTypeHeader, "application/json");// 设置额外的请求头for (auto it = headers.begin(); it != headers.end(); ++it) {request.setRawHeader(it.key().toUtf8(), it.value().toUtf8());}QByteArray jsonData = QJsonDocument(data).toJson();QNetworkReply *reply = manager->post(request, jsonData);QEventLoop loop;connect(reply, &QNetworkReply::finished, &loop, &QEventLoop::quit);loop.exec();QJsonObject result;if (reply->error() == QNetworkReply::NoError) {QByteArray responseData = reply->readAll();QJsonDocument doc = QJsonDocument::fromJson(responseData);if (doc.isObject()) {result = doc.object();}} else {result["error"] = reply->errorString();}reply->deleteLater();return result;
}

2. PUT/PATCH/DELETE 请求

// PUT 请求
QJsonObject put(const QString &url, const QJsonObject &data) {QUrl fullUrl(url);QNetworkRequest request(fullUrl);request.setHeader(QNetworkRequest::ContentTypeHeader, "application/json");QByteArray jsonData = QJsonDocument(data).toJson();QNetworkReply *reply = manager->put(request, jsonData);// 处理响应...
}// DELETE 请求
QJsonObject del(const QString &url) {QUrl fullUrl(url);QNetworkRequest request(fullUrl);QNetworkReply *reply = manager->deleteResource(request);// 处理响应...
}

三、认证与授权机制

1. 基本认证

// 设置基本认证
void setBasicAuth(const QString &username, const QString &password) {QString credentials = username + ":" + password;QByteArray encoded = credentials.toUtf8().toBase64();authHeader = "Basic " + encoded;
}// 在请求中应用认证
void applyAuth(QNetworkRequest &request) {if (!authHeader.isEmpty()) {request.setRawHeader("Authorization", authHeader);}
}

2. OAuth2 认证

// 设置 OAuth2 令牌
void setOAuthToken(const QString &token) {authHeader = "Bearer " + token.toUtf8();
}// 刷新 OAuth2 令牌
void refreshToken() {// 实现令牌刷新逻辑QJsonObject data;data["grant_type"] = "refresh_token";data["refresh_token"] = refreshToken;QJsonObject response = post(tokenUrl, data);if (response.contains("access_token")) {setOAuthToken(response["access_token"].toString());refreshToken = response["refresh_token"].toString();}
}

四、错误处理与重试机制

1. 完善的错误处理

// 处理 HTTP 状态码
void handleResponse(QNetworkReply *reply) {QJsonObject result;if (reply->error() != QNetworkReply::NoError) {result["error"] = reply->errorString();result["error_code"] = reply->error();emit requestFailed(result);return;}// 检查 HTTP 状态码int statusCode = reply->attribute(QNetworkRequest::HttpStatusCodeAttribute).toInt();if (statusCode >= 400) {QByteArray data = reply->readAll();QJsonDocument doc = QJsonDocument::fromJson(data);if (doc.isObject()) {result = doc.object();} else {result["error"] = "HTTP error";result["status_code"] = statusCode;}emit requestFailed(result);return;}// 处理成功响应QByteArray data = reply->readAll();QJsonDocument doc = QJsonDocument::fromJson(data);if (doc.isObject()) {result = doc.object();emit requestSuccess(result);} else {result["error"] = "Invalid JSON response";emit requestFailed(result);}
}

2. 智能重试机制

// 带重试的请求
QJsonObject requestWithRetry(const QString &method, const QString &url, const QJsonObject &data = QJsonObject(), int retries = 3) {for (int attempt = 0; attempt < retries; ++attempt) {QJsonObject result;if (method == "GET") {result = get(url);} else if (method == "POST") {result = post(url, data);} // 其他方法...// 检查是否需要重试if (!result.contains("error")) {return result;}// 处理特定错误（如网络超时）QString error = result["error"].toString();if (error.contains("timeout") || error.contains("network")) {qDebug() << "Request failed, retrying (" << attempt + 1 << "/" << retries << ")";QThread::sleep(1);  // 等待1秒后重试continue;}// 其他错误不重试return result;}// 所有重试都失败QJsonObject errorResult;errorResult["error"] = "Max retries exceeded";return errorResult;
}

五、REST API 客户端封装

1. 完整的 REST 客户端

class RestApiClient : public QObject {Q_OBJECT
public:explicit RestApiClient(const QString &baseUrl, QObject *parent = nullptr): QObject(parent), baseUrl(baseUrl) {manager = new QNetworkAccessManager(this);}// 设置认证信息void setBasicAuth(const QString &username, const QString &password);void setOAuthToken(const QString &token);// 请求方法QJsonObject get(const QString &path, const QMap<QString, QString> &params = {});QJsonObject post(const QString &path, const QJsonObject &data, const QMap<QString, QString> &headers = {});QJsonObject put(const QString &path, const QJsonObject &data);QJsonObject del(const QString &path);// 异步请求void getAsync(const QString &path, const QMap<QString, QString> &params = {});void postAsync(const QString &path, const QJsonObject &data);// 设置超时void setTimeout(int timeoutMs) { this->timeout = timeoutMs; }signals:void requestSuccess(const QJsonObject &result);void requestFailed(const QJsonObject &error);private:QString baseUrl;QNetworkAccessManager *manager;QByteArray authHeader;int timeout = 30000;  // 默认30秒超时// 内部方法QNetworkRequest createRequest(const QString &path, const QMap<QString, QString> &headers = {});void applyAuth(QNetworkRequest &request);QJsonObject processResponse(QNetworkReply *reply);
};

六、与 Qt 框架集成

1. 与 Qt Quick 集成

// 在 Qt Quick 中使用 REST 客户端
class QmlRestClient : public QObject {Q_OBJECTQ_PROPERTY(bool busy READ busy NOTIFY busyChanged)Q_PROPERTY(QString error READ error NOTIFY errorChanged)public:explicit QmlRestClient(QObject *parent = nullptr) : QObject(parent) {restClient = new RestApiClient("https://api.example.com", this);connect(restClient, &RestApiClient::requestSuccess, this, &QmlRestClient::onSuccess);connect(restClient, &RestApiClient::requestFailed, this, &QmlRestClient::onFailed);}Q_INVOKABLE void get(const QString &path) {setBusy(true);restClient->getAsync(path);}Q_INVOKABLE void post(const QString &path, const QVariantMap &data) {setBusy(true);QJsonObject jsonData = QJsonObject::fromVariantMap(data);restClient->postAsync(path, jsonData);}// Getters for propertiesbool busy() const { return m_busy; }QString error() const { return m_error; }signals:void responseReceived(const QVariantMap &response);void busyChanged();void errorChanged();private slots:void onSuccess(const QJsonObject &result) {setBusy(false);setError("");emit responseReceived(result.toVariantMap());}void onFailed(const QJsonObject &error) {setBusy(false);setError(error["error"].toString());}private:void setBusy(bool busy) {if (m_busy != busy) {m_busy = busy;emit busyChanged();}}void setError(const QString &error) {if (m_error != error) {m_error = error;emit errorChanged();}}private:RestApiClient *restClient;bool m_busy = false;QString m_error;
};

七、性能优化与最佳实践

1. 连接池优化

// 使用单个 QNetworkAccessManager 实例
// 确保在整个应用程序中只使用一个 QNetworkAccessManager 实例
// 这样可以共享连接池，提高性能
static QNetworkAccessManager* getSharedManager() {static QNetworkAccessManager* manager = nullptr;if (!manager) {manager = new QNetworkAccessManager();// 配置管理器...}return manager;
}

2. 异步处理大响应

// 处理大响应数据
void downloadLargeFile(const QString &url, const QString &savePath) {QNetworkRequest request(url);QNetworkReply *reply = manager->get(request);QFile file(savePath);if (!file.open(QIODevice::WriteOnly)) {emit downloadFailed("Cannot open file for writing");reply->abort();return;}connect(reply, &QNetworkReply::readyRead, this, [&file, reply]() {file.write(reply->readAll());});connect(reply, &QNetworkReply::finished, this, [&file, reply, savePath, this]() {file.close();if (reply->error() == QNetworkReply::NoError) {emit downloadCompleted(savePath);} else {QFile::remove(savePath);emit downloadFailed(reply->errorString());}reply->deleteLater();});
}