Tornado-基本入门

这篇讲什么

  • Tornado 既是 Web 框架也是 HTTP 服务器,核心卖点是异步非阻塞 IO,适合长连接、WebSocket 和高并发场景;这篇先把「一个能跑的最小服务」写出来。
  • 覆盖安装、两种启动写法、bind() 与 start() 的多进程语义、tornado.options 的命令行与配置文件、日志开关,以及访问日志和 keep-alive 的实测行为。
  • 所有结论都在本机跑过:Windows 用 Tornado 6.6 + Python 3.14.10,多进程部分另在 WSL Ubuntu(8 核)实测,因为 fork 在 Windows 上根本不可用。

Tornado 是什么

  • 官方首页的定义是一句话:Tornado is a Python web framework using non-blocking I/O(用非阻塞 IO 的 Python Web 框架),并且强调它「scales to tens of thousands of open connections」——能撑住上万个同时打开的连接。

  • 所以 Tornado 其实是三个东西装在一个包里,这也是它和 Django、Flask 最大的区别:

    • 一个 Web 框架:路由 + RequestHandler + 模板渲染。
    • 一个 HTTP 服务器:tornado.httpserver.HTTPServer,自己监听端口,不需要再套一层 WSGI 服务器。
    • 一个 异步网络库:AsyncHTTPClient、IOLoop、WebSocket 这些都能单独用,跟 Web 无关。
  • 「高效原理」这张老图仍然说得通:单个进程内用一个事件循环(IOLoop)盯着所有 socket,谁可读可读谁,不靠线程也不靠进程数堆并发。

    Tornado 工作原理

C10K 是什么

  • C10K = Concurrently handling 10K connections,即单机同时扛一万个连接,是当年 Linux 网络编程的一个门槛指标,Tornado 就是为这类场景设计的。

  • 传统「一个连接一个线程/进程」的模型,一万个连接就要一万个线程,光调度和内存就撑不住;Tornado 用非阻塞 IO + 事件循环,一个线程管几千个连接。

  • 官方对平台的说法(原文口径):Python 3 是硬要求;在支持 epoll(Linux)、kqueue(BSD/macOS)的系统上性能和扩展性最好;Windows 能跑,但不是官方推荐的生产平台。

  • 本机实测印证了「Windows 能跑」:IOLoop.current() 拿到的其实是 asyncio 的 ProactorEventLoop,服务起得来、请求答得了。

    1
    2
    IOLoop.current() 实际类型: AsyncIOMainLoop
    跑起来的事件循环: ProactorEventLoop
  • 结论:学习和开发用 Windows 完全没问题;真要上线扛并发,按官方口径放 Linux。

什么时候该用它

  • 长连接场景(WebSocket 聊天、实时推送、长轮询)——这是 Tornado 的主场。
  • 需要同时向外发很多请求(爬虫、聚合多个上游接口)——AsyncHTTPClient 很合适。
  • 普通 CRUD 后台、要现成的 ORM 和管理页面——用 Django 更省事,别为了「异步」二字上 Tornado。

与 Django 的分工

  • 老笔记拿 Tornado 和 Web.py 类比,那个框架早就没人用了;现在对比的参照物是 Django 和 Flask。

    维度 Django Flask Tornado
    定位 大而全,注重开发效率 微框架,注重灵活 少而精,注重并发
    自带 HTTP 服务器 只有开发用的 只有开发用的 自带生产可用的
    IO 模型 同步阻塞(另有 ASGI 异步路线) 同步阻塞 异步非阻塞
    ORM 内置且和框架深度绑定 靠扩展(Flask-SQLAlchemy) 没有,随便挑(SQLAlchemy/Tortoise/原生驱动)
    管理后台 内置 admin 无 无
    模板 Django Template Jinja2 自带 Tornado 模板(也是 Jinja 风格)
    WebSocket 要靠 Channels 要靠扩展 内置
  • 耦合度这条老笔记说得对:Django 的便利是绑在它的 ORM 上的,换掉 ORM 就享受不到那一堆自动化;Tornado 反过来,核心很薄,什么都得自己接。

  • 两者不是二选一:常见做法是业务后台用 Django,实时那块单独用 Tornado 服务,前面用 nginx 按路径分流。

