RESTful API 服务器

如何使用QHttpServer.NET 类创建 RESTful API 服务器的示例。

本示例展示了如何使用QHttpServer 类在小型应用程序中创建和托管简单的 RESTful Web API。该服务器可接受 REST 风格的调用，并可与客户端上的对应示例RESTful Color Palette API 客户端一起使用。

服从 REST 约束的应用程序可非正式地称为 RESTful。RESTful API 服务器允许对颜色（与 Reqres API 兼容的未知资源）和用户进行创建、读取、更新和删除操作。RESTful 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 状态代码。

要创建条目，请求体必须是一个 JSON 对象，其中包含email first_name last_name 和avatar 字段--用于创建新用户。例如

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

文件：

图像：

© 2025 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.