Tornado 核心模块概览

了解 Tornado 自身的核心模块，这有助于你理解各个组件的职责，这些模块在你安装 Tornado 后，位于你的 Python 环境的 site-packages/tornado/ 目录下。

• tornado.web: 核心模块，包含了 Application、RequestHandler、uimethod、uimodule 等所有 Web 开发所需的核心类和函数,你编写的绝大部分业务逻辑都在这个模块下。
• tornado.ioloop: 事件循环，Tornado 的心脏，负责处理所有 I/O 事件（网络连接、定时器等），你通常只需要创建并启动一个 IOLoop 实例。
• tornado.httpserver: HTTP 服务器，一个简单的、非阻塞的 HTTP 服务器，用于接收 Application 的请求。
• tornado.options: 命令行选项，提供了一个简单的方式来定义和解析命令行参数，非常适合配置开发、生产等不同环境的设置。
• tornado.escape: 转义工具，提供 HTML、JSON、URL 等内容的转义和反转义功能，防止 XSS 等安全问题。
• tornado.template: 模板引擎，一个简单、快速的模板系统，支持模板继承、包含和控制流。
• tornado.auth: 第三方认证，集成了对 Google OpenID、Facebook Graph API、Twitter OAuth 等常见认证服务的支持。
• tornado.gen: 生成器风格的协程，这是 Tornado 实现异步代码最优雅的方式之一，通过 @tornado.gen.coroutine 装饰器,可以用同步的写法实现异步逻辑。
• tornado.httpclient: 异步 HTTP 客户端，用于在应用内部异步地发起 HTTP 请求，可以调用其他 Web 服务的 API。
• tornado.websocket: WebSocket 支持，提供了服务器端和客户端的 WebSocket 实现,用于构建实时应用。
• tornado.process: 多进程管理，可以方便地启动和管理多个子进程，以利用多核 CPU。

一个标准 Tornado 项目的目录结构

对于一个典型的 Tornado Web 应用，推荐的项目结构如下，这种结构清晰地分离了配置、路由、处理器、业务逻辑、模板和静态资源。

my_tornado_app/
├── app/
│   ├── __init__.py          # 应用入口，创建 Application 和 HTTPServer 实例
│   ├── handlers/            # 所有请求处理器 (RequestHandler) 目录
│   │   ├── __init__.py
│   │   ├── main.py         # 首页、关于我们等页面的处理器
│   │   ├── auth.py         # 用户认证相关的处理器 (登录、注册、登出)
│   │   └── api/            # API 接口处理器目录
│   │       ├── __init__.py
│   │       └── v1/
│   │           ├── __init__.py
│   │           └── users.py # 用户相关的 API v1
│   ├── services/           # 业务逻辑层，处理数据库操作、调用外部服务等
│   │   ├── __init__.py
│   │   └── user_service.py
│   ├── utils/              # 工具函数库
│   │   ├── __init__.py
│   │   └── helpers.py
│   └── settings.py         # 应用配置文件 (开发/生产环境)
│
├── static/                 # 静态文件目录 (CSS, JS, 图片, 字体等)
│   ├── css/
│   ├── js/
│   └── images/
│
├── templates/              # HTML 模板文件目录
│   ├── base.html          # 基础模板，定义了通用的页面结构
│   ├── index.html         # 首页模板
│   └── login.html         # 登录页模板
│
├── tests/                  # 单元测试和集成测试
│   ├── __init__.py
│   ├── test_handlers.py
│   └── test_services.py
│
├── requirements.txt        # 项目依赖列表
├── run.py                  # 启动脚本 (开发环境)
└── config.py               # 全局配置，如密钥、数据库连接等

目录结构详解

app/ - 应用核心目录

这是你应用的主要代码所在。

• app/__init__.py (应用入口)

  • 这个文件是应用的“总调度室”,它负责：

    
    （图片来源网络，侵删）
    1. 导入所有 handlers。
    2. 定义 URL 路由规则 (tornado.web.URLSpec 或 tornado.web.url)。
    3. 创建 tornado.web.Application 实例，并传入路由列表、模板路径、静态路径等。
    4. 创建 tornado.httpserver.HTTPServer 实例，并绑定 Application。
    5. 启动 IOLoop。

  • 示例 (app/__init__.py):

    import tornado.web
    import tornado.ioloop
    import tornado.httpserver
    from tornado.options import define, options
    # 导入处理器
    from app.handlers.main import MainHandler
    from app.handlers.auth import LoginHandler, LogoutHandler
    from app.handlers.api.v1.users import UserAPIHandler
    # 定义命令行选项
    define("port", default=8888, help="run on the given port", type=int)
    def make_app():
        # 定义路由
        routes = [
            (r"/", MainHandler),
            (r"/login", LoginHandler),
            (r"/logout", LogoutHandler),
            (r"/api/v1/users", UserAPIHandler),
        ]
        # 创建 Application
        return tornado.web.Application(
            routes,
            template_path="templates",  # 模板目录
            static_path="static",        # 静态文件目录
            debug=True,                  # 开发环境开启调试模式
        )
    if __name__ == "__main__":
        # 解析命令行参数
        tornado.options.parse_command_line()
        app = make_app()
        http_server = tornado.httpserver.HTTPServer(app)
        http_server.listen(options.port)
        print(f"Server is running on port {options.port}")
        tornado.ioloop.IOLoop.current().start()

