Tornado 文档：一份面向全球开发者的综合指南

Tornado 是一个 Python Web 框架和异步网络库，最初由 FriendFeed 开发。它特别适用于长轮询、WebSockets 以及其他需要为每个用户维持长连接的应用。其非阻塞网络 I/O 使其具有极高的可扩展性，是构建高性能 Web 应用的强大选择。这份综合指南将引导您了解 Tornado 的核心概念，并提供实用示例帮助您入门。

什么是 Tornado？

Tornado 的核心是一个 Web 框架和异步网络库。与传统的同步 Web 框架不同，Tornado 使用基于单线程事件循环的架构。这意味着它可以在不需要为每个连接分配一个线程的情况下处理大量并发连接，从而使其更高效、更具可扩展性。

Tornado 的主要特性：

异步网络： Tornado 的核心围绕异步 I/O 构建，使其能够高效地处理数千个并发连接。
Web 框架： 它包含请求处理器、路由、模板和身份验证等功能，使其成为一个完整的 Web 框架。
WebSocket 支持： Tornado 为 WebSockets 提供了出色的支持，实现了服务器和客户端之间的实时通信。
轻量且快速： Tornado 为性能而设计，轻量而高效，最大限度地减少开销并最大化吞吐量。
易于使用： 尽管功能先进，Tornado 相对易于学习和使用，拥有清晰且文档齐全的 API。

设置您的 Tornado 环境

在深入 Tornado 开发之前，您需要设置您的环境。以下是分步指南：

安装 Python： 确保您已安装 Python 3.6 或更高版本。您可以从 Python 官方网站 (python.org) 下载。

创建虚拟环境（推荐）： 使用 venv 或 virtualenv 为您的项目创建一个隔离的环境：

python3 -m venv myenv
source myenv/bin/activate  # 在 Linux/macOS 上
myenv\Scripts\activate  # 在 Windows 上

安装 Tornado： 使用 pip 安装 Tornado：
```
pip install tornado
```

您的第一个 Tornado 应用

让我们用 Tornado 创建一个简单的“Hello, World!”应用。创建一个名为 app.py 的文件并添加以下代码：

import tornado.ioloop
import tornado.web

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

def make_app():
 return tornado.web.Application([
  (r"/", MainHandler),
 ])

if __name__ == "__main__":
 app = make_app()
 app.listen(8888)
 tornado.ioloop.IOLoop.current().start()

现在，从您的终端运行该应用：

python app.py

打开您的 Web 浏览器并访问 http://localhost:8888。您应该会看到“Hello, World!”的消息。

代码解释：

tornado.ioloop: 处理异步操作的核心事件循环。
tornado.web: 提供 Web 框架组件，如请求处理器和路由。
MainHandler: 一个请求处理器，定义如何处理传入的 HTTP 请求。get() 方法用于处理 GET 请求。
tornado.web.Application: 创建 Tornado 应用，将 URL 模式映射到请求处理器。
app.listen(8888): 启动服务器，在 8888 端口上监听传入的连接。
tornado.ioloop.IOLoop.current().start(): 启动事件循环，处理传入的请求和异步操作。

请求处理器和路由

请求处理器是 Tornado Web 应用的基础。它们定义了如何根据 URL 处理传入的 HTTP 请求。路由则将 URL 映射到特定的请求处理器。

定义请求处理器：

要创建请求处理器，请子类化 tornado.web.RequestHandler 并实现相应的 HTTP 方法（get、post、put、delete 等）。

class MyHandler(tornado.web.RequestHandler):
 def get(self):
  self.write("这是一个 GET 请求。")

 def post(self):
  data = self.request.body.decode('utf-8')
  self.write(f"收到的 POST 数据：{data}")

路由：

在创建 tornado.web.Application 时配置路由。您需要提供一个元组列表，其中每个元组包含一个 URL 模式和相应的请求处理器。

app = tornado.web.Application([
 (r"/", MainHandler),
 (r"/myhandler", MyHandler),
])

URL 模式：

