Back to Qt.io
Contact Us Blog Download Qt

QHttpServerRouterRule Class

QHttpServerRouterRule 是QHttpServerRouter 规则的基类。更多

头文件： #include <QHttpServerRouterRule>
CMake： find_package(Qt6 REQUIRED COMPONENTS HttpServer)
target_link_libraries(mytarget PRIVATE Qt6::HttpServer)
qmake： QT += httpserver
自Qt 6.4

公共函数

QHttpServerRouterRule(const QString &pathPattern, const QHttpServerRequest::Methods methods, const QObject *receiver, Functor &&slot)
QHttpServerRouterRule(const QString &pathPattern, const QObject *receiver, Functor &&slot)
virtual ~QHttpServerRouterRule()
const QObject *contextObject() const

静态公共成员

typename ViewTraits::BindableType bindCaptured(QObject *receiver, Functor &&slot, const QRegularExpressionMatch &match)

保护函数

bool exec(const QHttpServerRequest &request, QHttpServerResponder &responder) const
bool hasValidMethods() const
virtual bool matches(const QHttpServerRequest &request, QRegularExpressionMatch *match) const

详细说明

QHttpServerRouterRule 定义了请求路径、HTTP 方法和相应处理程序回调之间的关系。QHttpServerRouter 是这些规则的集合，当请求同时符合路径和方法时，就会执行相应的处理程序。处理程序负责生成响应。

路径和模式

每个 QHttpServerRouterRule 都包含一个路径或模式，用于确定它能处理哪些请求。路径可能包含传递给处理程序的占位符。下面的示例使用QHttpServer::route() 方便方法说明了路径模式，当然也可以使用 QHttpServerRouterRule 构造函数设置路径模式。

在最简单的情况下，路径是一个以"/" 为前导的字符串：

QHttpServer server;
server.route("/user", [] () { return "hello user"; } );

