Tornado 1.2 版本特性全解析：纯 Python HTTP 客户端、请求日志重构与安全增强

Tornado 1.2 版本特性全解析：纯 Python HTTP 客户端、请求日志重构与安全增强

【免费下载链接】tornadoTornado is a Python web framework and asynchronous networking library, originally developed at FriendFeed.项目地址: https://gitcode.com/gh_mirrors/to/tornado

导读

Tornado 1.2 于 2011 年 2 月 20 日发布，是 Tornado 发展史上的一个重要里程碑：它带来了首个不依赖 pycurl 的纯 Python HTTP 客户端tornado.simple_httpclient，将请求日志从RequestHandler迁移至Application层，并新增了Application.listen()、tornado.escape.linkify()、HTTPS 证书校验参数等一系列实用能力。本文以 docs/releases/v1.2.0.rst 为骨架，结合当前仓库源码，逐项讲解这些新特性与修复的用法、原理及在真实项目中的应用方式。读完本文，你将掌握这些特性背后的设计意图、调用方式，并能用当前版本源码验证其演进脉络。

一、版本概述与获取方式

Tornado 1.2 是继 1.1.x 系列之后的功能增强版本，官方公告称其源码包可从https://github.com/downloads/facebook/tornado/tornado-1.2.tar.gz获取。需要注意的是，这是 2011 年的历史版本，当前仓库（tornado/目录）已经演进到 6.x 时代，本文所有源码佐证均以当前仓库实际内容为准，用于对照 1.2 新特性的设计与最终落地形态。

向后兼容性警告（升级前必读）

1.2 版本携带了三项向后不兼容变更，升级前必须评估：

1. 包含 1.1.1 的安全变更：从 1.1 或更早版本升级的用户必须阅读 1.1.1 版本的发布说明（原公告附有 Google Groups 讨论帖链接），该变更涉及安全问题，属于强制升级项。
2. StackContext 需要可重入：凡是在捕获异常之外还做了其他事情的StackContext，可能需要修改为可重入（reentrant）实现，否则在上下文嵌套复用场景下会出现状态串扰。
3. XSRF 令牌覆盖更多方法：启用 XSRF 令牌后，令牌不仅要在 POST 请求中携带，PUT 和 DELETE 请求（即除 GET、HEAD 之外的所有方法）也必须携带。这是对跨站请求伪造防护范围的明确收紧，也是 1.2 中最重要的安全行为变更之一。

二、新特性详解

1. 纯 Python HTTP 客户端：tornado.simple_httpclient

1.2 最具战略意义的新特性是tornado.simple_httpclient模块的引入。此前 Tornado 的异步 HTTP 客户端完全依赖 pycurl 扩展，而新实现不依赖 pycurl，用纯 Python +socket/ssl即可完成 HTTP 请求。

在 1.2 时代，可以通过环境变量切换实现：

USE_SIMPLE_HTTPCLIENT=1 python your_app.py

该环境变量可让tornado.httpclient.AsyncHTTPClient透明地使用新实现。当时官方也明确提示：下一个版本将改用其他方式选择 HTTP 客户端实现。

这一演进在当前仓库中得到了完整印证：

• tornado/httpclient.py 中AsyncHTTPClient.configurable_default()返回tornado.simple_httpclient.SimpleAsyncHTTPClient，即当前版本默认 HTTP 客户端就是纯 Python 实现；
• 模块说明（tornado/httpclient.py）指出：simple_httpclient为默认实现，而curl_httpclient保留了部分simple_httpclient不具备的能力（如完整的代理认证支持等）；
• 两种实现的行为差异可以在测试中对照，例如 tornado/test/curl_httpclient_test.py 与 tornado/test/httpclient_test.py 注释了二者在max_body_size作用于重定向响应上的差异；
• 纯 Python 实现的测试基准见 maint/benchmark/ 目录下的解析性能脚本。

可以推断：1.2 引入的这套纯 Python 实现经受住了生产检验，最终按计划取代了 pycurl 实现成为默认——这正是"新客户端将最终取代 pycurl 客户端"这一官方预期的落地结果。

2. 请求日志迁至 Application 层

1.2 之前请求日志由RequestHandler负责，1.2 起改由Application统一记录，这是日志职责归属的一次架构调整。定制方式有两种：

• 继承Application并覆写log_request方法；
• 通过Application设置项传入log_function回调。

当前源码中该设计依然存在且逻辑清晰（tornado/web.py）：Application.log_request()会先检查self.settings中是否有log_function，有则调用之；否则按状态码选择日志级别——< 400记access_log.info，400~499记warning，>= 500记error，并输出状态码、耗时（毫秒）等字段。也就是说，只需在Application构造时传入log_function即可完全接管访问日志格式：