安装与最小服务

  • 装最新的就行,本系列基线是 Tornado 6.6:

    1
    pip install tornado
    1
    2
    3
    tornado 6.6 | python 3.14.10
    Requires-Python: >= 3.11
    Summary: Tornado is a Python web framework and asynchronous networking library, originally developed at FriendFeed.
  • 官方文档把 pycurl、pycares 列为可选前置依赖,本机两个都没装也照常跑:默认的异步 HTTP 客户端是纯 Python 的 SimpleAsyncHTTPClient;只有你去 import tornado.curl_httpclient 才会因为缺 pycurl 报 ModuleNotFoundError。

  • 老笔记钉的是 pip install tornado==5.1.1。5.x 从 2018 年起就没再发版,tornado.web.run_simple、web.execute、@web.asynchronous、web.stream_callback 这些入口在 6.x 里已经删干净(实测 hasattr 全为 False),所以别照抄 5.1.1 那套。

  • 最小可跑服务,一个文件就够:

    app.py
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    import tornado.ioloop
    import tornado.web


    class IndexHandler(tornado.web.RequestHandler):
    def get(self):
    self.write("hello, tornado")


    if __name__ == "__main__":
    app = tornado.web.Application([(r"/", IndexHandler)])
    app.listen(8888)
    tornado.ioloop.IOLoop.current().start()
  • 实测浏览器或 curl 访问 http://127.0.0.1:8888/:

    1
    2
    3
    4
    5
    HTTP/1.1 200 OK
    Server: TornadoServer/6.6
    Content-Type: text/html; charset=UTF-8

    hello, tornado

    终端同时打一行访问日志:

    1
    200 GET / (127.0.0.1) 0.33ms
  • 逐行看懂:

    • RequestHandler 是「一个 URL 对应一个类」,相当于 Django 的视图函数;类里写了哪个 HTTP 方法名的方法,就只接哪个方法。
    • Application([(r"/", IndexHandler)]) 收的是「正则 → 处理类」的列表,这就是路由表;r"/" 里的 r 是 Python 的原始字符串,正则里反斜杠不用 double。
    • app.listen(8888) 只是把端口占上,真正开始处理请求要等最后一行的事件循环启动。
  • 只写 get 的 handler,收到 POST 会直接 405,实测:

    1
    2
    POST / -> HTTP 405
    405 POST / (127.0.0.1) 0.33ms
  • 能接哪些方法由类属性决定,实测默认值:

    1
    RequestHandler.SUPPORTED_METHODS -> ('GET', 'HEAD', 'POST', 'DELETE', 'PATCH', 'PUT', 'OPTIONS')

两种启动写法

  • app.listen(port) 是简写,内部就是造一个 HTTPServer。等价的「显式」写法:

    app.py
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    import tornado.httpserver
    import tornado.ioloop
    import tornado.web


    class IndexHandler(tornado.web.RequestHandler):
    def get(self):
    self.write("hello, tornado")


    if __name__ == "__main__":
    app = tornado.web.Application([(r"/", IndexHandler)])
    http_server = tornado.httpserver.HTTPServer(app)
    http_server.listen(8888)
    tornado.ioloop.IOLoop.current().start()
  • app.listen() 的返回值就是那个 HTTPServer 对象,实测类型:

    1
    app.listen(8905) -> <class 'tornado.httpserver.HTTPServer'>
  • 两个签名放这里,参数名以后要查就用得上:

    1
    2
    3
    4
    5
    Application.listen(port, address=None, *, family=AF_UNSPEC, backlog=128,
    flags=None, reuse_port=False, **kwargs) -> HTTPServer
    HTTPServer.bind(port, address=None, family=AF_UNSPEC, backlog=128,
    flags=None, reuse_port=False) -> None
    HTTPServer.start(num_processes=1, max_restarts=None) -> None

