RESTful API 服务器

使用 `QHttpServer` 创建 RESTful API 服务器的示例。

Qt HTTP RESTful API 服务器

本示例演示了如何在小型应用程序中使用QHttpServer 类来创建和托管简单的 RESTful Web API。该服务器接受 REST 风格的调用，并可与客户端对应的示例RESTful 颜色调色板 API 客户端配合使用。

符合 REST 约束条件的应用程序通常被非正式地称为“RESTful”。该 RESTful API 服务器支持对颜色（为兼容 Reqres API 而设定的未知资源）和用户执行创建、读取、更新和删除操作。此外，该服务器还提供登录/注销功能。本示例基于Reqres API 构建。

要运行服务器应用程序，请执行服务器二进制文件：

./colorpaletteserver

或

./colorpaletteserver --port 1234

可选的port 参数用于指定服务器运行的端口。

httpServer.route(
        QString("%1").arg(apiPath), QHttpServerRequest::Method::Get,
        [&api](const QHttpServerRequest &request) { return api.getPaginatedList(request); });

在上例中，为 GET 方法指定了路由，该方法会返回包含已存储项目分页列表的 JSON 数组。为此，使用了QHttpServer::route() 方法并配合QHttpServerRequest::Method::Get 枚举。

httpServer.route(QString("%1/<arg>").arg(apiPath), QHttpServerRequest::Method::Get,
                 [&api](qint64 itemId) { return api.getItem(itemId); });

若要从实体列表中获取单个项目，需在请求查询中传入该项目的 ID。

httpServer.route(QString("%1").arg(apiPath), QHttpServerRequest::Method::Post,
                 [&api, &sessionApi](const QHttpServerRequest &request) {
                     if (!sessionApi.authorize(request)) {
                         return QHttpServerResponse(
                                 QHttpServerResponder::StatusCode::Unauthorized);
                     }
                     return api.postItem(request);
                 });

在此示例中，该路由接受 POST 方法，该方法将向项目列表中添加一条新条目，并返回一个表示所添加条目的 JSON 对象。此请求必须经过授权。要授权该请求，TOKEN 头部的值必须与先前通过api/login 或api/register 方法返回的令牌相等。

QHttpServerResponse postItem(const QHttpServerRequest &request)
{
    const std::optional<QJsonObject> json = byteArrayToJsonObject(request.body());
    if (!json)
        return QHttpServerResponse(QHttpServerResponder::StatusCode::BadRequest);

    const std::optional<T> item = factory->fromJson(*json);
    if (!item)
        return QHttpServerResponse(QHttpServerResponder::StatusCode::BadRequest);
    if (data.contains(item->id))
        return QHttpServerResponse(QHttpServerResponder::StatusCode::AlreadyReported);

    const auto entry = data.insert(item->id, *item);
    return QHttpServerResponse(entry->toJson(), QHttpServerResponder::StatusCode::Created);
}

除了作为 JSON 对象的新条目外，POST 方法还会返回不同的 HTTP 状态码：新增条目返回Created ，已存在条目返回AlreadyReported 。本示例利用了QHttpServerResponse::QHttpServerResponse 的重载，用于发送 JSON 对象及相应的 HTTP 状态码。

要创建条目，请求正文必须是一个包含email 、first_name 、last_name 和avatar 字段的 JSON 对象——用于创建新用户。例如：

{
    "email": "jane.doe@qt.io",
    "first_name": "Jane",
    "last_name": "Doe",
    "avatar": "/img/faces/1-image.jpg"
}

文件：

图片：

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.