该路径模式定义了一条规则，将所有指向"/user" 的请求都指向指定的处理程序，在本例中，处理程序是一个简单的 lambda 函数。(请注意，直接使用 QHttpServerRouterRule 时，处理程序的语法有所不同--见下文）。

路径模式中的尾部"/" 允许规则匹配"/" 之后带有参数的其他路径。当使用QHttpServer::route() 方便方法时，参数会自动传递给 lambda 函数：

server.route("/user/", [] ( qint64 id ) { return "hello user"; } );

这将匹配"/user/1","/user/2" 等请求路径。

捕获路径中的参数

您可以使用"<arg>" 占位符在路径模式中的任意位置放置参数，而且路径中支持多个参数：

server.route("/user/<arg>/history", [] (qint64 id){ return "hello user"; } );
server.route("/user/<arg>/history/", [] (qint64 id, qint64 page){ return "hello user"; } );

例如，这将匹配"/user/1/history/2" 这样的请求。在QHttpServerRouter::converters() 中注册的任何数据类型都可用于回调函数和路径中的相应占位符。

请求方法

请求方法与QHttpServerRequest::Method 中的值之一相对应。如果在构建规则时没有指定方法，规则将匹配任何已知方法的请求。

处理程序签名

处理程序是具有以下签名的回调函数：

void (*)(const QRegularExpressionMatch &, const QHttpServerRequest &, QHttpServerResponder &);
  • 第一个参数从路径中接收任何匹配的捕获组。
  • 第二个参数包含请求详情。
  • 第三个参数用于发送响应。

向 QHttpServerRouter 添加规则

下面的示例演示了如何在QHttpServerRouter 中用处理程序创建和注册新规则：

template<typename ViewHandler>
void route(const char *path, const QHttpServerRequest::Methods methods, ViewHandler &&viewHandler)
{
    auto rule = std::make_unique<QHttpServerRouterRule>(
            path, methods, [this, viewHandler = std::forward<ViewHandler>(viewHandler)]
                                            (QRegularExpressionMatch &match,
                                             const QHttpServerRequest &request,
                                             QHttpServerResponder &responder) mutable {
        auto boundViewHandler = QHttpServerRouterRule::bindCaptured<ViewHandler>(
                this, std::move(viewHandler), match);
        boundViewHandler(); // Execute the handler
    });

    // Add rule to the router
    router.addRule<ViewHandler>(std::move(rule));
}

// Valid:
route("/user/", [] (qint64 id) { } );                            // Matches "/user/1", "/user/3", etc.
route("/user/<arg>/history", [] (qint64 id) { } );               // Matches "/user/1/history", "/user/2/history"
route("/user/<arg>/history/", [] (qint64 id, qint64 page) { } ); // Matches "/user/1/history/1", "/user/2/history/2"

注： 这是一个低级 API。如需更高级别的 API，请参阅QHttpServer 。

注： 路径模式中不支持正则表达式，但可以使用QHttpServerRouter::addConverter() 将"<arg>" 与特定类型匹配。

成员函数文档

template <typename Functor> QHttpServerRouterRule::QHttpServerRouterRule(const QString &pathPattern, const QHttpServerRequest::Methods methods, const QObject *receiver, Functor &&slot)

为pathPattern 和methods 创建路由规则，将其连接到指定的receiver 和slot 。

  • slot 可以是函数指针、不可变 lambda 或任何其他可使用const 调用操作符的可复制可调用对象。
  • 如果slot 是可调用的，则receiver 将作为其上下文对象。
  • 在receiver 销毁之前，处理程序一直有效。

该规则可以处理任何可用 HTTP 方法的组合。

另请参阅 QHttpServerRequest::Methods 。

template <typename Functor> QHttpServerRouterRule::QHttpServerRouterRule(const QString &pathPattern, const QObject *receiver, Functor &&slot)

此重载为pathPattern 构建路由规则，并将其与receiver 和slot 关联。

  • 它的默认值是QHttpServerRequest::Method::AnyKnown ，这意味着它将匹配任何公认的 HTTP 方法。
  • slot 可以是函数指针、不可变 lambda 或任何其他可复制的可调用const 调用操作符。
  • 如果slot 是可调用的，则receiver 将作为其上下文对象。
  • 处理程序一直有效，直到receiver 被销毁。

这是一个重载函数。

[virtual noexcept] QHttpServerRouterRule::~QHttpServerRouterRule()

销毁QHttpServerRouterRule.

[static] template <typename Functor, typename ViewTraits = QHttpServerRouterViewTraits<Functor>> typename ViewTraits::BindableType QHttpServerRouterRule::bindCaptured(QObject *receiver, Functor &&slot, const QRegularExpressionMatch &match)

使用从 URL 提取的参数绑定给定的receiver 和slot 。函数会返回一个绑定的可调用函数，该函数会获取处理程序所需的任何其余参数，并在 URL 导出值之后将其提供给slot 。

从 URL 中获取的每个值（字符串）都会根据其位置转换为处理程序中相应的参数类型，确保能以match 的形式传递。

QHttpServerRouter路由器；自动pageView= [](constQStringpage, constquint32num) {    qDebug("page: %s, num: %d", qPrintable(page), num);
};usingViewHandler=decltype(pageView);autorule=std::make_unique<QHttpServerRouterRule>("/<arg>/<arg>/log", [&router, &pageView](QRegularExpressionMatch匹配， 常量QHttpServerRequest&request、               QHttpServerResponder&&responder) {// 使用匹配捕获的字符串和 quint32 绑定并调用 viewHandler：    QHttpServerRouterRule::bindCaptured(pageView,match)(); }); router.addRule<ViewHandler>(std::move(rule));

const QObject *QHttpServerRouterRule::contextObject() const

读取与此规则相关联的上下文对象。该对象是负责处理请求的接收器。

[protected] bool QHttpServerRouterRule::exec(const QHttpServerRequest &request, QHttpServerResponder &responder) const

执行规则。通过检查给定的request 是否与此规则匹配来处理它。

  • 当收到新的request 时，QHttpServerRouter 会调用此函数。
  • 如果request 与规则匹配，它将通过提供的responder 发送响应来处理请求，并返回true 。
  • 如果不匹配，则返回false 。

[protected] bool QHttpServerRouterRule::hasValidMethods() const

验证请求方法。如果指定的 HTTP 方法有效，则返回true 。

[virtual protected] bool QHttpServerRouterRule::matches(const QHttpServerRequest &request, QRegularExpressionMatch *match) const

确定所提供的request 是否符合本规则的条件。

  • exec() 调用此虚函数来评估request 。
  • 如果请求匹配，则详细信息将存储在match 中（必须不是 nullptr ），函数将返回true 。
  • 否则，返回false 。

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