listen 之后到底有没有在监听

  • 老笔记那句「绑定监听端口,注意:此时服务器并没有开启监听」半对半错,实测拆开看:

    test_bind.py
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    import socket
    import tornado.httpserver
    import tornado.web

    app = tornado.web.Application([(r"/", IndexHandler)])
    http_server = tornado.httpserver.HTTPServer(app)
    http_server.bind(8902) # 没有 start(),也没进事件循环

    s = socket.create_connection(("127.0.0.1", 8902), timeout=2)
    s.sendall(b"GET / HTTP/1.1\r\nHost: x\r\n\r\n")
    print(s.recv(100)) # 等 2 秒,超时
    1
    2
    TCP 三次握手: 成功(OS 层已经在 LISTEN)
    发 HTTP 请求后 2 秒没响应(没人 accept,事件循环没跑)
  • 准确说法是:bind()(以及 listen())已经把端口占住、内核也开始收连接进 backlog,但没有 accept、也没有处理请求,所以端口是「占着但不干活」。要真正服务,必须让 IOLoop 跑起来。

  • 也正因为如此,listen() 之后不 start() 的进程会把端口一直占住,调试时 Ctrl+C 不干净就会留下「Address already in use」。

用 asyncio 起(现代写法)

  • Tornado 6 就是 asyncio 之上的封装,所以也可以反过来用 asyncio.run():

    app_async.py
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    import asyncio

    import tornado.ioloop
    import tornado.web


    class IndexHandler(tornado.web.RequestHandler):
    def get(self):
    self.write("hello, tornado")


    async def main():
    app = tornado.web.Application([(r"/", IndexHandler)])
    http_server = tornado.httpserver.HTTPServer(app)
    http_server.listen(8888)
    await asyncio.Event().wait() # 让循环一直跑着


    if __name__ == "__main__":
    asyncio.run(main())
  • 两种写法实测都能正常起服务。老笔记那种 IOLoop.current().start() 仍然有效,是官方文档里一直在用的写法,继续用没问题。

多进程

  • Tornado 默认单进程:一个进程一个事件循环,靠异步扛并发。要吃满多核 CPU,才需要多进程。

  • 官方给的多进程入口是 bind() + start():

    app.py
    1
    2
    3
    4
    5
    6
    if __name__ == "__main__":
    app = tornado.web.Application([(r"/", IndexHandler)])
    http_server = tornado.httpserver.HTTPServer(app)
    http_server.bind(8888)
    http_server.start(4) # 1 个父进程 + 4 个子进程
    tornado.ioloop.IOLoop.current().start()
  • start(n) 的语义实测(WSL Ubuntu,nproc 为 8):

    写法 进程数实测 说明
    start(1) 1 不 fork,父进程自己干
    start(4) 5 1 父 + 4 子
    start(0) 9 按 CPU 核数(8)+ 父进程
  • 老笔记写的是「值为 None 或者小于等于 0,开启 CPU 核心数个子进程」,实测要补一句:start(None) 会直接 AssertionError,能触发「按核数」的只有 0(或负数)。

  • 请求确实分散在不同子进程里(handler 返回自己的 pid):

    1
    六次请求返回的 pid: 85094 85094 85094 85095 85095 85095

    注意只落在 4 个 worker 中的 2 个上——多个子进程共享同一个监听 socket,内核唤醒谁没有保证,分发本来就不均匀,别拿「请求数 ÷ 进程数」去预期。

  • Windows 上这条路是断的,实测三种写法:

    1
    2
    3
    start(2)   -> Exception: fork not available on windows
    start(0) -> Exception: fork not available on windows
    start(None) -> AssertionError

    原因是 start() 靠 fork 复制进程,Windows 没有 fork。所以在 Windows 上要开多进程,只能「一个进程一个端口」手动起多个实例,或者用 reuse_port=True 让多个进程各自 bind 同一端口(Linux 才支持)。

  • 老笔记「不建议用 start() 起多进程,推荐手动多进程」的三条理由仍然成立,值得原样记住:

    • 子进程是从父进程复制来的,创建子进程之前改过 IOLoop,会影响所有子进程。
    • 所有进程由一条命令带起来,改代码必须整体重启,做不到不停服滚动更新。
    • 所有进程共享一个端口,单独监控某个进程很麻烦。
  • 生产上更常见的做法是让进程管理器去管:Linux 用 systemd/supervisord 起 N 个单进程实例,或者干脆用 tornado.process.fork_processes();HTTPServer.start() 适合「本机多核跑满」这种简单需求。

