`tornado.routing` — 基本路由实现¶

灵活的路由实现。

Tornado 使用 Router 类实现将 HTTP 请求路由到相应的处理程序。 tornado.web.Application 类是一个 Router 实现，可以直接使用，或者可以使用本模块中的类来获得额外的灵活性。 RuleRouter 类可以匹配比 Application 更多的标准，或者可以子类化 Router 接口以实现最大程度的自定义。

Router 接口扩展了 HTTPServerConnectionDelegate 以提供额外的路由功能。这也意味着任何 Router 实现都可以直接用作 HTTPServer 构造函数的 request_callback。

Router 子类必须实现一个 find_handler 方法以提供一个合适的 HTTPMessageDelegate 实例来处理请求

class CustomRouter(Router):
    def find_handler(self, request, **kwargs):
        # some routing logic providing a suitable HTTPMessageDelegate instance
        return MessageDelegate(request.connection)

class MessageDelegate(HTTPMessageDelegate):
    def __init__(self, connection):
        self.connection = connection

    def finish(self):
        self.connection.write_headers(
            ResponseStartLine("HTTP/1.1", 200, "OK"),
            HTTPHeaders({"Content-Length": "2"}),
            b"OK")
        self.connection.finish()

router = CustomRouter()
server = HTTPServer(router)

Router 实现的主要职责是提供一个从请求到 HTTPMessageDelegate 实例的映射，该实例将处理此请求。在上面的示例中，我们可以看到即使没有实例化 Application，路由也是可能的。

为了路由到 RequestHandler 实现，我们需要一个 Application 实例。 get_handler_delegate 提供了一种方便的方法来为给定的请求和 RequestHandler 创建 HTTPMessageDelegate。

以下是一个简单的示例，说明如何通过 HTTP 方法将路由到 RequestHandler 子类。

resources = {}

class GetResource(RequestHandler):
    def get(self, path):
        if path not in resources:
            raise HTTPError(404)

        self.finish(resources[path])

class PostResource(RequestHandler):
    def post(self, path):
        resources[path] = self.request.body

class HTTPMethodRouter(Router):
    def __init__(self, app):
        self.app = app

    def find_handler(self, request, **kwargs):
        handler = GetResource if request.method == "GET" else PostResource
        return self.app.get_handler_delegate(request, handler, path_args=[request.path])

router = HTTPMethodRouter(Application())
server = HTTPServer(router)

ReversibleRouter 接口添加了区分路由并将其反转为原始 URL 的功能，可以使用路由的名称和其他参数。 Application 本身就是 ReversibleRouter 类的实现。

RuleRouter 和 ReversibleRuleRouter 是 Router 和 ReversibleRouter 接口的实现，可用于创建基于规则的路由配置。

规则是 Rule 类的实例。它们包含一个 Matcher，该 Matcher 提供确定规则是否与特定请求匹配的逻辑，以及一个目标，该目标可以是以下之一。

HTTPServerConnectionDelegate 的实例

router = RuleRouter([
    Rule(PathMatches("/handler"), ConnectionDelegate()),
    # ... more rules
])

class ConnectionDelegate(HTTPServerConnectionDelegate):
    def start_request(self, server_conn, request_conn):
        return MessageDelegate(request_conn)

一个接受 HTTPServerRequest 类型单个参数的可调用对象

router = RuleRouter([
    Rule(PathMatches("/callable"), request_callable)
])

def request_callable(request):
    request.write(b"HTTP/1.1 200 OK\r\nContent-Length: 2\r\n\r\nOK")
    request.finish()

另一个 Router 实例

router = RuleRouter([
    Rule(PathMatches("/router.*"), CustomRouter())
])

当然，嵌套的 RuleRouter 或 Application 是允许的

router = RuleRouter([
    Rule(HostMatches("example.com"), RuleRouter([
        Rule(PathMatches("/app1/.*"), Application([(r"/app1/handler", Handler)])),
    ]))
])

server = HTTPServer(router)

在下面的示例中，RuleRouter 用于在应用程序之间进行路由。

app1 = Application([
    (r"/app1/handler", Handler1),
    # other handlers ...
])

app2 = Application([
    (r"/app2/handler", Handler2),
    # other handlers ...
])

router = RuleRouter([
    Rule(PathMatches("/app1.*"), app1),
    Rule(PathMatches("/app2.*"), app2)
])

server = HTTPServer(router)

有关应用程序级路由的更多信息，请参阅 Application 的文档。

版本 4.5 中的新增功能。

class tornado.routing.Router[source]¶

抽象路由器接口。

find_handler(request: HTTPServerRequest, **kwargs: Any) → Optional[HTTPMessageDelegate][source]¶

必须实现以返回一个合适的 HTTPMessageDelegate 实例来处理请求。路由实现可能会传递额外的关键字参数来扩展路由逻辑。

参数

request (httputil.HTTPServerRequest) – 当前 HTTP 请求。
kwargs – 路由实现传递的额外关键字参数。

返回值

一个将用于处理请求的 HTTPMessageDelegate 实例。

class tornado.routing.ReversibleRouter[source]¶

用于可以处理命名路由并支持将其反转为原始 URL 的路由器的抽象路由器接口。

reverse_url(name: str, *args: Any) → Optional[str][source]¶

返回给定路由名称和参数的 URL 字符串，如果未找到匹配项，则返回 None。

参数

name (str) – 路由名称。
args – URL 参数。

返回值

给定路由名称的参数化 URL 字符串（或 None）。