app = tornado.web.Application( handlers, log_function=lambda handler: print( "%d %s %.2fms" % ( handler.get_status(), handler.request.uri, 1000.0 * handler.request.request_time(), ) ), )

3. Application.listen(port)：一行启动 HTTP 服务

此前启动服务需要显式创建HTTPServer再调用其监听方法，1.2 新增的Application.listen(port)将两步合并。当前源码（tornado/web.py）仍保留该方法，其实现就是"创建HTTPServer并调用其listen"的便捷别名，同时支持address、family、backlog、reuse_port等参数，并返回HTTPServer对象。官方文档同时强调：调用listen()后仍需IOLoop.current().start()（现代版本可置于asyncio.run中）才能真正进入事件循环。

if __name__ == "__main__": app = tornado.web.Application(handlers) app.listen(8888) # 1.2 新增 tornado.ioloop.IOLoop.current().start()

对于多进程等高级用法，官方明确建议不要用该方法，而应直接创建HTTPServer并调用bind()/start()。

4. tornado.escape.linkify()：文本自动转链接

tornado.escape.linkify()是 1.2 新增的文本工具，用于把纯文本中的 URL 自动包裹成<a>标签。例如：

linkify("Hello http://tornadoweb.org!") # => Hello <a href="http://tornadoweb.org">http://tornadoweb.org</a>!

当前实现（tornado/escape.py）进一步支持以下参数：

• shorten：超长 URL 显示时截断（约 30 字符，仅影响展示文本，不影响 href）；
• extra_params：附加到链接标签的额外属性字符串，或接收 URL 返回属性文本的可调用对象，例如'rel="nofollow" class="external"'；
• require_protocol：为True时只链接带协议的 URL，为False（默认）时www.example.com这类无协议写法也会被链接；
• permitted_protocols：允许链接的协议白名单，默认["http", "https"]。官方强调：把javascript等协议加入白名单非常危险，这正是防止 XSS 的关键设计。

另外 1.2 还修复了xhtml_escape()的返回类型问题：现在返回unicode 字符串而非 utf-8 编码的字节串，与escape模块的其余 API（如 tornado/escape.py 中utf8()、to_unicode()）的字符语义保持一致。

5. RequestHandler.create_signed_value()：不落 Cookie 的签名值

secure_cookie系列方法（set_secure_cookie/get_secure_cookie）在 1.2 之前已能生成带签名的 Cookie，而 1.2 新增的create_signed_value()则把"生成签名值"这一步独立出来，不设置任何 Cookie，适合需要手动控制 Cookie 过期时间或通过其他渠道（如表单隐藏字段）传递签名值的场景。

当前源码中该方法定义于 tornado/web.py，模块级函数create_signed_value位于 tornado/web.py，配套的解签函数decode_signed_value位于 tornado/web.py，二者共同构成"签名—验签"闭环，其核心算法沿用 HMAC 签名方案。

6. tornado.testing.get_unused_port() 与 AsyncHTTPTestCase.fetch()

1.2 将测试中"挑一个空闲端口"的常用逻辑提炼为tornado.testing.get_unused_port()，其端口选取方式与AsyncHTTPTestCase内部一致，避免测试间端口冲突。当前版本该能力演化为 tornado/testing.py 中的bind_unused_port()，返回(socket, port)二元组，测试代码中大量使用，例如 tornado/test/httpclient_test.py、tornado/test/ioloop_test.py。

同时AsyncHTTPTestCase.fetch()提供了同步取回响应的便捷方法，让测试代码可以直白地写成：

class MyTest(AsyncHTTPTestCase): def get_app(self): return Application([(r"/", MainHandler)]) def test_homepage(self): response = self.fetch("/") # 同步返回 HTTPResponse self.assertEqual(response.code, 200)

7. IOLoop.set_blocking_signal_threshold()：阻塞监测

IOLoop.set_blocking_signal_threshold()允许设置一个阈值，当事件循环被阻塞（即单次循环迭代耗时超过阈值）时触发回调，用于定位"事件循环卡住"的性能问题。其配套的set_blocking_log_threshold()则直接把阻塞事件写入日志。该 API 对排查阻塞型 Handler 非常有效——Tornado 是单线程事件驱动模型，任何同步耗时操作都会阻塞整个服务，该特性提供了一种廉价的运行时观测手段。

8. IOStream.connect()：客户端异步连接

1.2 之前IOStream主要承担服务端已建立连接的读写封装，1.2 新增的IOStream.connect()让客户端也能异步发起 socket 连接。当前源码中IOStream.connect存在两个重载版本（tornado/iostream.py 与 tornado/iostream.py），后者对应SSLIOStream的 TLS 握手场景；更高层的 tornado/tcpclient.py 的TCPClient.connect也基于此构建。这让"在 Tornado 内直接写异步 TCP 客户端"成为可能，与 demos 中的 demos/tcpecho/client.py 演示场景一脉相承。

