`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，它提供了判斷規則是否與特定請求匹配的邏輯，以及一個目標，該目標可以是以下之一。

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[原始碼]¶

抽象路由介面。

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

必須實作以傳回一個適當的 HTTPMessageDelegate 實例，該實例可以服務該請求。路由實作可以傳遞額外的 kwargs 來擴展路由邏輯。

參數

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[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)[原始碼]¶

基於規則的路由器實作。

從規則的有序清單建構路由器

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[原始碼]¶

將新規則附加到路由器。

參數: rules – Rule 實例的清單（或是傳遞給 Rule 建構函式的引數元組）。

process_rule(rule: Rule) → Rule[原始碼]¶

覆寫此方法以進行每個規則的額外預處理。

參數: rule (Rule) – 要處理的規則。
傳回: 相同或修改後的 Rule 實例。

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

為 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)[原始碼]¶

一個基於規則的路由器，它實現了 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)[原始碼]¶

一個路由規則。

建構一個 Rule 實例。

參數

matcher (Matcher) – 一個 Matcher 實例，用於確定是否應將該規則視為與特定請求匹配。
target – Rule 的目標（通常是 RequestHandler 或 HTTPServerConnectionDelegate 子類，甚至是一個巢狀的 Router，取決於路由實作）。
target_kwargs (dict) – 一個參數字典，在目標實例化時可能有用（例如，RequestHandler 子類的 status_code）。它們最終會出現在 RuleRouter.get_target_delegate 方法的 target_params['target_kwargs'] 中。
name (str) – 規則的名稱，可用於在 ReversibleRouter.reverse_url 實作中找到它。

class tornado.routing.Matcher[原始碼]¶

表示請求特性的匹配器。

match(request: HTTPServerRequest) → Optional[Dict[str, Any]][原始碼]¶

將當前實例與請求進行匹配。

參數: request (httputil.HTTPServerRequest) – 當前的 HTTP 請求
傳回: 一個要傳遞給目標處理器的參數字典（例如，可以傳遞 handler_kwargs、path_args、path_kwargs 以便正確地實例化 RequestHandler）。當不使用參數傳遞功能時，空字典是一個有效（且常見）的返回值，表示匹配成功。必須返回 None 來表示沒有匹配。

reverse(*args: Any) → Optional[str][原始碼]¶: 從匹配器實例和附加參數重建完整的 URL。

class tornado.routing.AnyMatches[原始碼]¶: 匹配任何請求。

class tornado.routing.HostMatches(host_pattern: Union[str, Pattern])[原始碼]¶: 匹配來自 host_pattern 正規表達式指定的 host 的請求。

class tornado.routing.DefaultHostMatches(application: Any, host_pattern: Pattern)[原始碼]¶: 匹配來自與應用程式 default_host 相等的 host 的請求。如果存在 X-Real-Ip header，則始終返回不匹配。

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: 要匹配的正規表達式。正規表達式中的任何捕獲群組都將作為參數傳遞給處理器的 get/post/等方法（如果已命名，則按關鍵字傳遞；如果未命名，則按位置傳遞。命名和未命名的捕獲群組不能在同一規則中混合使用）。
handler: 要調用的 RequestHandler 子類別。
kwargs (可選): 要傳遞給處理器建構子的其他參數字典。
name (可選): 此處理器的名稱。由 reverse_url 使用。

tornado.routing — 基本路由實作¶

`tornado.routing` — 基本路由實作¶