ColorPalette RESTful API 客户端

该示例演示了如何使用 Qt OpenAPI 生成器从colorpalette.yaml 规范中创建 RESTful API 客户端代码并将其集成到 Qt XML 应用程序中。它的结构和用户界面与Qt Quick Demo - RESTful API 客户端示例非常相似，因此很容易识别网络和集成方法的不同之处。

运行示例

要从 Qt Creator，打开Welcome 模式并从Examples 中选择示例。更多信息，请参阅Qt Creator: 教程：构建和运行。

应用程序功能

该示例提供的基本功能与Qt Quick Demo - RESTful API 客户端相同。

服务器选择

启动时，应用程序会显示 Color Palette 客户端可与之通信的预定义服务器选项：

• 基于 Qt 的 REST API 服务器示例 QtHttpServer

选择服务器并按下Connect 按钮后，RESTful API 客户端就会发出一个测试 HTTP GET 请求，以验证服务器是否可用。如果服务器未运行，应用程序将保留在服务器选择视图中。

从 OpenAPI 规范生成客户端代码

CMakeLists.txt 文件通过调用qt6_add_openapi_client函数，调用 Qt OpenAPI 生成器从colorpalette.yaml 规范生成客户端代码。

qt_add_openapi_client(ColorpaletteClientExample
    SPEC_FILE
        ${CMAKE_CURRENT_SOURCE_DIR}/colorpalette.yaml
)

生成的 API 类ColorsApi 和UsersApi 处理所有底层 HTTP 细节：

• 服务器配置
• 为所有标准 HTTP 方法构建 HTTP 请求
• 根据规范序列化输入参数
• 将服务器响应反序列化为类型化对象
• 通过 Qt 信号报告成功和错误

与直接使用 QtNetworkAuth API的其他版本示例相比，这种方法无需手动构建网络请求。

将生成的 API 暴露于 QML

生成的 API 类ColorsApi 和UsersApi 通过ApiBridges.h 中定义的辅助类暴露给 QML。每个辅助类都使用QML_FOREIGN 宏，并将底层 C++ 实例注册为单例，允许 QML 访问同一对象，而所有权仍在 C++ 中。有关此主题的更多详情，请查看 Qt Qml 文档中关于将现有对象公开为单例的内容。

struct ForeignColorsAPI
{
    Q_GADGET
    QML_FOREIGN(QtOpenAPI::ColorsApi)
    QML_SINGLETON
    QML_NAMED_ELEMENT(ColorsApi)

};

使用 QML 的 API

一旦注册，API 在 QML 中全局可用。这允许 QML 组件直接访问ColorsApi 和UsersApi 并调用它们的方法，如下所示：

ColorsApi.getColors(page)

每个 API 方法都会在操作成功或失败时发出信号，允许 QML 组件处理服务器响应：

function onAddColorFinished() {
    root.fetchColors(root.currentColorPage)
}

function onAddColorErrorOccurred(errorType, errorStr) {
    root.handleError(errorStr)
}

辅助单例类型

有些 API 方法采用非三元类型作为参数，如Credentials 和Color 。该示例提供了 QML 单子，用于在ApiBridges.h 中构建此类类型的实例：

class Credentials: public QObject
{
    Q_OBJECT
    QML_ELEMENT
    QML_SINGLETON
public:
    Q_INVOKABLE QtOpenAPI::Credentials create(const QString &email, const QString &password)
    {
        QtOpenAPI::Credentials credentials;
        credentials.setEmail(email);
        credentials.setPassword(password);
        return credentials;
    }
};

在调用 API 方法时，这些单例可在 QML 中使用。例如，Credentials 用来在登录前创建凭证对象：

let credentials = Credentials.create(userInfo.model.email, "apassword");
UsersApi.loginUser(credentials);

源文件

示例项目 @ code.qt.io