`tornado.web` — `RequestHandler` 和 `Application` 类¶

tornado.web 提供了一个简单的 Web 框架，具有异步功能，可以扩展到大量开放连接，使其非常适合长轮询.

这是一个简单的“Hello，world”示例应用程序

import asyncio
import tornado

class MainHandler(tornado.web.RequestHandler):
    def get(self):
        self.write("Hello, world")

async def main():
    application = tornado.web.Application([
        (r"/", MainHandler),
    ])
    application.listen(8888)
    await asyncio.Event().wait()

if __name__ == "__main__":
    asyncio.run(main())

有关更多信息，请参阅用户指南.

线程安全注意事项¶

一般来说，RequestHandler 及 Tornado 中其他地方的方法不是线程安全的。特别是，write()、finish() 和 flush() 等方法只能从主线程调用。如果您使用多个线程，重要的是使用 IOLoop.add_callback 在完成请求之前将控制权转回主线程，或者将其他线程的使用限制为 IOLoop.run_in_executor，并确保在执行器中运行的回调不引用 Tornado 对象。

请求处理程序¶

class tornado.web.RequestHandler(...)[source]¶

HTTP 请求处理程序的基类。

子类必须定义下面“入口点”部分中定义的至少一个方法。

应用程序不应直接构造 RequestHandler 对象，子类不应覆盖 __init__（而是覆盖 initialize）。

入口点¶

RequestHandler.initialize() → None¶

子类初始化的钩子。为每个请求调用。

作为 URLSpec 的第三个参数传递的字典将作为关键字参数提供给 initialize()。

示例

class ProfileHandler(RequestHandler):
    def initialize(self, database):
        self.database = database

    def get(self, username):
        ...

app = Application([
    (r'/user/(.*)', ProfileHandler, dict(database=database)),
    ])

RequestHandler.prepare() → Optional[Awaitable[None]][source]¶

在 get/post/等等之前，在请求开始时调用。

覆盖此方法以执行与请求方法无关的通用初始化。

异步支持：使用 async def 或用 gen.coroutine 装饰此方法以使其异步。如果此方法返回一个 Awaitable，则执行将不会继续，直到 Awaitable 完成。

3.1 版新增：异步支持。

RequestHandler.on_finish() → None[source]¶

在请求结束之后调用。

覆盖此方法以执行清理、记录等等。此方法是 prepare 的对应方法。 on_finish 可能不会产生任何输出，因为它是在将响应发送到客户端之后调用的。

实现以下任何方法（统称为 HTTP 动词方法）以处理相应的 HTTP 方法。可以使用 async def 关键字或 gen.coroutine 装饰器使这些方法异步。

这些方法的参数来自 URLSpec：正则表达式中的任何捕获组都成为 HTTP 动词方法的参数（如果组是命名的，则为关键字参数；如果组是未命名的，则为位置参数）。

要支持不在此列表中的方法，请覆盖类变量 SUPPORTED_METHODS

class WebDAVHandler(RequestHandler):
    SUPPORTED_METHODS = RequestHandler.SUPPORTED_METHODS + ('PROPFIND',)

    def propfind(self):
        pass

RequestHandler.get(*args: str, **kwargs: str) → None¶

RequestHandler.head(*args: str, **kwargs: str) → None¶

RequestHandler.post(*args: str, **kwargs: str) → None¶

RequestHandler.delete(*args: str, **kwargs: str) → None¶

RequestHandler.patch(*args: str, **kwargs: str) → None¶

RequestHandler.put(*args: str, **kwargs: str) → None¶

RequestHandler.options(*args: str, **kwargs: str) → None¶

输入¶

The argument 方法提供对 HTML 表单样式参数的支持。这些方法在单数和复数形式中都可用，因为 HTML 表单是模棱两可的，不区分单个参数和包含一个条目的列表。如果您希望使用其他格式的参数（例如 JSON），请自行解析 self.request.body

def prepare(self):
    if self.request.headers['Content-Type'] == 'application/x-json':
        self.args = json_decode(self.request.body)
    # Access self.args directly instead of using self.get_argument.

RequestHandler.get_argument(name: str, default: str, strip: bool = True) → str[source]¶

RequestHandler.get_argument(name: str, default: _ArgDefaultMarker = _ARG_DEFAULT, strip: bool = True) → str

RequestHandler.get_argument(name: str, default: None, strip: bool = True) → Optional[str]

返回具有给定名称的参数的值。

如果未提供 default，则该参数被认为是必需的，如果该参数缺失，我们将引发 MissingArgumentError。

如果该参数在请求中出现多次，我们将返回最后一个值。

此方法同时搜索查询参数和主体参数。

RequestHandler.get_arguments(name: str, strip: bool = True) → List[str][source]¶

返回具有给定名称的参数列表。

如果该参数不存在，则返回一个空列表。

此方法同时搜索查询参数和主体参数。

RequestHandler.get_query_argument(name: str, default: Union[None, str, RAISE] = RAISE, strip: bool = True) → Optional[str][source]¶

返回来自请求查询字符串中具有给定名称的参数的值。

如果未提供 default，则该参数被认为是必需的，如果该参数缺失，我们将引发 MissingArgumentError。

如果该参数在 url 中出现多次，我们将返回最后一个值。

3.2 版本新增。

RequestHandler.get_query_arguments(name: str, strip: bool = True) → List[str][source]¶

返回给定名称的查询参数列表。

如果该参数不存在，则返回一个空列表。

3.2 版本新增。

RequestHandler.get_body_argument(name: str, default: Union[None, str, RAISE] = RAISE, strip: bool = True) → Optional[str][source]¶

从请求体中返回给定名称的参数的值。

如果未提供 default，则该参数被认为是必需的，如果该参数缺失，我们将引发 MissingArgumentError。

如果该参数在 url 中出现多次，我们将返回最后一个值。

3.2 版本新增。

RequestHandler.get_body_arguments(name: str, strip: bool = True) → List[str][source]¶

返回给定名称的请求体参数列表。

如果该参数不存在，则返回一个空列表。

3.2 版本新增。

RequestHandler.decode_argument(value: bytes, name: Optional[str] = None) → str[source]¶

解码来自请求的参数。

参数已进行百分号解码，现在是字节字符串。默认情况下，此方法将参数解码为 utf-8 并返回一个 Unicode 字符串，但可以在子类中覆盖此行为。

此方法用作 get_argument() 的过滤器，以及从 url 中提取并传递到 get()/post()/等等的值得过滤器。

如果已知参数的名称，则会提供该名称，但它也可能是 None（例如，对于 url 正则表达式中的未命名组）。

RequestHandler.request¶: 包含附加请求参数的 tornado.httputil.HTTPServerRequest 对象，包括例如标头和正文数据。

RequestHandler.path_args¶

RequestHandler.path_kwargs¶: path_args 和 path_kwargs 属性包含传递给 HTTP 动词方法的位置参数和关键字参数。这些属性在调用这些方法之前设置，因此这些值在 prepare 期间可用。