• app/handlers/ (请求处理器)

  • 每个文件或类对应一个或一组 URL 路径。

  • 负责接收 HTTP 请求，处理用户输入，调用业务逻辑（services），并返回响应（渲染模板或返回 JSON）。

    
    （图片来源网络，侵删）

  • 示例 (app/handlers/main.py):

    import tornado.web
    from app.services.user_service import UserService
    class MainHandler(tornado.web.RequestHandler):
        def get(self):
            # 调用业务逻辑层获取数据
            user_service = UserService()
            user = user_service.get_current_user(self)
            self.render("index.html", user=user)

• app/services/ (业务逻辑层)

  • 这是应用的“大脑”，它不关心 HTTP 请求,只负责处理核心业务规则。
  • 用户注册、数据验证、数据库增删改查、调用第三方 API 等。
  • 示例 (app/services/user_service.py):

    class UserService:
        def get_current_user(self, handler):
            session_id = handler.get_secure_cookie("session_id")
            if session_id:
                # 这里应该查询数据库获取用户信息
                return {"name": "John Doe", "id": session_id}
            return None

• app/utils/ (工具函数)

  放置一些可复用的、与业务逻辑无关的工具函数，如日期格式化、字符串处理、加密等。

• app/settings.py (应用配置)

  • 存放应用的配置项，如数据库连接字符串、API 密钥、缓存配置等。
  • 可以使用 tornado.options 来管理不同环境的配置。

static/ - 静态文件目录

• 存放所有不需要由服务器动态处理的文件。
• Tornado 会自动处理对该目录下文件的请求。
• CSS (/static/css/style.css): 页面样式。
• JavaScript (/static/js/main.js): 前端交互逻辑。
• Images (/static/images/logo.png): 图片资源。
• 在模板中，可以通过 {{ static_url("path/to/file") }} 来获取文件的 URL，Tornado 会自动为文件名添加哈希值,便于浏览器缓存管理。

templates/ - 模板目录

• 存放 HTML 文件。

• Tornado 的模板引擎支持继承，base.html 通常定义了 <html>, <head>, <body> 等公共结构，并通过 {% block content %} 定义内容块。

• 其他页面（如 index.html）可以继承 base.html 并填充自己的内容。

  • 示例 (templates/base.html):

    <!DOCTYPE html>
    <html>
    <head>
        <title>{% block title %}My App{% end %}</title>
        <link href="{{ static_url("css/style.css") }}" rel="stylesheet" />
    </head>
    <body>
        <nav>...</nav>
        {% block content %}{% end %}
        <script src="{{ static_url("js/main.js") }}"></script>
    </body>
    </html>

  • 示例 (templates/index.html):

    {% extends "base.html" %}
    {% block title %}Home Page{% end %}
    {% block content %}
        <h1>Welcome, {{ user.name }}!</h1>
    {% end %}

tests/ - 测试目录

• 使用 unittest 或 pytest 等框架为你的代码编写单元测试和集成测试。
• test_handlers.py 用于测试请求处理器的行为。
• test_services.py 用于测试业务逻辑层的正确性。

requirements.txt - 依赖管理

• 列出项目所需的所有 Python 包及其版本。
• 使用 pip install -r requirements.txt 来安装所有依赖。
• 示例 (requirements.txt):

  tornado==6.4
  pymongo==4.6.0
  python-dotenv==1.0.0

run.py - 启动脚本

• 一个简单的脚本，用于启动开发服务器。app/__init__.py 就可以充当这个角色。

这个目录结构是一个强大且可扩展的模板，它遵循了关注点分离的原则：

• 路由 (handlers): 只负责 HTTP 请求的接收和响应。
• 业务逻辑 (services): 只负责数据处理和规则判断。
• 表现层 (templates & static): 只负责页面的展示和样式。

将 Tornado 的核心模块与这种清晰的项目结构相结合，可以帮助你构建出健壮、可维护、易于协作的异步 Web 应用。