tornado.routing ——基本路由实现

灵活的路由实现。

Tornado使用 Router 类实现。这个 tornado.web.Application 类是 Router 实现，可以直接使用，也可以使用此模块中的类来增加灵活性。这个 RuleRouter 类的匹配条件超过 Application ，或者 Router 接口可以被子类化以实现最大的自定义。

Router 接口扩展 HTTPServerConnectionDelegate 提供额外的路由功能。这也意味着 Router 实现可以直接用作 request_callback 对于 HTTPServer 建造师。

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 提供了一种方便的创建方法 HTTPMessageDelegate 对于给定的请求和 RequestHandler .

下面是一个简单的例子，说明我们如何路由到 RequestHandler HTTP方法的子类：

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 ，它提供用于确定规则是否与特定请求和目标匹配的逻辑，目标可以是以下之一。

1. 的实例 HTTPServerConnectionDelegate ：

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

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

2. 可调用的接受单个参数 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()

3. 另一 Router 实例：

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

当然是嵌套的 RuleRouter 或A 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

抽象路由接口。

find_handler(request: tornado.httputil.HTTPServerRequest, **kwargs: Any) → Optional[tornado.httputil.HTTPMessageDelegate]

必须实现以返回 HTTPMessageDelegate 这可以满足要求。路由实现可能会通过额外的限制来扩展路由逻辑。

参数

• request (httputil.HTTPServerRequest) -- 当前HTTP请求。

• kwargs -- 路由实现传递的其他关键字参数。

返回

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

class tornado.routing.ReversibleRouter

路由器的抽象路由器接口，可以处理命名路由并支持将它们转换为原始URL。

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

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

参数

• name (str) -- 路由名称。

• args -- URL参数。

返回

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

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

基于规则的路由器实现。

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

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[tornado.routing.Rule, List[Any], Tuple[Union[str, tornado.routing.Matcher], Any], Tuple[Union[str, tornado.routing.Matcher], Any, Dict[str, Any]], Tuple[Union[str, tornado.routing.Matcher], Any, Dict[str, Any], str]]]) → None

将新规则附加到路由器。

参数

rules -- 规则实例列表（或传递给规则构造函数的参数元组）。

process_rule(rule: tornado.routing.Rule) → tornado.routing.Rule

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

参数

rule (Rule) -- 要处理的规则。

返回

相同或已修改的规则实例。

get_target_delegate(target: Any, request: tornado.httputil.HTTPServerRequest, **target_params: Any) → Optional[tornado.httputil.HTTPMessageDelegate]

返回的实例 HTTPMessageDelegate 规则的目标。此方法由调用 find_handler 并且可以扩展以提供其他目标类型。

参数

• target -- 规则的目标。

• request (httputil.HTTPServerRequest) -- 当前请求。

• target_params -- 其他参数可用于 HTTPMessageDelegate 创造。

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

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

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

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

路由规则。

构造规则实例。

参数

• matcher (Matcher) -- 一 Matcher 用于确定是否应将规则视为特定请求的匹配项的实例。

• target -- 规则的目标（通常是 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

表示请求功能的匹配器。

match(request: tornado.httputil.HTTPServerRequest) → Optional[Dict[str, Any]]

根据请求匹配当前实例。

参数

request (httputil.HTTPServerRequest) -- 当前HTTP请求

返回

要传递给目标处理程序的参数的dict（例如， handler_kwargs ， path_args ， path_kwargs 可适当通过 RequestHandler 实例化）。空dict是一个有效（也是公共）返回值，用于在不使用参数传递功能时指示匹配。 None 必须返回以指示没有匹配项。

reverse(*args: Any) → Optional[str]

从Matcher实例和其他参数重建完整的URL。

class tornado.routing.AnyMatches

匹配任何请求。

class tornado.routing.HostMatches(host_pattern: Union[str, Pattern])

匹配由指定的主机发出的请求 host_pattern 正则表达式

class tornado.routing.DefaultHostMatches(application: Any, host_pattern: Pattern)

匹配来自等于应用程序默认主机的主机的请求。始终返回不匹配条件 X-Real-Ip 存在标题。

class tornado.routing.PathMatches(path_pattern: Union[str, Pattern])

将请求与指定的路径匹配 path_pattern 正则表达式

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

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

参数：

• pattern ：要匹配的正则表达式。regex中的任何捕获组都将作为参数传入处理程序的get/post/etc方法（如果已命名，则按关键字，如果未命名，则按位置）。命名和未命名的捕获组不能在同一规则中混合）。

• handler ： RequestHandler 要调用的子类。

• kwargs （可选）：要传递给处理程序的构造函数的其他参数的字典。

• name （可选）：此处理程序的名称。被使用 reverse_url .