RequestHandler.data_received(chunk: bytes) → Optional[Awaitable[None]][source]¶

实现此方法以处理流式请求数据。

需要 stream_request_body 装饰器。

可以是用于流量控制的协程。

输出¶

RequestHandler.set_status(status_code: int, reason: Optional[str] = None) → None[source]¶

设置响应的代码。

参数

status_code (int) – 响应代码。
reason (str) – 描述代码的人类可读原因短语。如果为 None，它将从 http.client.responses 或 “Unknown” 中填充。

在版本 5.0 中更改: 不再验证响应代码是否在 http.client.responses 中。

RequestHandler.set_header(name: str, value: Union[bytes, str, int, Integral, datetime]) → None[source]¶

设置给定的响应头名称和值。

所有头值都会被转换为字符串（datetime 对象将根据 HTTP 规范格式化为 Date 头）。

RequestHandler.add_header(name: str, value: Union[bytes, str, int, Integral, datetime]) → None[source]¶

添加给定的响应头和值。

与 set_header 不同，add_header 可以被多次调用以返回同一个头的多个值。

RequestHandler.clear_header(name: str) → None[source]¶

清除一个输出头，撤销之前的 set_header 调用。

注意，此方法不适用于由 add_header 设置的多值头。

RequestHandler.set_default_headers() → None[source]¶

覆盖此方法以在请求开始时设置 HTTP 头。

例如，这是设置自定义 Server 头的地方。请注意，在请求处理的正常流程中设置此类头可能无法达到预期效果，因为在错误处理期间头可能会被重置。

RequestHandler.write(chunk: Union[str, bytes, dict]) → None[source]¶

将给定的块写入输出缓冲区。

要将输出写入网络，请使用下面的 flush() 方法。

如果给定的块是字典，我们将它写成 JSON 并将响应的 Content-Type 设置为 application/json。（如果您想以不同的 Content-Type 发送 JSON，请在调用 write() 之后调用 set_header）。

注意，列表不会被转换为 JSON，因为存在潜在的跨站点安全漏洞。所有 JSON 输出都应该封装在字典中。更多详细信息请参见 http://haacked.com/archive/2009/06/25/json-hijacking.aspx/ 和 https://github.com/facebook/tornado/issues/1009

RequestHandler.flush(include_footers: bool = False) → Future[None][source]¶: 将当前输出缓冲区刷新到网络。

Changed in version 4.0: 现在如果未提供回调，则返回一个 Future。

Changed in version 6.0: 已删除 callback 参数。

RequestHandler.finish(chunk: Optional[Union[str, bytes, dict]] = None) → Future[None][source]¶

完成此响应，结束 HTTP 请求。

将 chunk 传递给 finish() 等同于将该块传递给 write()，然后在不带参数的情况下调用 finish()。

返回一个 Future，可以选择等待它来跟踪响应发送到客户端的过程。这个 Future 在所有响应数据发送完毕时解析，如果在所有数据发送完毕之前连接关闭，则会抛出错误。

在 5.1 版本中变更: 现在返回一个 Future 而不是 None。

RequestHandler.render(template_name: str, **kwargs: Any) → Future[None][source]¶

使用给定的参数渲染模板作为响应。

render() 调用 finish()，因此在调用它之后不能再调用其他输出方法。

返回一个 Future，语义与 finish 返回的相同。等待这个 Future 是可选的。

在 5.1 版本中变更: 现在返回一个 Future 而不是 None。

RequestHandler.render_string(template_name: str, **kwargs: Any) → bytes[source]¶

使用给定的参数生成指定的模板。

我们返回生成的字节字符串（以 utf8 格式）。要生成并写入模板作为响应，请使用上面的 render()。

RequestHandler.get_template_namespace() → Dict[str, Any][source]¶

返回一个字典，用作默认模板命名空间。

子类可以重写它来添加或修改值。

此方法的结果将与 tornado.template 模块中的其他默认值以及 render 或 render_string 的关键字参数组合。

RequestHandler.redirect(url: str, permanent: bool = False, status: Optional[int] = None) → None[source]¶

将浏览器重定向到给定的（可选的相对）URL。

如果指定了 status 参数，则该值将用作 HTTP 状态码；否则，将根据 permanent 参数选择 301（永久）或 302（临时）。默认值为 302（临时）。

RequestHandler.send_error(status_code: int = 500, **kwargs: Any) → None[source]¶

将指定的 HTTP 错误代码发送到浏览器。

如果 flush() 已经被调用，则无法发送错误，因此此方法将简单地终止响应。如果输出已经被写入但尚未刷新，它将被丢弃并替换为错误页面。

重写 write_error() 以自定义返回的错误页面。其他关键字参数将传递给 write_error。

RequestHandler.write_error(status_code: int, **kwargs: Any) → None[source]¶

重写以实现自定义错误页面。

write_error 可以调用 write、render、set_header 等以生成输出，如往常一样。

如果此错误是由未捕获的异常（包括 HTTPError）引起的，则一个 exc_info 三元组将作为 kwargs["exc_info"] 可用。注意，此异常可能不是方法（如 sys.exc_info() 或 traceback.format_exc）的“当前”异常。

RequestHandler.clear() → None[source]¶: 重置此响应的所有标头和内容。

RequestHandler.render_linked_js(js_files: Iterable[str]) → str[source]¶

用于渲染最终网页 js 链接的默认方法。

在子类控制器中覆盖此方法以更改输出。

RequestHandler.render_embed_js(js_embed: Iterable[bytes]) → bytes[source]¶

用于渲染最终网页嵌入 js 的默认方法。

在子类控制器中覆盖此方法以更改输出。

RequestHandler.render_linked_css(css_files: Iterable[str]) → str[source]¶

用于渲染最终网页 css 链接的默认方法。

在子类控制器中覆盖此方法以更改输出。

RequestHandler.render_embed_css(css_embed: Iterable[bytes]) → bytes[source]¶

用于渲染最终网页嵌入 css 的默认方法。

在子类控制器中覆盖此方法以更改输出。

Cookies¶

RequestHandler.cookies¶: 是 self.request.cookies 的别名。

RequestHandler.get_cookie(name: str, default: Optional[str] = None) → Optional[str][source]¶

返回请求 cookie 中给定名称的值。

如果名为 cookie 不存在，则返回 default。

此方法仅返回请求中存在的 cookie。它不会看到此处理程序中由 set_cookie 设置的传出 cookie。

RequestHandler.set_cookie(name: str, value: Union[str, bytes], domain: Optional[str] = None, expires: Optional[Union[float, Tuple, datetime]] = None, path: str = '/', expires_days: Optional[float] = None, *, max_age: Optional[int] = None, httponly: bool = False, secure: bool = False, samesite: Optional[str] = None, **kwargs: Any) → None[source]¶

使用给定选项设置传出 cookie 名称/值。