URL 模式是正则表达式。您可以使用正则表达式的分组来捕获 URL 的部分内容，并将其作为参数传递给请求处理器的方法。

class UserHandler(tornado.web.RequestHandler):
 def get(self, user_id):
  self.write(f"用户 ID：{user_id}")

app = tornado.web.Application([
 (r"/user/([0-9]+)", UserHandler),
])

在此示例中，/user/([0-9]+) 匹配像 /user/123 这样的 URL。([0-9]+) 部分捕获一个或多个数字，并将其作为 user_id 参数传递给 UserHandler 的 get 方法。

模板

Tornado 包含一个简单高效的模板引擎。模板用于动态生成 HTML，将表示逻辑与应用逻辑分离开来。

创建模板：

模板通常存储在单独的文件中（例如 index.html）。以下是一个简单的示例：

<!DOCTYPE html>
<html>
<head>
 <title>我的网站</title>
</head>
<body>
 <h1>欢迎, {{ name }}!</h1>
 <p>今天是 {{ today }}。</p>
</body>
</html>

{{ name }} 和 {{ today }} 是占位符，在渲染模板时将被替换为实际值。

渲染模板：

要在请求处理器中渲染模板，请使用 render() 方法：

class TemplateHandler(tornado.web.RequestHandler):
 def get(self):
  name = "John Doe"
  today = "2023-10-27"
  self.render("index.html", name=name, today=today)

请确保在您的应用设置中正确配置了 template_path。默认情况下，Tornado 会在与您的应用文件相同的目录中名为 templates 的文件夹中查找模板。

app = tornado.web.Application([
 (r"/template", TemplateHandler),
], template_path="templates")

模板语法：

Tornado 模板支持多种功能，包括：

变量： {{ variable }}
控制流： {% if condition %} ... {% else %} ... {% end %}, {% for item in items %} ... {% end %}
函数： {{ function(argument) }}
包含： {% include "another_template.html" %}
转义： Tornado 会自动转义 HTML 实体以防止跨站脚本（XSS）攻击。您可以使用 {% raw variable %} 禁用转义。

异步操作

Tornado 的优势在于其异步能力。异步操作允许您的应用执行非阻塞 I/O，从而提高性能和可扩展性。这对于涉及等待外部资源（如数据库查询或网络请求）的任务特别有用。

`@tornado.gen.coroutine`:

@tornado.gen.coroutine 装饰器允许您使用 yield 关键字编写异步代码。这使得异步代码的外观和行为更像同步代码，从而提高了可读性和可维护性。

import tornado.gen
import tornado.httpclient

class AsyncHandler(tornado.web.RequestHandler):
 @tornado.gen.coroutine
 def get(self):
  http_client = tornado.httpclient.AsyncHTTPClient()
  response = yield http_client.fetch("http://example.com")
  self.write(response.body.decode('utf-8'))

在此示例中，http_client.fetch() 是一个返回 Future 的异步操作。yield 关键字会暂停协程的执行，直到 Future 被解析。一旦 Future 被解析，协程将恢复执行，并将响应体写入客户端。

`tornado.concurrent.Future`:

Future 代表一个可能尚不可用的异步操作的结果。您可以使用 Future 对象将异步操作链接在一起并处理错误。

`tornado.ioloop.IOLoop`:

IOLoop 是 Tornado 异步引擎的核心。它监视文件描述符和套接字的事件，并将它们分派给适当的处理器。您通常不需要直接与 IOLoop 交互，但了解它在处理异步操作中的作用很重要。

WebSockets

Tornado 为 WebSockets 提供了出色的支持，实现了服务器和客户端之间的实时通信。WebSockets 是需要双向、低延迟通信的应用的理想选择，例如聊天应用、在线游戏和实时仪表板。

创建 WebSocket 处理器：

要创建 WebSocket 处理器，请子类化 tornado.websocket.WebSocketHandler 并实现以下方法：

open(): 在建立新的 WebSocket 连接时调用。
on_message(message): 在从客户端接收到消息时调用。
on_close(): 在 WebSocket 连接关闭时调用。

import tornado.websocket

