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

在现代软件开发中，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_OBJECT
    Q_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 properties
    bool 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();
    });
}

八、总结

通过 Qt 的网络模块，开发者可以轻松实现高效、可靠的 RESTful API 调用。本文详细介绍了 REST 请求的构建、认证机制的实现、错误处理与重试策略，以及与 Qt 框架的集成方法。合理应用这些技术，可以帮助你构建出更健壮、更高效的网络应用，实现客户端与服务器的无缝通信。