ColorPalette RESTful API 客户端

本示例演示了如何使用 Qt OpenAPI 生成器，根据colorpalette.yaml 规范生成 RESTful API 客户端代码，并将其集成到 QML 应用程序中。其结构和用户界面与Qt Quick 演示——RESTful API 客户端示例高度一致，以便于识别网络通信和集成方法上的差异。

运行示例

您可以通过以下方式运行该示例：

• Qt Creator

  打开“Welcome ”模式，并从“Examples ”中选择该示例。有关更多信息，请参阅Qt Creator ：教程：构建与运行。

• Qt Extension for Visual Studio Code

  在Command Palette 中运行Qt: Open Qt examples 命令，并从列表中选择该示例。有关详细信息，请参阅Qt Extension for Visual Studio Code ：教程：构建和运行。

应用程序功能

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

服务器选择

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

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

一旦选择服务器并点击“Connect ”按钮，RESTful API 客户端将发出一个测试性的 HTTP GET 请求，以验证服务器是否可用。如果服务器未运行，应用程序将保持在服务器选择界面。

根据 OpenAPI 规范生成客户端代码

CMakeLists.txt 文件通过调用qt_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 。示例在ApiBridges.h 中提供了 QML 单例，用于构造此类类型的实例：

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;
    }
};

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

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

源文件

示例项目 @ code.qt.io