新设置的 Cookie 不会立即通过 get_cookie 可见；它们只有在下一个请求中才会出现。

大多数参数直接传递给 http.cookies.Morsel。有关更多信息，请参见 https://mdn.org.cn/en-US/docs/Web/HTTP/Headers/Set-Cookie。

expires 可以是 time.time 返回的数字时间戳，time.gmtime 返回的时间元组，或 datetime.datetime 对象。 expires_days 作为设置从今天开始的天数的到期时间的便捷方法提供（如果两者都设置，则使用 expires）。

从版本 6.3 开始弃用：关键字参数目前接受不区分大小写。在 Tornado 7.0 中，这将更改为仅接受小写参数。

RequestHandler.clear_cookie(name: str, **kwargs: Any) → None[source]¶

删除具有给定名称的 Cookie。

此方法接受与 set_cookie 相同的参数，除了 expires 和 max_age。清除 Cookie 需要与设置时相同的 domain 和 path 参数。在某些情况下，还需要 samesite 和 secure 参数匹配。其他参数将被忽略。

与 set_cookie 类似，此方法的效果只有在下一个请求中才会生效。

在版本 6.3 中更改：现在接受 set_cookie 接受的所有关键字参数。最近，samesite 和 secure 标志已成为清除 samesite="none" Cookie 的必需条件。

RequestHandler.clear_all_cookies(**kwargs: Any) → None[source]¶

尝试删除用户在此请求中发送的所有 Cookie。

有关关键字参数的更多信息，请参见 clear_cookie。由于 Cookie 协议的限制，无法在服务器端确定哪些值是 domain、path、samesite 或 secure 参数所必需的，因此此方法只有在您在设置 Cookie 时始终使用相同的参数值时才能成功。

与 set_cookie 类似，此方法的效果只有在下一个请求中才会生效。

在版本 3.2 中更改：添加了 path 和 domain 参数。

在版本 6.3 中更改：现在接受 set_cookie 接受的所有关键字参数。

从版本 6.3 开始弃用：由于越来越复杂的 Cookie 规则，一个 clear_all_cookies 方法无法可靠地工作，因为我们只知道 Cookie 的名称。应用程序通常应该使用 clear_cookie 一次清除一个 Cookie。

RequestHandler.get_signed_cookie(name: str, value: Optional[str] = None, max_age_days: float = 31, min_version: Optional[int] = None) → Optional[bytes][source]¶

如果给定的已签名 Cookie 验证通过，则返回该 Cookie，否则返回 None。

解码后的 Cookie 值作为字节字符串返回（与 get_cookie 不同）。

与 get_cookie 类似，此方法只返回请求中存在的 Cookie。它不会看到此处理程序中 set_signed_cookie 设置的传出 Cookie。

在版本 3.2.1 中更改

添加了 min_version 参数。引入了 Cookie 版本 2；默认情况下接受版本 1 和版本 2。

在版本 6.3 中更改：从 get_secure_cookie 重命名为 get_signed_cookie 以避免与 Cookie 属性和前缀中“secure”的其他用法混淆。旧名称仍然作为别名存在。

RequestHandler.get_signed_cookie_key_version(name: str, value: Optional[str] = None) → Optional[int][source]¶

返回安全 Cookie 的签名密钥版本。

版本作为整数返回。

在版本 6.3 中更改：从 get_secure_cookie_key_version 重命名为 set_signed_cookie_key_version 以避免与 Cookie 属性和前缀中“secure”的其他用法混淆。旧名称仍然作为别名存在。

RequestHandler.set_signed_cookie(name: str, value: Union[str, bytes], expires_days: Optional[float] = 30, version: Optional[int] = None, **kwargs: Any) → None[source]¶

对 cookie 进行签名和时间戳，防止伪造。

您必须在应用程序中指定 cookie_secret 设置才能使用此方法。它应该是用于签名 HMAC 密钥的长随机字节序列。

要读取使用此方法设置的 cookie，请使用 get_signed_cookie().

请注意，expires_days 参数设置 cookie 在浏览器中的生存期，但与 get_signed_cookie 的 max_age_days 参数无关。值为 None 将生存期限制为当前浏览器会话。

安全 cookie 可以包含任意字节值，而不仅仅是 Unicode 字符串（与普通 cookie 不同）。

与 set_cookie 类似，此方法的效果只有在下一个请求中才会生效。

版本 3.2.1 中的更改：添加了 version 参数。引入了 cookie 版本 2 并将其设为默认版本。

版本 6.3 中的更改：从 set_secure_cookie 重命名为 set_signed_cookie 以避免与 cookie 属性和前缀中“secure”的其他用法混淆。旧名称仍然作为别名存在。

RequestHandler.get_secure_cookie()¶: get_signed_cookie 的已弃用别名。

自版本 6.3 起已弃用。

RequestHandler.get_secure_cookie_key_version()¶: get_signed_cookie_key_version 的已弃用别名。

自版本 6.3 起已弃用。

RequestHandler.set_secure_cookie()¶: set_signed_cookie 的已弃用别名。

自版本 6.3 起已弃用。

RequestHandler.create_signed_value(name: str, value: Union[str, bytes], version: Optional[int] = None) → bytes[source]¶

对字符串进行签名和时间戳，防止伪造。

通常通过 set_signed_cookie 使用，但作为一种独立方法提供用于非 cookie 用途。要解码未存储为 cookie 的值，请使用 get_signed_cookie 的可选值参数。

版本 3.2.1 中的更改：添加了 version 参数。引入了 cookie 版本 2 并将其设为默认版本。

tornado.web.MIN_SUPPORTED_SIGNED_VALUE_VERSION = 1¶

此版本的 Tornado 支持的最旧签名值版本。

比此版本更旧的签名值无法解码。

版本 3.2.1 中的新增功能。

tornado.web.MAX_SUPPORTED_SIGNED_VALUE_VERSION = 2¶

此版本的 Tornado 支持的最新签名值版本。

比此版本更新的签名值无法解码。

版本 3.2.1 中的新增功能。

tornado.web.DEFAULT_SIGNED_VALUE_VERSION = 2¶

RequestHandler.create_signed_value 生成的签名值版本。

可以通过传递 version 关键字参数来覆盖。

版本 3.2.1 中的新增功能。

tornado.web.DEFAULT_SIGNED_VALUE_MIN_VERSION = 1¶

RequestHandler.get_signed_cookie 接受的最旧签名值。

可以通过传递 min_version 关键字参数来覆盖。

版本 3.2.1 中的新增功能。

其他¶

RequestHandler.application¶: 为该请求提供服务的 Application 对象。

RequestHandler.check_etag_header() → bool[source]¶

检查 Etag 标头是否与请求的 If-None-Match 匹配。

如果请求的 Etag 匹配，则应返回 304，则返回 True。例如

self.set_etag_header()
if self.check_etag_header():
    self.set_status(304)
    return