tornado.options

  • tornado.options 是 Tornado 自带的一套「全局参数定义 + 从命令行/配置文件读值」的小框架,作用就是把 port、debug 这类参数集中起来,不用自己写 argparse。

  • 6.6 实测的 define() 签名:

    1
    2
    define(name, default=None, type=None, help=None, metavar=None,
    multiple=False, group=None, callback=None)
  • 定义完就挂在 tornado.options.options 这个全局对象上,取值为 options.port。它自带一批内置选项,实测清单:

    1
    2
    help, logging, log-to-stderr, log-file-prefix, log-file-max-size,
    log-file-num-backups, log-rotate-when, log-rotate-interval, log-rotate-mode
  • 键名有个容易懵的细节:define('max_body_count') 存进去是 max-body-count(下划线转连字符),但三种取法都通:options.max_body_count、options['max-body-count']、命令行 --max-body-count=25 或 --max_body_count=30 实测都能改到同一个值。

从命令行取值

  • 完整可跑的示例:

    app.py
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    import tornado.httpserver
    import tornado.ioloop
    import tornado.options
    import tornado.web

    tornado.options.define("port", default=8000, type=int)
    tornado.options.define("mylist", default=[], type=str, multiple=True)


    class IndexHandler(tornado.web.RequestHandler):
    def get(self):
    self.write("port=%s list=%s" % (
    tornado.options.options.port, tornado.options.options.mylist))


    if __name__ == "__main__":
    tornado.options.parse_command_line()
    app = tornado.web.Application([(r"/", IndexHandler)])
    http_server = tornado.httpserver.HTTPServer(app)
    http_server.bind(tornado.options.options.port)
    http_server.start(1)
    tornado.ioloop.IOLoop.current().start()
    1
    python app.py --port=8848 --mylist=good,nice,handsome,cool
    1
    GET / -> port=8848 list=['good', 'nice', 'handsome', 'cool']
  • 类型会按 type 转换,实测这些写法:

    定义 命令行 实测值
    type=int --port=8848 8848(int)
    type=str, multiple=True --mylist=a,b,c ['a', 'b', 'c']
    type=int, multiple=True --nums=1:4 [1, 2, 3, 4](x:y 是区间写法)
    type=bool --debug(不带值) True,等价 --debug=true
    type=bool --debug=false False
    type=datetime.timedelta --delta=90s / --delta=5m timedelta(seconds=90) / timedelta(seconds=300)
    type=datetime.datetime --when=2026-11-06 datetime(2026, 11, 6, 0, 0)
  • type 不写时按 default 的类型推断,实测 default=7000 推断成 int;default 也不写则按 str 处理(内部 type 记为 str、值为 None)。