9. HTTPRequest 新增 validate_cert 与 ca_certs（HTTPS 安全）

1.2 为tornado.httpclient.HTTPRequest增加了两个 HTTPS 关键参数：

• validate_cert（默认True）：设为False时禁用全部证书校验，适合自签名证书的内部调试环境，但生产环境务必保持开启；
• ca_certs：指定包含受信 CA 的 PEM 文件路径，未指定时使用系统默认信任库。

当前源码中的完整签名与语义见 tornado/httpclient.py 及文档注释（tornado/httpclient.py）。两个实现的表现略有差异：

• pycurl 实现通过pycurl.SSL_VERIFYPEER与pycurl.CAINFO生效（tornado/curl_httpclient.py）；
• 纯 Python 实现基于标准库ssl上下文，validate_cert=False时跳过校验，否则用ssl.create_default_context(ssl.Purpose.SERVER_AUTH, cafile=...)加载 CA（tornado/simple_httpclient.py）。

req = tornado.httpclient.HTTPRequest( "https://internal.example.com/", validate_cert=False, # 仅限内部调试 # ca_certs="/path/to/custom-ca.pem", # 自定义信任库 )

另外 1.2 还为HTTPRequest增加了get_ssl_certificate()方法，用于取回服务端（或在客户端证书场景下）的 SSL 证书信息，对应 tornado/httputil.py。

10. StaticFileHandler 支持目录默认文件

1.2 让StaticFileHandler可以配置"请求目录时返回默认文件"，典型用途就是目录请求返回index.html。这一能力在 demo 中可直接落地：例如 demos/blog/blog.py 这类带静态资源的应用，只需为静态路径设置default_filename="index.html"，访问目录时即可自动命中首页文件。

11. 模板支持 {% from x import y %}

1.2 在原有{% import x %}基础上，新增了对 Python 风格导入语句的模板支持：

{% from datetime import datetime %} {{ datetime.now() }}

这使模板能按需导入模块中的特定符号，避免整模块导入带来的命名空间污染，与 docs/template.rst 所讲述的模板语法体系互相配合。

12. FacebookGraphMixin.get_authenticated_user 新增 extra_fields

FacebookGraphMixin.get_authenticated_user在 1.2 增加了extra_fields参数，用于请求额外的用户信息字段。当前源码（tornado/auth.py）中该方法会合并基础字段（如id、name、link）与extra_fields指定的字段后向 Graph API 发起请求。完整调用链与 demo 可参考 tornado/test/auth_test.py 中的认证测试。

三、Bug 修复清单（按模块分类）

1.2 修复了大量问题，按模块归类如下：

这些修复在当前代码库中大多能找到对应实现或测试佐证，例如xheaders与X-Forwarded-Proto的解析逻辑、StaticFileHandler的缓存与 Etag 处理等，均可对照 tornado/httpserver.py、tornado/web.py 及其测试 tornado/test/httpserver_test.py、tornado/test/web_test.py 深入阅读。

四、小结与版本演进脉络

Tornado 1.2 的核心贡献可以概括为三条主线：

1. HTTP 客户端去 pycurl 化：tornado.simple_httpclient用纯 Python 实现了完整客户端能力，并配套validate_cert/ca_certs补齐 HTTPS 安全控制，最终在后续版本中成为默认实现（当前 tornado/httpclient.py 可验证）；
2. Web 框架层职责收敛：请求日志上收到Application层（log_request/log_function），配合Application.listen()简化启动代码，XSRF 防护覆盖 PUT/DELETE 等全部非 GET/HEAD 方法，安全边界更明确；
3. 异步基础设施补全：IOStream.connect()、IOLoop.set_blocking_signal_threshold()分别补上了客户端连接与运行期观测两块拼图。

对于想要对照历史版本行为的读者，建议将本文提及的 API 与当前源码逐一比对（如get_unused_port()→bind_unused_port()、USE_SIMPLE_HTTPCLIENT环境变量 →AsyncHTTPClient.configure()机制），从而更清楚地看到 Tornado 从 1.2 到 6.x 的设计演化轨迹。

本文事实依据：官方发布说明 docs/releases/v1.2.0.rst 及当前仓库源码（tornado/httpclient.py、tornado/web.py、tornado/escape.py、tornado/auth.py、tornado/curl_httpclient.py、tornado/simple_httpclient.py、tornado/iostream.py、tornado/testing.py）与相应测试文件。

【免费下载链接】tornadoTornado is a Python web framework and asynchronous networking library, originally developed at FriendFeed.项目地址: https://gitcode.com/gh_mirrors/to/tornado