此方法在请求完成时会自动调用，但在应用程序需要覆盖 compute_etag 并希望在完成请求之前对 If-None-Match 进行早期检查时，可以更早地调用它。在调用此方法之前，应设置 Etag 标头（可能使用 set_etag_header）。

RequestHandler.check_xsrf_cookie() → None[source]¶

验证 _xsrf cookie 是否与 _xsrf 参数匹配。

为了防止跨站点请求伪造，我们设置一个 _xsrf cookie，并将相同的值作为非 cookie 字段包含在所有 POST 请求中。如果两者不匹配，我们会将表单提交拒绝为可能的伪造行为。

的值可以设置成名为的表单字段，也可以设置成名为或的自定义 HTTP 标头（后者为了兼容 Django 而被接受）。

参见 http://en.wikipedia.org/wiki/Cross-site_request_forgery

在版本 3.2.2 中变更: 添加了对 cookie 版本 2 的支持。版本 1 和 2 都受支持。

RequestHandler.compute_etag() → Optional[str][source]¶

计算用于此请求的 etag 标头。

默认情况下使用到目前为止写入的内容的哈希值。

可以覆盖以提供自定义 etag 实现，也可以返回 None 以禁用 tornado 的默认 etag 支持。

RequestHandler.create_template_loader(template_path: str) → BaseLoader[source]¶

为给定路径返回一个新的模板加载器。

可以被子类覆盖。默认情况下，在给定路径上返回基于目录的加载器，使用 autoescape 和 template_whitespace 应用程序设置。如果提供了 template_loader 应用程序设置，则使用它。

RequestHandler.current_user¶

此请求的已认证用户。

这可以通过两种方式之一设置

子类可以覆盖 get_current_user()，它将在第一次访问 self.current_user 时自动调用。 get_current_user() 每个请求只会被调用一次，并且会缓存以供将来访问
```
def get_current_user(self):
    user_cookie = self.get_signed_cookie("user")
    if user_cookie:
        return json.loads(user_cookie)
    return None
```

它可以像普通变量一样设置，通常来自覆盖的 prepare()

@gen.coroutine
def prepare(self):
    user_id_cookie = self.get_signed_cookie("user_id")
    if user_id_cookie:
        self.current_user = yield load_user(user_id_cookie)

请注意， prepare() 可以是一个协程，而 get_current_user() 可能不是，所以如果加载用户需要异步操作，则需要使用后一种形式。

用户对象可以是应用程序选择的任何类型。

RequestHandler.detach() → IOStream[source]¶

控制底层流。

返回底层 IOStream 对象并停止所有进一步的 HTTP 处理。用于实现像 websockets 这样的协议，这些协议通过 HTTP 握手进行隧道传输。

此方法仅在使用 HTTP/1.1 时受支持。

版本 5.1 中新增。

RequestHandler.get_browser_locale(default: str = 'en_US') → Locale[source]¶

从 Accept-Language 标头中确定用户的区域设置。

参见 http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.4

RequestHandler.get_current_user() → Any[source]¶

覆盖以从例如 cookie 中确定当前用户。

此方法可能不是协程。

RequestHandler.get_login_url() → str[source]¶

覆盖以根据请求定制登录 URL。

默认情况下，我们使用 login_url 应用程序设置。

RequestHandler.get_status() → int[source]¶: 返回我们响应的状态码。

RequestHandler.get_template_path() → Optional[str][source]¶

覆盖以自定义每个处理程序的模板路径。

默认情况下，我们使用 template_path 应用程序设置。返回 None 以加载相对于调用文件的模板。

RequestHandler.get_user_locale() → Optional[Locale][source]¶

覆盖以从已认证用户处确定区域设置。

如果返回 None，我们将回退到 get_browser_locale()。

此方法应该返回一个 tornado.locale.Locale 对象，最有可能通过类似 tornado.locale.get("en") 的调用获得

RequestHandler.locale¶

当前会话的区域设置。

由 get_user_locale 确定，您可以覆盖它以根据例如存储在数据库中的用户首选项设置区域设置，或 get_browser_locale，它使用 Accept-Language 标头。

RequestHandler.log_exception(typ: Optional[Type[BaseException]], value: Optional[BaseException], tb: Optional[TracebackType]) → None[source]¶

重写以自定义未捕获异常的日志记录。

默认情况下，将 HTTPError 的实例作为警告记录（在 tornado.general 日志记录器上），并且将所有其他异常作为错误记录（在 tornado.application 日志记录器上），并附带堆栈跟踪信息。

3.1 版新增。

RequestHandler.on_connection_close() → None[source]¶

如果客户端关闭连接，则在异步处理程序中调用此方法。

重写此方法以清理与长期连接相关的资源。请注意，仅当连接在异步处理过程中关闭时才会调用此方法；如果您需要在每个请求后进行清理，请改写 on_finish。

代理可能在客户端断开连接后将连接保持打开状态（可能无限期），因此此方法可能不会在最终用户关闭其连接后立即被调用。

RequestHandler.require_setting(name: str, feature: str = 'this feature') → None[source]¶: 如果给定的应用程序设置未定义，则引发异常。

RequestHandler.reverse_url(name: str, *args: Any) → str[source]¶: Application.reverse_url 的别名。

RequestHandler.set_etag_header() → None[source]¶

使用 self.compute_etag() 设置响应的 Etag 标头。

注意：如果 compute_etag() 返回 None，则不会设置任何标头。

此方法在请求完成时会自动调用。

RequestHandler.settings¶: self.application.settings 的别名。

RequestHandler.static_url(path: str, include_host: Optional[bool] = None, **kwargs: Any) → str[source]¶

返回给定相对静态文件路径的静态 URL。

此方法要求您在应用程序中设置 static_path 设置（它指定静态文件的根目录）。

此方法返回一个版本化的 URL（默认情况下附加 ?v=<signature>），这允许静态文件被无限期缓存。可以通过传递 include_version=False 来禁用此功能（在默认实现中；其他静态文件实现不需要支持此功能，但它们可能支持其他选项）。

默认情况下，此方法返回相对于当前主机的 URL，但是如果 include_host 为真，则返回的 URL 将是绝对的。如果此处理程序具有 include_host 属性，则该值将用作所有未将 include_host 作为关键字参数传递的 static_url 调用的默认值。

RequestHandler.xsrf_form_html() → str[source]¶

要与所有 POST 表单一起包含的 HTML <input/> 元素。

它定义了 _xsrf 输入值，我们在所有 POST 请求中检查此值以防止跨站点请求伪造。如果您已设置 xsrf_cookies 应用程序设置，则必须将此 HTML 包含在您的所有 HTML 表单中。

在模板中，此方法应使用 {% module xsrf_form_html() %} 调用。

有关详细信息，请参见上面的 check_xsrf_cookie()。

RequestHandler.xsrf_token¶

当前用户/会话的 XSRF 防护令牌。