三个实测到的坑

  • 坑一:parse_command_line(args) 的第一个元素会被当成程序名跳过。它默认吃 sys.argv,而 sys.argv[0] 就是脚本名。手工传列表时必须补一个占位,否则第一个参数白写:

    1
    2
    parse_command_line(['--port=8848'])        -> port 仍是默认值 8000
    parse_command_line(['prog', '--port=8848']) -> port = 8848
  • 坑二:不认识的选项会先打印整页帮助再报错,报错原文:

    1
    Error: Unrecognized command line option: 'nope'
  • 坑三:转换失败抛的异常不一定友好,实测三种:

    1
    2
    3
    --port=abc(type=int)      -> ValueError: invalid literal for int() with base 10: 'abc'
    --name(type=str 却不带值) -> Error: Option 'name' requires a value
    --delta=abc(type=timedelta)-> Exception: (空消息,光秃秃一个 Exception)
  • 重复 define 同一个名字,报错原文(老笔记说会报 already define,实际措辞是这样):

    1
    Error: Option 'port' already defined in E:\...\app.py

从配置文件取值

  • parse_config_file(path) 读的是一个按 Python 语法写的文件(老笔记里那个文件就叫 config,没有扩展名也行):

    config
    1
    2
    port = 7000
    mylist = ['good', 'nice']
    app.py
    1
    tornado.options.parse_config_file("config")
    1
    port = 7000 | mylist = ['good', 'nice']
  • 老笔记说「不支持字典类型」,实测结论要精确一点:字典能不能读进来,取决于你有没有 define 它、以及 type 是什么。

    1
    2
    3
    配置文件里有 adict = {'k': 1}
    没 define adict -> 这个键被直接忽略,options 里查不到
    define('adict', type=dict) 再 parse -> adict = {'k': 1}
  • 同理,配置文件里那些没 define 过的键(哪怕是 computed = 2 * 3 这种表达式)都不报错、也不进 options——它确实是按 Python 执行的,只是结果没人接。

  • 第三种做法(老笔记的「最终版本」)跟 tornado.options 无关,就是普通地写个配置模块再 import:

    config.py
    1
    2
    3
    4
    options = {
    "port": 8080,
    "mylist": ["good", "nice", "handsome"],
    }
    app.py
    1
    2
    3
    import config

    http_server.bind(config.options["port"])

    这种做法没有命令行覆盖、没有类型转换,好处是零依赖;项目一大还是前两种更成体系。

日志

  • 只要调了 parse_command_line() 或 parse_config_file(),Tornado 就顺手把 logging 配好了,实测:

    1
    2
    没 parse            -> handlers=0 级别=WARNING
    parse_command_line -> handlers=1 级别=INFO

    默认的日志格式串(实测从 handler 的 formatter 里读出来的):

    1
    %(color)s[%(levelname)1.1s %(asctime)s %(module)s:%(lineno)d]%(end_color)s %(message)s
  • 关掉日志的两种办法,实测在新进程里都真的关掉了(handlers=0):

    app.py
    1
    2
    3
    4
    import tornado.options

    tornado.options.options.logging = None # 必须在 parse 之前
    tornado.options.parse_config_file("config")
    1
    python app.py --port=8848 --logging=none
  • --logging 的取值实测:

    取值 根 logger 级别
    debug DEBUG
    info(默认) INFO
    warning WARNING
    error ERROR
    none 不配 handler(等于关掉)
  • 访问日志由 RequestHandler 的 log_request 负责,格式实测:

    1
    2
    3
    200 GET / (127.0.0.1) 0.33ms
    404 GET /x?a=1 (127.0.0.1) 0.39ms
    405 POST / (127.0.0.1) 0.33ms

    即「状态码 方法 路径 (客户端 IP) 耗时」,路径带查询串、耗时精确到 0.01ms,排查慢请求很方便。

  • 出未捕获异常时,日志里是完整的 traceback,响应是 500 页面:

    1
    2
    3
    4
    5
    6
    Uncaught exception GET / (127.0.0.1)
    HTTPServerRequest(protocol='http', host='x', method='GET', uri='/', version='HTTP/1.1', remote_ip='127.0.0.1')
    Traceback (most recent call last):
    ...
    AttributeError: 'HTTPServerRequest' object has no attribute 'remote_addr'
    500 GET / (127.0.0.1) 3.20ms

    这条 traceback 本身也是个实测结论:取客户端 IP 要写 self.request.remote_ip,remote_addr 不存在(那是 Flask/Werkzeug 那边的名字)。