class WebSocketHandler(tornado.websocket.WebSocketHandler):
 def open(self):
  print("WebSocket opened")

 def on_message(self, message):
  self.write_message(f"You sent: {message}")

 def on_close(self):
  print("WebSocket closed")

 def check_origin(self, origin):
  return True # 允许跨域 WebSocket 连接

将 WebSockets 集成到您的应用中：

将 WebSocket 处理器添加到您的应用路由配置中：

app = tornado.web.Application([
 (r"/ws", WebSocketHandler),
])

客户端实现：

在客户端，您可以使用 JavaScript 建立 WebSocket 连接并发送/接收消息：

const websocket = new WebSocket("ws://localhost:8888/ws");

websocket.onopen = () => {
 console.log("WebSocket connection established");
 websocket.send("Hello from the client!");
};

websocket.onmessage = (event) => {
 console.log("Received message:", event.data);
};

websocket.onclose = () => {
 console.log("WebSocket connection closed");
};

认证与安全

安全是 Web 应用开发的关键方面。Tornado 提供了多种功能来帮助您保护应用，包括认证、授权以及防范常见的 Web 漏洞。

认证：

认证是验证用户身份的过程。Tornado 内置了对多种认证方案的支持，包括：

基于 Cookie 的认证： 将用户凭据存储在 Cookie 中。
第三方认证（OAuth）： 与 Google、Facebook 和 Twitter 等流行的社交媒体平台集成。
API 密钥： 使用 API 密钥对 API 请求进行认证。

授权：

授权是确定用户是否有权访问特定资源的过程。您可以在请求处理器中实现授权逻辑，以根据用户角色或许可限制访问。

安全最佳实践：

跨站脚本（XSS）防护： Tornado 会自动转义 HTML 实体以防止 XSS 攻击。始终使用 render() 方法渲染模板，避免在请求处理器中直接生成 HTML。
跨站请求伪造（CSRF）防护： 在您的应用设置中启用 CSRF 防护，以防止 CSRF 攻击。
HTTPS： 始终使用 HTTPS 来加密服务器和客户端之间的通信。
输入验证： 验证所有用户输入，以防止注入攻击和其他漏洞。
定期安全审计： 定期进行安全审计，以识别和解决潜在漏洞。

部署

部署 Tornado 应用涉及多个步骤，包括配置 Web 服务器、设置进程管理器和优化性能。

Web 服务器：

您可以将 Tornado 部署在 Nginx 或 Apache 等 Web 服务器后面。Web 服务器充当反向代理，将传入的请求转发到 Tornado 应用。

进程管理器：

可以使用像 Supervisor 或 systemd 这样的进程管理器来管理 Tornado 进程，确保在进程崩溃时能自动重启。

性能优化：

使用生产就绪的事件循环： 使用像 uvloop 这样的生产就绪事件循环以提高性能。
启用 gzip 压缩： 启用 gzip 压缩以减小 HTTP 响应的大小。
缓存静态文件： 缓存静态文件以减少服务器负载。
监控性能： 使用 New Relic 或 Prometheus 等工具监控您的应用性能。

国际化 (i18n) 和本地化 (l10n)

在为全球受众构建应用时，考虑国际化 (i18n) 和本地化 (l10n) 非常重要。i18n 是指在设计应用时，使其无需工程更改即可适应各种语言和地区。l10n 是指通过添加特定区域的组件和翻译文本，为特定语言或地区调整国际化应用的过程。

Tornado 与 i18n/l10n

Tornado 本身没有内置的 i18n/l10n 库。但是，您可以轻松地集成像 `gettext` 这样的标准 Python 库或像 Babel 这样更复杂的框架，在您的 Tornado 应用中处理 i18n/l10n。

使用 `gettext` 的示例：

1. **设置您的区域设置：** 为您想支持的每种语言创建目录，其中包含消息目录（通常是 `.mo` 文件）。

locales/
 en/LC_MESSAGES/messages.mo
 fr/LC_MESSAGES/messages.mo
 de/LC_MESSAGES/messages.mo