为了防止跨站点请求伪造，我们设置了一个 ‘_xsrf’ cookie，并在所有 POST 请求中包含相同的 ‘_xsrf’ 值作为参数。如果两者不匹配，我们将拒绝表单提交，因为它可能是潜在的伪造。

参见 http://en.wikipedia.org/wiki/Cross-site_request_forgery

此属性的类型为 bytes，但它只包含 ASCII 字符。如果需要字符字符串，则无需对其进行 Base64 编码；只需将字节字符串解码为 UTF-8 即可。

在版本 3.2.2 中更改: xsrf 令牌现在将在每个请求中应用随机掩码，这使得将令牌包含在压缩的页面中变得安全。有关此更改修复的问题的更多信息，请参见 http://breachattack.com。除非 xsrf_cookie_version Application 设置设置为 1，否则旧版（版本 1）cookie 将在调用此方法时转换为版本 2。

在版本 4.3 中更改: xsrf_cookie_kwargs Application 设置可用于提供其他 cookie 选项（这些选项将直接传递给 set_cookie）。例如，xsrf_cookie_kwargs=dict(httponly=True, secure=True) 将在 _xsrf cookie 上设置 secure 和 httponly 标志。

应用程序配置¶

class tornado.web.Application(handlers: Optional[List[Union[Rule, Tuple]]] = None, default_host: Optional[str] = None, transforms: Optional[List[Type[OutputTransform]]] = None, **settings)[source]¶

一个包含构成 Web 应用程序的请求处理程序的集合。

此类的实例是可调用的，可以直接传递给 HTTPServer 以服务应用程序

application = web.Application([
    (r"/", MainPageHandler),
])
http_server = httpserver.HTTPServer(application)
http_server.listen(8080)

此类的构造函数接收 Rule 对象列表或对应于 Rule 构造函数参数的值元组：(matcher, target, [target_kwargs], [name])，方括号中的值是可选的。默认匹配器为 PathMatches，因此 (regexp, target) 元组也可以用作 (PathMatches(regexp), target) 的替代方案。

一个常见的路由目标是 RequestHandler 子类，但您也可以使用规则列表作为目标，这将创建一个嵌套的路由配置

application = web.Application([
    (HostMatches("example.com"), [
        (r"/", MainPageHandler),
        (r"/feed", FeedHandler),
    ]),
])

除此之外，您还可以使用嵌套的 Router 实例、HTTPMessageDelegate 子类和可调用对象作为路由目标（有关更多信息，请参见 routing 模块文档）。

当我们接收到请求时，我们将按顺序遍历该列表，并实例化第一个正则表达式与请求路径匹配的请求类的实例。请求类可以指定为类对象或（完全限定的）名称。

元组的第三个元素（target_kwargs）可以传递字典，它将用作处理程序构造函数和 initialize 方法的关键字参数。此模式用于此示例中的 StaticFileHandler（请注意，可以使用下面描述的 static_path 设置自动安装 StaticFileHandler）

application = web.Application([
    (r"/static/(.*)", web.StaticFileHandler, {"path": "/var/www"}),
])

我们使用 add_handlers 方法支持虚拟主机，该方法将主机正则表达式作为第一个参数。

application.add_handlers(r"www\.myhost\.com", [
    (r"/article/([0-9]+)", ArticleHandler),
])

如果当前请求的主机没有匹配项，则将 default_host 参数值与主机正则表达式匹配。

警告

不使用 TLS 的应用程序可能容易受到 DNS 重绑定攻击。这种攻击与仅在 127.0.0.1 或其他私有网络上侦听的应用程序特别相关。必须使用适当的主机模式（而不是默认的 r'.*'）来防止此风险。在可能容易受到 DNS 重绑定攻击的应用程序中，不得使用 default_host 参数。

您可以通过将 static_path 设置作为关键字参数发送来服务静态文件。我们将从 /static/ URI（这可以通过 static_url_prefix 设置配置）服务这些文件，并将从同一目录服务 /favicon.ico 和 /robots.txt。可以使用 static_handler_class 设置指定 StaticFileHandler 的自定义子类。

在版本 4.5 中更改: 与新的 tornado.routing 模块集成。

settings¶

传递给构造函数的其他关键字参数将保存在 settings 字典中，并且在文档中通常被称为“应用程序设置”。设置用于自定义 Tornado 的各个方面（尽管在某些情况下，可以通过覆盖 RequestHandler 子类的某些方法来实现更丰富的自定义）。某些应用程序还喜欢使用 settings 字典作为一种方法，使应用程序特定的设置可供处理程序使用，而无需使用全局变量。Tornado 中使用的设置在下面描述。

一般设置

autoreload: 如果为 True，则服务器进程将在任何源文件更改时重新启动，如调试模式和自动重新加载中所述。此选项是 Tornado 3.2 中的新增功能；以前，此功能由 debug 设置控制。
debug: 几个调试模式设置的简写，如调试模式和自动重新加载中所述。将 debug 设置为 True 等效于 autoreload=True、compiled_template_cache=False、static_hash_cache=False、serve_traceback=True。
default_handler_class 和 default_handler_args: 如果没有找到其他匹配项，将使用此处理程序；使用此处理程序来实现自定义 404 页面（Tornado 3.2 中的新增功能）。
compress_response: 如果设置为 True，文本格式的响应将自动压缩。此功能在 Tornado 4.0 中新增。
gzip: 自 Tornado 4.0 起，compress_response 的弃用别名。
log_function: 此函数将在每个请求结束时被调用，以记录结果（使用一个参数，即 RequestHandler 对象）。默认实现写入 logging 模块的根记录器。也可以通过重写 Application.log_request 来自定义。
serve_traceback: 如果设置为 True，默认错误页面将包含错误的回溯信息。此选项在 Tornado 3.2 中新增；在此之前，此功能由 debug 设置控制。
ui_modules 和 ui_methods: 可以设置为 UIModule 或 UI 方法的映射，以便在模板中使用。可以设置为模块、字典或模块和/或字典的列表。有关更多详细信息，请参阅 UI 模块。
websocket_ping_interval: 如果设置为数字，所有 websocket 将每隔 n 秒 ping 一次。这有助于通过某些关闭空闲连接的代理服务器保持连接存活，并可以检测 websocket 是否在未正常关闭的情况下发生故障。
websocket_ping_timeout: 如果设置了 ping 间隔，并且服务器在这么多秒内没有收到“pong”，它将关闭 websocket。默认值是 ping 间隔的三倍，最小值为 30 秒。如果未设置 ping 间隔，则忽略此设置。

身份验证和安全设置