连接与转发头

  • 老笔记「使用场景」里讲的 HTTP 持久连接,在 Tornado 上是默认行为,实测在同一条 TCP 连接上连发两个 HTTP/1.1 请求:

    1
    2
    第一个响应头 Connection: (没有这个头,即默认 keep-alive)
    同一连接第二个请求也拿到了: True
    • HTTP/1.1 默认持久连接,所以服务端不用带 Connection: keep-alive。
    • 用 HTTP/1.0 请求时,响应同样不带 Connection 头,连接按 1.0 的语义关闭。
  • 反向代理场景下取真实客户端 IP,Tornado 的做法是给 HTTPServer 传 xheaders=True,它会读 X-Real-IP(以及 X-Scheme):

    app.py
    1
    http_server = tornado.httpserver.HTTPServer(app, xheaders=True)

    实测同一个请求(客户端伪造了 X-Real-IP: 9.9.9.9):

    1
    2
    xheaders=False -> remote_ip = '127.0.0.1'
    xheaders=True -> remote_ip = '9.9.9.9'
  • 这条开关的安全含义和 Flask 那边一模一样:只有前面确实是一层可信代理时才开,否则客户端自己塞一个头就能伪造来源 IP。Tornado 没有 ProxyFix 那种「按层数取第 N 个」的处理,xheaders 就是简单地信 X-Real-IP,多层代理时要在 nginx 侧把 X-Real-IP 设成正确的值。

性能说法怎么看

  • 老笔记那句「官方用 nginx 反向代理做对比,最大浏览量超过第二名近 40%」,现在在官方文档里找不到这个榜单,属于早期(FriendFeed 时代)的宣传口径,别再当依据引用。

  • 想要量级感,本机自己测一个数才有意义。同一台机器、同一个 handler,用 Tornado 自己的异步客户端打 5000 个请求:

    bench.py
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    import asyncio

    import tornado.httpclient
    import tornado.ioloop
    import tornado.web


    class IndexHandler(tornado.web.RequestHandler):
    def get(self):
    self.write("ok")


    async def run(n_conn=50, n_each=100):
    client = tornado.httpclient.AsyncHTTPClient()

    async def worker():
    for _ in range(n_each):
    await client.fetch("http://127.0.0.1:8899/")

    loop = asyncio.get_running_loop()
    t0 = loop.time()
    await asyncio.gather(*(worker() for _ in range(n_conn)))
    dt = loop.time() - t0
    return n_conn * n_each, dt


    if __name__ == "__main__":
    app = tornado.web.Application([(r"/", IndexHandler)])
    server = app.listen(8899)
    total, dt = tornado.ioloop.IOLoop.current().run_sync(run)
    print("%d 个请求 / %.2f s = %.0f req/s" % (total, dt, total / dt))
    server.stop()
    1
    5000 个请求 / 11.60 s = 431 req/s(50 并发 × 100 次)
  • 这个数字只能说明「Windows + 纯 Python 客户端 + 回环」这一套的量级,不能拿去和任何 Linux 榜单比:压测工具本身(这里是 SimpleAsyncHTTPClient)往往比服务端先到瓶颈。真要评估,用 wrk/hey 这类工具在目标部署平台上测,并且同时看 CPU、内存和 p99 延迟。

  • 能确定的只有方向:连接数越高、单连接越「挂着不动」,Tornado 相对同步框架的优势越明显;纯 CPU 计算密集的场景,异步帮不上忙。

参考