2. **提取可翻译字符串：** 使用像 `xgettext` 这样的工具从您的 Python 代码中提取可翻译的字符串到一个 `.po` 文件（可移植对象）中。该文件将包含原始字符串和翻译的占位符。

xgettext -d messages -o locales/messages.po your_tornado_app.py

3. **翻译字符串：** 为每种语言翻译 `.po` 文件中的字符串。

4. **编译翻译：** 将 `.po` 文件编译成 `.mo` 文件（机器对象），`gettext` 在运行时会使用这些文件。

msgfmt locales/fr/LC_MESSAGES/messages.po -o locales/fr/LC_MESSAGES/messages.mo

5. **集成到您的 Tornado 应用中：**

import gettext
import locale
import os
import tornado.web

class BaseHandler(tornado.web.RequestHandler):
 def initialize(self):
  try:
  locale.setlocale(locale.LC_ALL, self.get_user_locale().code)
  except locale.Error:
  # 处理系统不支持区域设置的情况
  print(f"区域设置 {self.get_user_locale().code} 不受支持")

  translation = gettext.translation('messages', 'locales', languages=[self.get_user_locale().code])
  translation.install()
  self._ = translation.gettext

 def get_current_user_locale(self):
  # 确定用户区域设置的逻辑（例如，从 Accept-Language 标头、用户设置等）
  # 这是一个简化的示例 - 您需要一个更健壮的解决方案
  accept_language = self.request.headers.get('Accept-Language', 'en')
  return tornado.locale.get(accept_language.split(',')[0].split(';')[0])

class MainHandler(BaseHandler):
 def get(self):
  self.render("index.html", _=self._)

settings = {
 "template_path": os.path.join(os.path.dirname(__file__), "templates"),
}

app = tornado.web.Application([
 (r"/", MainHandler),
], **settings)

6. **修改您的模板：** 使用 `_()` 函数（绑定到 `gettext.gettext`）在您的模板中标记需要翻译的字符串。

<h1>{{ _("Welcome to our website!") }}</h1>
<p>{{ _("This is a translated paragraph.") }}</p>

面向全球受众的重要考虑因素：

**字符编码：** 始终使用 UTF-8 编码以支持广泛的字符集。
**日期和时间格式化：** 使用特定区域的日期和时间格式。Python 的 `strftime` 和 `strptime` 函数可以与区域设置一起使用。
**数字格式化：** 使用特定区域的数字格式（例如，小数点分隔符、千位分隔符）。`locale` 模块为此提供了函数。
**货币格式化：** 使用特定区域的货币格式。考虑使用像 `Babel` 这样的库进行更高级的货币处理。
**从右到左（RTL）语言：** 支持像阿拉伯语和希伯来语这样的 RTL 语言。这可能需要镜像您网站的布局。
**翻译质量：** 使用专业翻译人员以确保翻译准确且文化上得体。机器翻译可以是一个好的起点，但通常需要人工审校。
**用户区域检测：** 根据用户偏好、浏览器设置或 IP 地址实施可靠的区域检测。提供用户手动选择其首选语言的方式。
**测试：** 使用不同的区域设置彻底测试您的应用，以确保所有内容都显示正确。

高级主题

自定义错误页面：

您可以自定义 Tornado 在发生错误时显示的错误页面。这使您能够提供更友好的用户体验并包含调试信息。

自定义设置：

您可以在应用配置中定义自定义设置，并在请求处理器中访问它们。这对于存储特定于应用的参数（如数据库连接字符串或 API 密钥）很有用。

测试：

彻底测试您的 Tornado 应用，以确保其功能正常且安全。使用单元测试、集成测试和端到端测试来覆盖您应用的所有方面。

结论

Tornado 是一个功能强大且用途广泛的 Web 框架，非常适合构建可扩展、高性能的 Web 应用。其异步架构、WebSocket 支持和易于使用的 API 使其成为全球开发者的热门选择。通过遵循本综合指南中的指导和示例，您可以开始构建自己的 Tornado 应用并利用其众多功能。

请记得查阅官方 Tornado 文档以获取最新的信息和最佳实践。编码愉快！