cookie_secret: 由 RequestHandler.get_signed_cookie 和 set_signed_cookie 用于签署 cookie。
key_version: 当 cookie_secret 是一个密钥字典时，由 requestHandler set_signed_cookie 用于使用特定密钥签署 cookie。
login_url: 如果用户未登录，authenticated 装饰器将重定向到此 URL。可以通过重写 RequestHandler.get_login_url 进行进一步自定义。
xsrf_cookies: 如果设置为 True，将启用跨站请求伪造保护。
xsrf_cookie_version: 控制此服务器生成的新的 XSRF cookie 的版本。通常应该保持默认值（始终为最高支持版本），但在版本转换期间可以暂时设置为较低的值。在 Tornado 3.2.2 中新增，引入了 XSRF cookie 版本 2。
xsrf_cookie_kwargs: 可以设置为一个字典，其中包含要传递给 RequestHandler.set_cookie 的附加参数，用于 XSRF cookie。
xsrf_cookie_name: 控制用于 XSRF cookie 的名称（默认值为 _xsrf）。其目的是利用 cookie 前缀。请注意，cookie 前缀会与其他 cookie 标志交互，因此必须与 xsrf_cookie_kwargs 结合使用，例如 {"xsrf_cookie_name": "__Host-xsrf", "xsrf_cookie_kwargs": {"secure": True}}
twitter_consumer_key、twitter_consumer_secret、friendfeed_consumer_key、friendfeed_consumer_secret、google_consumer_key、google_consumer_secret、facebook_api_key、facebook_secret: 用于 tornado.auth 模块，以验证各种 API。

模板设置

autoescape: 控制模板的自动转义。可以设置为 None 以禁用转义，或者设置为所有输出应通过的函数的 *名称*。默认为 "xhtml_escape"。可以在每个模板的基础上使用 {% autoescape %} 指令进行更改。
compiled_template_cache: 默认值为 True；如果为 False，则模板将在每次请求时重新编译。此选项在 Tornado 3.2 中新增；在此之前，此功能由 debug 设置控制。
template_path: 包含模板文件的目录。可以通过重写 RequestHandler.get_template_path 进行进一步自定义。
template_loader: 分配给 tornado.template.BaseLoader 的实例以自定义模板加载。如果使用此设置，则忽略 template_path 和 autoescape 设置。可以通过重写 RequestHandler.create_template_loader 进行进一步自定义。
template_whitespace: 控制模板中空白的处理方式；有关允许的值，请参阅 tornado.template.filter_whitespace。在 Tornado 4.3 中新增。

静态文件设置

static_hash_cache: 默认值为 True；如果为 False，则静态 URL 将在每次请求时重新计算。此选项在 Tornado 3.2 中新增；在此之前，此功能由 debug 设置控制。
static_path: 用于提供静态文件的目录。
static_url_prefix: 静态文件的 URL 前缀，默认为 "/static/"。
static_handler_class、static_handler_args: 可以设置为使用不同的处理程序来处理静态文件，而不是默认的 tornado.web.StaticFileHandler。如果设置了 static_handler_args，则它应该是一个字典，其中包含要传递给处理程序的 initialize 方法的关键字参数。

Application.listen(port: int, address: Optional[str] = None, *, family: AddressFamily = AddressFamily.AF_UNSPEC, backlog: int = 128, flags: Optional[int] = None, reuse_port: bool = False, **kwargs: Any) → HTTPServer[source]¶

为该应用程序在给定端口上启动一个 HTTP 服务器。

这是创建 HTTPServer 对象并调用其 listen 方法的便捷别名。HTTPServer.listen 不支持的关键字参数将传递给 HTTPServer 构造函数。对于高级用法（例如多进程模式），不要使用此方法；创建 HTTPServer 并直接调用其 TCPServer.bind/TCPServer.start 方法。

请注意，在调用此方法后，您仍然需要调用 IOLoop.current().start()（或在 asyncio.run 中运行）来启动服务器。

返回 HTTPServer 对象。

版本 4.3 中的更改：现在返回 HTTPServer 对象。

版本 6.2 中的更改：添加了对 TCPServer.listen 中的新关键字参数的支持，包括 reuse_port。

Application.add_handlers(handlers: List[Union[Rule, Tuple]])[source]¶

将给定的处理程序追加到我们的处理程序列表。

主机模式按添加顺序依次处理。所有匹配的模式都将被考虑。

Application.get_handler_delegate(request: HTTPServerRequest, target_class: Type[RequestHandler], target_kwargs: Optional[Dict[str, Any]] = None, path_args: Optional[List[bytes]] = None, path_kwargs: Optional[Dict[str, bytes]] = None) → _HandlerDelegate[source]¶

返回可以为应用程序和 RequestHandler 子类服务请求的 HTTPMessageDelegate。

参数

request (httputil.HTTPServerRequest) – 当前 HTTP 请求。
target_class (RequestHandler) – RequestHandler 类。
target_kwargs (dict) – target_class 构造函数的关键字参数。
path_args (list) – target_class HTTP 方法的位置参数，将在处理请求时执行 (get, post 或其他)。
path_kwargs (dict) – target_class HTTP 方法的关键字参数。

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

返回名为 name 的处理程序的 URL 路径

该处理程序必须作为命名 URLSpec 添加到应用程序。

参数将被替换为在 URLSpec 正则表达式中的捕获组。如果需要，它们将被转换为字符串，以 utf8 编码，并进行 url 转义。

Application.log_request(handler: RequestHandler) → None[source]¶

将完成的 HTTP 请求写入日志。

默认情况下写入 python 根日志记录器。要更改此行为，请子类化 Application 并覆盖此方法，或在应用程序设置字典中将函数作为 log_function 传递。

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

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

参数

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

URLSpec 类也可以在名称 tornado.web.url 下使用。

装饰器¶

tornado.web.authenticated(method: Callable[[...], Optional[Awaitable[None]]]) → Callable[[...], Optional[Awaitable[None]]][source]¶

用此装饰方法以要求用户登录。

如果用户未登录，他们将被重定向到配置的 login url。

如果使用查询参数配置登录 URL，Tornado 将假定您知道自己在做什么，并按原样使用它。如果没有，它将添加一个 next 参数，以便登录页面知道在您登录后将您发送到哪里。

tornado.web.addslash(method: Callable[[...], Optional[Awaitable[None]]]) → Callable[[...], Optional[Awaitable[None]]][source]¶

使用此装饰器将缺少的尾部斜杠添加到请求路径。

例如，对 /foo 的请求将使用此装饰器重定向到 /foo/。您的请求处理程序映射应使用类似于 r'/foo/?' 的正则表达式，并结合使用装饰器。

tornado.web.removeslash(method: Callable[[...], Optional[Awaitable[None]]]) → Callable[[...], Optional[Awaitable[None]]][source]¶

使用此装饰器从请求路径中删除尾部斜杠。

例如，对 /foo/ 的请求将使用此装饰器重定向到 /foo。您的请求处理程序映射应使用类似于 r'/foo/*' 的正则表达式，并结合使用装饰器。

tornado.web.stream_request_body(cls: Type[_RequestHandlerType]) → Type[_RequestHandlerType][source]¶

将此装饰器应用于 RequestHandler 子类以启用流式正文支持。

此装饰器意味着以下更改