class tornado.routing.RuleRouter(rules: Optional[List[Union[Rule, List[Any], Tuple[Union[str, Matcher], Any], Tuple[Union[str, Matcher], Any, Dict[str, Any]], Tuple[Union[str, Matcher], Any, Dict[str, Any], str]]]] = None)[source]¶

基于规则的路由器实现。

从规则的有序列表构建路由器

RuleRouter([
    Rule(PathMatches("/handler"), Target),
    # ... more rules
])

您也可以省略显式 Rule 构造函数，并使用参数元组

RuleRouter([
    (PathMatches("/handler"), Target),
])

PathMatches 是默认匹配器，因此上面的示例可以简化为

RuleRouter([
    ("/handler", Target),
])

在上面的示例中，Target 可以是嵌套的 Router 实例、HTTPServerConnectionDelegate 的实例或旧式可调用函数，接受请求参数。

参数: rules – Rule 实例的列表或 Rule 构造函数参数的元组。

add_rules(rules: List[Union[Rule, List[Any], Tuple[Union[str, Matcher], Any], Tuple[Union[str, Matcher], Any, Dict[str, Any]], Tuple[Union[str, Matcher], Any, Dict[str, Any], str]]]) → None[source]¶

将新规则附加到路由器。

参数: rules – 一系列 Rule 实例（或参数元组，传递给 Rule 构造函数）。

process_rule(rule: Rule) → Rule[source]¶

覆盖此方法以对每个规则进行额外的预处理。

参数: rule (Rule) – 要处理的规则。
返回值: 相同的或修改后的 Rule 实例。

get_target_delegate(target: Any, request: HTTPServerRequest, **target_params: Any) → Optional[HTTPMessageDelegate][source]¶

为 Rule 的目标返回 HTTPMessageDelegate 实例。此方法由 find_handler 调用，可以扩展以提供其他目标类型。

参数

target – Rule 的目标。
request (httputil.HTTPServerRequest) – 当前请求。
target_params – 其他参数，可能对 HTTPMessageDelegate 创建有用。

class tornado.routing.ReversibleRuleRouter(rules: Optional[List[Union[Rule, List[Any], Tuple[Union[str, Matcher], Any], Tuple[Union[str, Matcher], Any, Dict[str, Any]], Tuple[Union[str, Matcher], Any, Dict[str, Any], str]]]] = None)[source]¶

一个基于规则的路由器，它实现了 reverse_url 方法。

添加到此路由器的每个规则都可能有一个 name 属性，可用于重建原始 uri。实际的重建发生在规则的匹配器中（参见 Matcher.reverse）。

class tornado.routing.Rule(matcher: Matcher, target: Any, target_kwargs: Optional[Dict[str, Any]] = None, name: Optional[str] = None)[source]¶

路由规则。

构造一个 Rule 实例。

参数

matcher (Matcher) – 用于确定规则是否应该被视为特定请求匹配的 Matcher 实例。
target – Rule 的目标（通常是 RequestHandler 或 HTTPServerConnectionDelegate 子类，甚至可能是嵌套的 Router，取决于路由实现）。
target_kwargs (dict) – 在目标实例化时可能会有用的参数字典（例如，status_code 用于 RequestHandler 子类）。它们最终在 target_params['target_kwargs'] 中 RuleRouter.get_target_delegate 方法。
name (str) – 规则的名称，可用于在 ReversibleRouter.reverse_url 实现中找到它。

class tornado.routing.Matcher[source]¶

表示请求特征的匹配器。

match(request: HTTPServerRequest) → Optional[Dict[str, Any]][source]¶

将当前实例与请求进行匹配。

参数: request (httputil.HTTPServerRequest) – 当前 HTTP 请求
返回值: 要传递给目标处理程序的参数字典（例如，handler_kwargs、path_args、path_kwargs 可以传递用于正确实例化 RequestHandler）。空字典是有效的（也是常见的）返回值，表示匹配时未使用参数传递功能。必须返回 None 以指示没有匹配。

reverse(*args: Any) → Optional[str][source]¶: 从匹配器实例和附加参数重建完整 URL。

class tornado.routing.AnyMatches[source]¶: 匹配任何请求。

class tornado.routing.HostMatches(host_pattern: Union[str, Pattern])[source]¶: 匹配来自由 host_pattern 正则表达式指定的宿主的请求。

class tornado.routing.DefaultHostMatches(application: Any, host_pattern: Pattern)[source]¶: 匹配来自与应用程序的 default_host 相等的宿主的请求。如果存在 X-Real-Ip 头部，则始终返回不匹配。

class tornado.routing.PathMatches(path_pattern: Union[str, Pattern])[source]¶: 匹配路径由 path_pattern 正则表达式指定的请求。

class tornado.routing.URLSpec(pattern: Union[str, Pattern], handler: Any, kwargs: Optional[Dict[str, Any]] = None, name: Optional[str] = None)[source]¶

指定 URL 和处理程序之间的映射。

参数

pattern：要匹配的正则表达式。正则表达式中的任何捕获组都将作为参数传递给处理程序的 get/post/etc 方法（如果命名，则按关键字传递，如果未命名，则按位置传递。命名和未命名捕获组不能在同一个规则中混合使用）。
handler：要调用的 RequestHandler 子类。
kwargs（可选）：要传递给处理程序构造函数的附加参数字典。
name（可选）：此处理程序的名称。由 reverse_url 使用。

tornado.routing — 基本路由实现¶

`tornado.routing` — 基本路由实现¶