HTTPServerRequest.body 未定义，并且正文参数不会包含在 RequestHandler.get_argument 中。
RequestHandler.prepare 在读取请求头后调用，而不是在读取整个正文后调用。
子类必须定义一个方法 data_received(self, data):，该方法将在数据可用时调用零次或多次。请注意，如果请求具有空正文，则可能不会调用 data_received。
prepare 和 data_received 可能会返回 Futures（例如通过 @gen.coroutine，在这种情况下，下一个方法将不会被调用，直到这些 futures 完成。
常规 HTTP 方法（post、put 等）将在读取整个正文后调用。

有关示例用法，请参见文件接收器演示。

其他所有内容¶

exception tornado.web.HTTPError(status_code: int = 500, log_message: Optional[str] = None, *args: Any, **kwargs: Any)[source]¶

将变成 HTTP 错误响应的异常。

引发 HTTPError 是调用 RequestHandler.send_error 的一种便捷替代方案，因为它会自动结束当前函数。

要自定义使用 HTTPError 发送的响应，请覆盖 RequestHandler.write_error。

参数

status_code (int) – HTTP 状态代码。必须列在 httplib.responses 中，除非给出 reason 关键字参数。
log_message (str) – 要写入此错误日志的消息（除非 Application 处于调试模式，否则不会显示给用户）。可能包含 %s 样式的占位符，这些占位符将使用剩余的位置参数填充。
reason (str) – 仅限关键字参数。要与 status_code 一起在状态行中传递的 HTTP “原因” 短语。通常从 status_code 自动确定，但可以用于使用非标准数字代码。

exception tornado.web.Finish[source]¶

结束请求而不生成错误响应的异常。

当 Finish 在 RequestHandler 中引发时，请求将结束（如果尚未调用，则调用 RequestHandler.finish），但不会调用错误处理方法（包括 RequestHandler.write_error）。

如果 Finish() 没有参数创建，则将按原样发送挂起的响应。如果 Finish() 给出了一个参数，该参数将传递给 RequestHandler.finish()。

这可能是实现自定义错误页面的更便捷的方式，而不是覆盖 write_error（尤其是在库代码中）。

if self.current_user is None:
    self.set_status(401)
    self.set_header('WWW-Authenticate', 'Basic realm="something"')
    raise Finish()

在版本 4.3 中更改：传递给 Finish() 的参数将传递给 RequestHandler.finish。

exception tornado.web.MissingArgumentError(arg_name: str)[source]¶

由 RequestHandler.get_argument 引发的异常。

这是 HTTPError 的子类，因此如果未捕获，将使用 400 响应代码而不是 500（并且不会记录堆栈跟踪）。

3.1 版新增。

class tornado.web.UIModule(handler: RequestHandler)[source]¶

页面上的可重用、模块化 UI 单元。

UI 模块通常执行额外的查询，它们可以包含将在输出页面中包含的额外 CSS 和 JavaScript，这些内容会在页面渲染时自动插入。

UIModule 的子类必须覆盖 render 方法。

render(*args: Any, **kwargs: Any) → str[source]¶: 在子类中覆盖以返回此模块的输出。

embedded_javascript() → Optional[str][source]¶: 覆盖以返回要嵌入页面的 JavaScript 字符串。

javascript_files() → Optional[Iterable[str]][source]¶

覆盖此方法以返回此模块所需的 JavaScript 文件列表。

如果返回值为相对路径，则它们将传递给 RequestHandler.static_url；否则它们将按原样使用。

embedded_css() → Optional[str][source]¶: 覆盖此方法以返回将嵌入到页面中的 CSS 字符串。

css_files() → Optional[Iterable[str]][source]¶

覆盖此方法以返回此模块所需的 CSS 文件列表。

如果返回值为相对路径，则它们将传递给 RequestHandler.static_url；否则它们将按原样使用。

html_head() → Optional[str][source]¶: 覆盖此方法以返回一个 HTML 字符串，该字符串将放在 <head/> 元素中。

html_body() → Optional[str][source]¶: 覆盖此方法以返回一个 HTML 字符串，该字符串将放在 <body/> 元素的末尾。

render_string(path: str, **kwargs: Any) → bytes[source]¶: 渲染模板并将其作为字符串返回。

class tornado.web.ErrorHandler(application: Application, request: HTTPServerRequest, **kwargs: Any)[source]¶: 使用 status_code 为所有请求生成错误响应。

class tornado.web.FallbackHandler(application: Application, request: HTTPServerRequest, **kwargs: Any)[source]¶

一个 RequestHandler，它包装另一个 HTTP 服务器回调。

回退是一个可调用对象，它接受一个 HTTPServerRequest，例如一个 Application 或 tornado.wsgi.WSGIContainer。这最常用于在同一个服务器中同时使用 Tornado RequestHandlers 和 WSGI。典型用法

wsgi_app = tornado.wsgi.WSGIContainer(
    django.core.handlers.wsgi.WSGIHandler())
application = tornado.web.Application([
    (r"/foo", FooHandler),
    (r".*", FallbackHandler, dict(fallback=wsgi_app)),
])

class tornado.web.RedirectHandler(application: Application, request: HTTPServerRequest, **kwargs: Any)[source]¶

将客户端重定向到所有 GET 请求的给定 URL。

您应该为处理程序提供关键字参数 url，例如

application = web.Application([
    (r"/oldpath", web.RedirectHandler, {"url": "/newpath"}),
])

RedirectHandler 支持正则表达式替换。例如，要交换路径的第一部分和第二部分，同时保留其余部分

application = web.Application([
    (r"/(.*?)/(.*?)/(.*)", web.RedirectHandler, {"url": "/{1}/{0}/{2}"}),
])

最终 URL 使用 str.format 和匹配捕获组的子字符串进行格式化。在上面的示例中，对“/a/b/c”的请求将被格式化为

str.format("/{1}/{0}/{2}", "a", "b", "c")  # -> "/b/a/c"

使用 Python 的格式字符串语法自定义值的替换方式。

在版本 4.5 中更改：添加了对目标 URL 中替换的支持。

在版本 5.0 中更改：如果存在任何查询参数，它们将被复制到目标 URL。

class tornado.web.StaticFileHandler(application: Application, request: HTTPServerRequest, **kwargs: Any)[source]¶

一个简单的处理程序，可以从目录中提供静态内容。

如果您将 static_path 关键字参数传递给 Application，则会自动配置一个 StaticFileHandler。可以使用 static_url_prefix、static_handler_class 和 static_handler_args 设置来自定义此处理程序。

要将另一个路径映射到此处理程序以用于静态数据目录，您可以在您的应用程序中添加一行代码，例如

application = web.Application([
    (r"/content/(.*)", web.StaticFileHandler, {"path": "/var/www"}),
])

处理程序构造函数需要一个 path 参数，该参数指定要提供的内容的本地根目录。

请注意，正则表达式中的捕获组是解析 path 参数值的必要条件（不同于上面的构造函数参数），该参数传递给 get() 方法；有关详细信息，请参阅 URLSpec。

要自动在请求目录时提供像 index.html 这样的文件，请在应用程序设置中设置 static_handler_args=dict(default_filename="index.html")，或者将 default_filename 作为 StaticFileHandler 的初始化参数添加。

为了最大限度地提高浏览器缓存的效率，此类支持版本化的 URL（默认使用参数 ?v=）。如果给定了版本，我们将指示浏览器无限期地缓存此文件。 make_static_url（也可作为 RequestHandler.static_url 使用）可用于构建版本化的 URL。

此处理程序主要用于开发和轻负载文件服务；对于高流量场景，使用专用静态文件服务器（如 nginx 或 Apache）会更有效率。我们支持 HTTP Accept-Ranges 机制来返回部分内容（因为某些浏览器要求此功能才能在 HTML5 音频或视频中进行查找）。

子类化说明

此类设计为通过子类化进行扩展，但由于静态 URL 是使用类方法而不是实例方法生成的，因此继承模式有些不同寻常。请确保在覆盖类方法时使用 @classmethod 装饰器。实例方法可以使用属性 self.path self.absolute_path 和 self.modified。

子类应仅覆盖本节中讨论的方法；覆盖其他方法容易出错。覆盖 StaticFileHandler.get 尤其成问题，因为这与 compute_etag 和其他方法紧密耦合。

要更改静态 URL 的生成方式（例如，匹配其他服务器或 CDN 的行为），请覆盖 make_static_url、parse_url_path、get_cache_time 和/或 get_version。

要替换所有与文件系统的交互（例如，从数据库中提供静态内容），请覆盖 get_content、get_content_size、get_modified_time、get_absolute_path 和 validate_absolute_path。

Tornado 3.1 中已更改：子类的许多方法是在 Tornado 3.1 中添加的。

compute_etag() → Optional[str][source]¶

根据静态 URL 版本设置 Etag 标头。

这允许对缓存版本进行有效的 If-None-Match 检查，并为部分响应发送正确的 Etag（即与完整文件相同的 Etag）。

3.1 版新增。

set_headers() → None[source]¶: 在响应中设置内容和缓存标头。

3.1 版新增。

should_return_304() → bool[source]¶: 如果标头指示我们应该返回 304，则返回 True。

3.1 版新增。

classmethod get_absolute_path(root: str, path: str) → str[source]¶

返回相对于 root 的 path 的绝对位置。

root 是为此 StaticFileHandler 配置的路径（在大多数情况下是 static_path Application 设置）。

此类方法可以在子类中被覆盖。默认情况下，它返回一个文件系统路径，但只要字符串是唯一的并且被子类的覆盖 get_content 理解，其他字符串也可以使用。

3.1 版新增。

validate_absolute_path(root: str, absolute_path: str) → Optional[str][source]¶

验证并返回绝对路径。

root 是为 StaticFileHandler 配置的路径，path 是 get_absolute_path 的结果。

这是一个在请求处理期间调用的实例方法，因此它可能会引发 HTTPError 或使用诸如 RequestHandler.redirect 之类的方法（在重定向后返回 None 以停止进一步处理）。这就是为缺失文件生成 404 错误的地方。

此方法可能会在返回之前修改路径，但请注意，任何此类修改都不会被 make_static_url 理解。

在实例方法中，此方法的结果可用作 self.absolute_path。

3.1 版新增。

classmethod get_content(abspath: str, start: Optional[int] = None, end: Optional[int] = None) → Generator[bytes, None, None][source]¶

检索位于给定绝对路径的请求资源的内容。

此类方法可以被子类覆盖。注意，它的签名与其他可覆盖的类方法不同（没有 settings 参数）；这是故意的，以确保 abspath 能够作为缓存键独立存在。

此方法应该返回一个字节字符串或字节字符串的迭代器。对于大型文件，后者更可取，因为它有助于减少内存碎片。

3.1 版新增。

classmethod get_content_version(abspath: str) → str[source]¶

返回给定路径上的资源的版本字符串。

此类方法可以被子类覆盖。默认实现是文件内容的 SHA-512 哈希值。

3.1 版新增。

get_content_size() → int[source]¶

检索给定路径上资源的总大小。

此方法可以被子类覆盖。

3.1 版新增。

版本 4.0 中已更改: 此方法现在始终被调用，而不是仅在请求部分结果时调用。

get_modified_time() → Optional[datetime][source]¶

返回 self.absolute_path 最后修改的时间。

可以在子类中覆盖。应该返回一个 datetime 对象或 None。

3.1 版新增。

版本 6.4 中已更改: 现在返回一个感知时区的 datetime 对象，而不是一个非感知时区的对象。覆盖此方法的子类可以返回任一类型。

get_content_type() → str[source]¶: 返回要用于此请求的 Content-Type 标头。

3.1 版新增。

set_extra_headers(path: str) → None[source]¶: 供子类向响应添加额外的标头

get_cache_time(path: str, modified: Optional[datetime], mime_type: str) → int[source]¶

覆盖以自定义缓存控制行为。

返回一个正数秒数，使结果可缓存该时间段，或返回 0，将资源标记为可缓存一段时间（取决于浏览器启发式算法）。

默认情况下，对于使用 v 参数请求的资源，返回 10 年的缓存过期时间。

classmethod make_static_url(settings: Dict[str, Any], path: str, include_version: bool = True) → str[source]¶

为给定路径构建一个版本化的 URL。

此方法可以在子类中覆盖（但注意，它是一个类方法，而不是一个实例方法）。子类只需要实现签名 make_static_url(cls, settings, path)；其他关键字参数可以通过 static_url 传递，但不是标准的。

settings 是 Application.settings 字典。 path 是正在请求的静态路径。返回的 URL 应该相对于当前主机。

include_version 确定生成的 URL 是否应该包含包含与给定 path 对应的文件的版本哈希的查询字符串。

parse_url_path(url_path: str) → str[source]¶

将静态 URL 路径转换为文件系统路径。

url_path 是 URL 的路径组件，已移除 static_url_prefix。返回值应相对于 static_path 的文件系统路径。

这是 make_static_url 的逆运算。

classmethod get_version(settings: Dict[str, Any], path: str) → Optional[str][source]¶

生成用于静态 URL 的版本字符串。

settings 是 Application.settings 字典，path 是文件系统上所请求资产的相对位置。返回值应为字符串，如果无法确定版本，则为 None。

从版本 3.1 开始更改：先前建议子类重写此方法；现在首选 get_content_version，因为它允许基类处理结果的缓存。

tornado.web — RequestHandler 和 Application 类¶

线程安全注意事项¶

请求处理程序¶

入口点¶

输入¶

输出¶

Cookies¶

其他¶

应用程序配置¶

装饰器¶

其他所有内容¶

`tornado.web` — `RequestHandler` 和 `Application` 类¶