Tornado入門教程

Overview

FriendFeed是一款使用 Python 編寫的，相對簡單的非阻塞式 Web 服務器。其應用程序使用的 Web 框架看起來有些像 web.py 或者 Google 的 webapp，不過爲了能有效利用非阻塞式服務器環境，這個 Web 框架還包含了一些相關的有用工具和優化。

Tornado 就是我們在 FriendFeed 的 Web 服務器及其常用工具的開源版本。

Tornado 和現在的主流 Web 服務器框架（包括大多數 Python 的框架）有着明顯的區別：它是非阻塞式服務器，而且速度相當快。得利於其非阻塞的方式和對 epoll的運用，Tornado 每秒可以處理數以千計的連接，因此 Tornado 是實時 Web 服務的一個理想框架。我們開發這個 Web 服務器的主要目的就是爲了處理 FriendFeed 的實時功能 ——在 FriendFeed 的應用裏每一個活動用戶都會保持着一個服務器連接。（關於如何擴容服務器，以處理數以千計的客戶端的連接的問題，請參閱 The C10K problem ）

以下是經典的 “Hello, world” 示例：

import tornado.ioloop
import tornado.web

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

application = tornado.web.Application([
    (r"/", MainHandler),
])

if __name__ == "__main__":
    application.listen(8888)
    tornado.ioloop.IOLoop.instance().start()

查看下面的 Tornado 攻略以瞭解更多關於 tornado.web 包的細節。

我們清理了 Tornado 的基礎代碼，減少了各模塊之間的相互依存關係，所以理論上講，你可以在自己的項目中獨立地使用任何模塊，而不需要使用整個包。

下載和安裝

自動安裝： Tornado 已經列入 PyPI ，因此可以通過 pip 或者 easy_install 來安裝。如果你沒有安裝 libcurl 的話，你需要將其單獨安裝到系統中。請參見下面的安裝依賴一節。注意一點，使用 pip 或 easy_install 安裝的 Tornado 並沒有包含源代碼中的 demo 程序。

手動安裝： 下載 tornado-2.0.tar.gz

tar xvzf tornado-2.0.tar.gz
cd tornado-2.0
python setup.py build
sudo python setup.py install

Tornado 的代碼託管在 GitHub 上面。對於 Python 2.6 以上的版本，因爲標準庫中已經包括了對 epoll 的支持，所以你可以不用 setup.py 編譯安裝，只要簡單地將 tornado 的目錄添加到 PYTHONPATH 就可以使用了。

安裝需求

Tornado 在 Python 2.5, 2.6, 2.7 中都經過了測試。要使用 Tornado 的所有功能，你需要安裝 PycURL (7.18.2 或更高版本) 以及 simplejson (僅適用於Python 2.5，2.6 以後的版本標準庫當中已經包含了對 JSON 的支持)。爲方便起見，下面將列出 Mac OS X 和 Ubuntu 中的完整安裝方式：

Mac OS X 10.6 (Python 2.6+)

sudo easy_install setuptools pycurl

Ubuntu Linux (Python 2.6+)

sudo apt-get install python-pycurl

Ubuntu Linux (Python 2.5)

sudo apt-get install python-dev python-pycurl python-simplejson

模塊索引

最重要的一個模塊是web，它就是包含了 Tornado 的大部分主要功能的 Web 框架。其它的模塊都是工具性質的，以便讓 web 模塊更加有用後面的 Tornado 攻略詳細講解了 web 模塊的使用方法。

主要模塊

web - FriendFeed 使用的基礎 Web 框架，包含了 Tornado 的大多數重要的功能
escape - XHTML, JSON, URL 的編碼/解碼方法
database - 對 MySQLdb 的簡單封裝，使其更容易使用
template - 基於 Python 的 web 模板系統
httpclient - 非阻塞式 HTTP 客戶端，它被設計用來和 web 及 httpserver 協同工作
auth - 第三方認證的實現（包括 Google OpenID/OAuth、Facebook Platform、Yahoo BBAuth、FriendFeed OpenID/OAuth、Twitter OAuth）
locale - 針對本地化和翻譯的支持
options - 命令行和配置文件解析工具，針對服務器環境做了優化

底層模塊

httpserver - 服務於 web 模塊的一個非常簡單的 HTTP 服務器的實現
iostream - 對非阻塞式的 socket 的簡單封裝，以方便常用讀寫操作
ioloop - 核心的 I/O 循環

Tornado 攻略

請求處理程序和請求參數

Tornado 的 Web 程序會將 URL 或者 URL 範式映射到 tornado.web.RequestHandler 的子類上去。在其子類中定義了get() 或 post() 方法，用以處理不同的 HTTP 請求。

下面的代碼將 URL 根目錄 / 映射到 MainHandler，還將一個 URL 範式 /story/([0-9]+) 映射到 StoryHandler。正則表達式匹配的分組會作爲參數引入的相應方法中：

class MainHandler(tornado.web.RequestHandler):
    def get(self):
        self.write("You requested the main page")

class StoryHandler(tornado.web.RequestHandler):
    def get(self, story_id):
        self.write("You requested the story " + story_id)

application = tornado.web.Application([
    (r"/", MainHandler),
    (r"/story/([0-9]+)", StoryHandler),
])

你可以使用 get_argument() 方法來獲取查詢字符串參數，以及解析 POST 的內容：

class MainHandler(tornado.web.RequestHandler):
    def get(self):
        self.write('<html><body><form action="/" method="post">'
                   '<input type="text" name="message">'
                   '<input type="submit" value="Submit">'
                   '</form></body></html>')

    def post(self):
        self.set_header("Content-Type", "text/plain")
        self.write("You wrote " + self.get_argument("message"))

上傳的文件可以通過 self.request.files 訪問到，該對象將名稱（HTML元素 <input type="file">的 name 屬性）對應到一個文件列表。每一個文件都以字典的形式存在，其格式爲 {"filename":..., "content_type":..., "body":...}。

如果你想要返回一個錯誤信息給客戶端，例如“403 unauthorized”，只需要拋出一個 tornado.web.HTTPError 異常：

if not self.user_is_logged_in():
    raise tornado.web.HTTPError(403)

請求處理程序可以通過 self.request 訪問到代表當前請求的對象。該 HTTPRequest 對象包含了一些有用的屬性，包括：

arguments - 所有的 GET 或 POST 的參數
files - 所有通過 multipart/form-data POST 請求上傳的文件
path - 請求的路徑（ ? 之前的所有內容）
headers - 請求的開頭信息

你可以通過查看源代碼 httpserver 模組中 HTTPRequest 的定義，從而瞭解到它的所有屬性。

重寫 RequestHandler 的方法函數

除了 get()/post()等以外，RequestHandler 中的一些別的方法函數，這都是一些空函數，它們存在的目的是在必要時在子類中重新定義其內容。對於一個請求的處理的代碼調用次序如下：

程序爲每一個請求創建一個 RequestHandler 對象
程序調用 initialize() 函數，這個函數的參數是 Application 配置中的關鍵字參數定義。（initialize 方法是 Tornado 1.1 中新添加的，舊版本中你需要重寫 __init__ 以達到同樣的目的） initialize 方法一般只是把傳入的參數存到成員變量中，而不會產生一些輸出或者調用像 send_error 之類的方法。
程序調用 prepare()。無論使用了哪種 HTTP 方法，prepare 都會被調用到，因此這個方法通常會被定義在一個基類中，然後在子類中重用。prepare可以產生輸出信息。如果它調用了finish（或send_error` 等函數），那麼整個處理流程就此結束。
程序調用某個 HTTP 方法：例如 get()、post()、put() 等。如果 URL 的正則表達式模式中有分組匹配，那麼相關匹配會作爲參數傳入方法。

下面是一個示範 initialize() 方法的例子：

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

    def get(self, username):
        ...

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

其它設計用來被複寫的方法有：

get_error_html(self, status_code, exception=None, **kwargs) - 以字符串的形式返回 HTML，以供錯誤頁面使用。
get_current_user(self) - 查看下面的用戶認證一節
get_user_locale(self) - 返回 locale 對象，以供當前用戶使用。
get_login_url(self) - 返回登錄網址，以供 @authenticated 裝飾器使用（默認位置在 Application 設置中）
get_template_path(self) - 返回模板文件的路徑（默認是 Application 中的設置）

重定向(redirect)

Tornado 中的重定向有兩種主要方法：self.redirect，或者使用 RedirectHandler。

你可以在使用 RequestHandler （例如 get）的方法中使用 self.redirect，將用戶重定向到別的地方。另外還有一個可選參數 permanent，你可以用它指定這次操作爲永久性重定向。

該參數會激發一個 301 Moved Permanently HTTP 狀態，這在某些情況下是有用的，例如，你要將頁面的原始鏈接重定向時，這種方式會更有利於搜索引擎優化（SEO）。

permanent 的默認值是 False，這是爲了適用於常見的操作，例如用戶端在成功發送 POST 請求以後的重定向。

self.redirect('/some-canonical-page', permanent=True)

RedirectHandler 會在你初始化 Application 時自動生成。

例如本站的下載 URL，由較短的 URL 重定向到較長的 URL 的方式是這樣的：

application = tornado.wsgi.WSGIApplication([
    (r"/([a-z]*)", ContentHandler),
    (r"/static/tornado-0.2.tar.gz", tornado.web.RedirectHandler,
     dict(url="http://github.com/downloads/facebook/tornado/tornado-0.2.tar.gz")),
], **settings)

RedirectHandler 的默認狀態碼是 301 Moved Permanently，不過如果你想使用 302 Found 狀態碼，你需要將permanent 設置爲 False。

application = tornado.wsgi.WSGIApplication([
    (r"/foo", tornado.web.RedirectHandler, {"url":"/bar", "permanent":False}),
], **settings)

注意，在 self.redirect 和 RedirectHandler 中，permanent 的默認值是不同的。這樣做是有一定道理的，self.redirect 通常會被用在自定義方法中，是由邏輯事件觸發的（例如環境變更、用戶認證、以及表單提交）。而 RedirectHandler 是在每次匹配到請求 URL 時被觸發。

模板

你可以在 Tornado 中使用任何一種 Python 支持的模板語言。但是相較於其它模板而言， Tornado 自帶的模板系統速度更快，並且也更靈活。具體可以查看 template 模塊的源碼。

Tornado 模板其實就是 HTML 文件（也可以是任何文本格式的文件），其中包含了 Python 控制結構和表達式，這些控制結構和表達式需要放在規定的格式標記符(markup)中：

<html>
   <head>
      <title>{{ title }}</title>
   </head>
   <body>
     <ul>
       {% for item in items %}
         <li>{{ escape(item) }}</li>
       {% end %}
     </ul>
   </body>
 </html>

如果你把上面的代碼命名爲 "template.html"，保存在 Python 代碼的同一目錄中，你就可以這樣來渲染它：

class MainHandler(tornado.web.RequestHandler):
    def get(self):
        items = ["Item 1", "Item 2", "Item 3"]
        self.render("template.html", title="My title", items=items)

Tornado 的模板支持“控制語句”和“表達語句”，控制語句是使用 {% 和 %} 包起來的例如 {% if len(items) > 2 %}。表達語句是使用 {{ 和 }} 包起來的，例如 {{ items[0] }}。

控制語句和對應的 Python 語句的格式基本完全相同。我們支持 if、for、while 和 try，這些語句邏輯結束的位置需要用 {% end %} 做標記。我們還通過 extends 和 block 語句實現了模板繼承。這些在 template 模塊的代碼文檔中有着詳細的描述。

表達語句可以是包括函數調用在內的任何 Python 表述。模板中的相關代碼，會在一個單獨的名字空間中被執行，這個名字空間包括了以下的一些對象和方法。（注意，下面列表中的對象或方法在使用 RequestHandler.render 或者render_string 時才存在的，如果你在 RequestHandler 外面直接使用 template 模塊，則它們中的大部分是不存在的）。

escape: tornado.escape.xhtml_escape 的別名
xhtml_escape: tornado.escape.xhtml_escape 的別名
url_escape: tornado.escape.url_escape 的別名
json_encode: tornado.escape.json_encode 的別名
squeeze: tornado.escape.squeeze 的別名
linkify: tornado.escape.linkify 的別名
datetime: Python 的 datetime 模組
handler: 當前的 RequestHandler 對象
request: handler.request 的別名
current_user: handler.current_user 的別名
locale: handler.locale 的別名
_: handler.locale.translate 的別名
static_url: for handler.static_url 的別名
xsrf_form_html: handler.xsrf_form_html 的別名
reverse_url: Application.reverse_url 的別名
Application 設置中 ui_methods 和 ui_modules 下面的所有項目
任何傳遞給 render 或者 render_string 的關鍵字參數

當你製作一個實際應用時，你會需要用到 Tornado 模板的所有功能，尤其是模板繼承功能。所有這些功能都可以在template 模塊的代碼文檔中瞭解到。（其中一些功能是在 web 模塊中實現的，例如 UIModules）

從實現方式來講，Tornado 的模板會被直接轉成 Python 代碼。模板中的語句會逐字複製到一個代表模板的函數中去。我們不會對模板有任何限制，Tornado 模板模塊的設計宗旨就是要比其他模板系統更靈活而且限制更少。所以，當你的模板語句裏發生了隨機的錯誤，在執行模板時你就會看到隨機的 Python 錯誤信息。

所有的模板輸出都已經通過 tornado.escape.xhtml_escape 自動轉義(escape)，這種默認行爲，可以通過以下幾種方式修改：將 autoescape=None 傳遞給 Application 或者 TemplateLoader、在模板文件中加入 {% autoescape None %}、或者在簡單表達語句 {{ ... }} 寫成 {% raw ...%}。另外你可以在上述位置將 autoescape 設爲一個自定義函數，而不僅僅是 None。

你可以使用 set_cookie 方法在用戶的瀏覽中設置 cookie：

class MainHandler(tornado.web.RequestHandler):
    def get(self):
        if not self.get_cookie("mycookie"):
            self.set_cookie("mycookie", "myvalue")
            self.write("Your cookie was not set yet!")
        else:
            self.write("Your cookie was set!")

Cookie 很容易被惡意的客戶端僞造。加入你想在 cookie 中保存當前登陸用戶的 id 之類的信息，你需要對 cookie 作簽名以防止僞造。Tornado 通過 set_secure_cookie 和 get_secure_cookie 方法直接支持了這種功能。要使用這些方法，你需要在創建應用時提供一個密鑰，名字爲 cookie_secret。你可以把它作爲一個關鍵詞參數傳入應用的設置中：

application = tornado.web.Application([
    (r"/", MainHandler),
], cookie_secret="61oETzKXQAGaYdkL5gEmGeJJFuYh7EQnp2XdTP1o/Vo=")

簽名過的 cookie 中包含了編碼過的 cookie 值，另外還有一個時間戳和一個 HMAC 簽名。如果 cookie 已經過期或者簽名不匹配，get_secure_cookie 將返回 None，這和沒有設置 cookie 時的返回值是一樣的。上面例子的安全 cookie 版本如下：

class MainHandler(tornado.web.RequestHandler):
    def get(self):
        if not self.get_secure_cookie("mycookie"):
            self.set_secure_cookie("mycookie", "myvalue")
            self.write("Your cookie was not set yet!")
        else:
            self.write("Your cookie was set!")

用戶認證

當前已經認證的用戶信息被保存在每一個請求處理器的 self.current_user 當中，同時在模板的 current_user 中也是。默認情況下，current_user 爲 None。

要在應用程序實現用戶認證的功能，你需要複寫請求處理中 get_current_user() 這個方法，在其中判定當前用戶的狀態，比如通過 cookie。下面的例子讓用戶簡單地使用一個 nickname 登陸應用，該登陸信息將被保存到 cookie 中：

class BaseHandler(tornado.web.RequestHandler):
    def get_current_user(self):
        return self.get_secure_cookie("user")

class MainHandler(BaseHandler):
    def get(self):
        if not self.current_user:
            self.redirect("/login")
            return
        name = tornado.escape.xhtml_escape(self.current_user)
        self.write("Hello, " + name)

class LoginHandler(BaseHandler):
    def get(self):
        self.write('<html><body><form action="/login" method="post">'
                   'Name: <input type="text" name="name">'
                   '<input type="submit" value="Sign in">'
                   '</form></body></html>')

    def post(self):
        self.set_secure_cookie("user", self.get_argument("name"))
        self.redirect("/")

application = tornado.web.Application([
    (r"/", MainHandler),
    (r"/login", LoginHandler),
], cookie_secret="61oETzKXQAGaYdkL5gEmGeJJFuYh7EQnp2XdTP1o/Vo=")

對於那些必須要求用戶登陸的操作，可以使用裝飾器 tornado.web.authenticated。如果一個方法套上了這個裝飾器，但是當前用戶並沒有登陸的話，頁面會被重定向到 login_url（應用配置中的一個選項），上面的例子可以被改寫成：

class MainHandler(BaseHandler):
    @tornado.web.authenticated
    def get(self):
        name = tornado.escape.xhtml_escape(self.current_user)
        self.write("Hello, " + name)

settings = {
    "cookie_secret": "61oETzKXQAGaYdkL5gEmGeJJFuYh7EQnp2XdTP1o/Vo=",
    "login_url": "/login",
}
application = tornado.web.Application([
    (r"/", MainHandler),
    (r"/login", LoginHandler),
], **settings)

如果你使用 authenticated 裝飾器來裝飾 post() 方法，那麼在用戶沒有登陸的狀態下，服務器會返回 403 錯誤。

Tornado 內部集成了對第三方認證形式的支持，比如 Google 的 OAuth 。參閱 auth 模塊的代碼文檔以瞭解更多信息。 for more details. Checkauth 模塊以瞭解更多的細節。在 Tornado 的源碼中有一個 Blog 的例子，你也可以從那裏看到用戶認證的方法（以及如何在 MySQL 數據庫中保存用戶數據）。

跨站僞造請求的防範

跨站僞造請求(Cross-site request forgery)，簡稱爲 XSRF，是個性化 Web 應用中常見的一個安全問題。前面的鏈接也詳細講述了 XSRF 攻擊的實現方式。

當前防範 XSRF 的一種通用的方法，是對每一個用戶都記錄一個無法預知的 cookie 數據，然後要求所有提交的請求中都必須帶有這個 cookie 數據。如果此數據不匹配，那麼這個請求就可能是被僞造的。

Tornado 有內建的 XSRF 的防範機制，要使用此機制，你需要在應用配置中加上 xsrf_cookies 設定：

settings = {
    "cookie_secret": "61oETzKXQAGaYdkL5gEmGeJJFuYh7EQnp2XdTP1o/Vo=",
    "login_url": "/login",
    "xsrf_cookies": True,
}
application = tornado.web.Application([
    (r"/", MainHandler),
    (r"/login", LoginHandler),
], **settings)

如果設置了 xsrf_cookies，那麼 Tornado 的 Web 應用將對所有用戶設置一個 _xsrf 的 cookie 值，如果 POST PUTDELET 請求中沒有這個 cookie 值，那麼這個請求會被直接拒絕。如果你開啓了這個機制，那麼在所有被提交的表單中，你都需要加上一個域來提供這個值。你可以通過在模板中使用專門的函數 xsrf_form_html() 來做到這一點：

<form action="/new_message" method="post">
  {{ xsrf_form_html() }}
  <input type="text" name="message"/>
  <input type="submit" value="Post"/>
</form>

如果你提交的是 AJAX 的 POST 請求，你還是需要在每一個請求中通過腳本添加上 _xsrf 這個值。下面是在 FriendFeed 中的 AJAX 的 POST 請求，使用了 jQuery 函數來爲所有請求組東添加 _xsrf 值：

function getCookie(name) {
    var r = document.cookie.match("\\b" + name + "=([^;]*)\\b");
    return r ? r[1] : undefined;
}

jQuery.postJSON = function(url, args, callback) {
    args._xsrf = getCookie("_xsrf");
    $.ajax({url: url, data: $.param(args), dataType: "text", type: "POST",
        success: function(response) {
        callback(eval("(" + response + ")"));
    }});
};

對於 PUT 和 DELETE 請求（以及不使用將 form 內容作爲參數的 POST 請求）來說，你也可以在 HTTP 頭中以 X-XSRFToken 這個參數傳遞 XSRF token。

如果你需要針對每一個請求處理器定製 XSRF 行爲，你可以重寫 RequestHandler.check_xsrf_cookie()。例如你需要使用一個不支持 cookie 的 API，你可以通過將 check_xsrf_cookie() 函數設空來禁用 XSRF 保護機制。然而如果你需要同時支持 cookie 和非 cookie 認證方式，那麼只要當前請求是通過 cookie 進行認證的，你就應該對其使用 XSRF 保護機制，這一點至關重要。

靜態文件和主動式文件緩存

你能通過在應用配置中指定 static_path 選項來提供靜態文件服務：

settings = {
    "static_path": os.path.join(os.path.dirname(__file__), "static"),
    "cookie_secret": "61oETzKXQAGaYdkL5gEmGeJJFuYh7EQnp2XdTP1o/Vo=",
    "login_url": "/login",
    "xsrf_cookies": True,
}
application = tornado.web.Application([
    (r"/", MainHandler),
    (r"/login", LoginHandler),
    (r"/(apple-touch-icon\.png)", tornado.web.StaticFileHandler, dict(path=settings['static_path'])),
], **settings)

這樣配置後，所有以 /static/ 開頭的請求，都會直接訪問到指定的靜態文件目錄，比如 http://localhost:8888/static/foo.png 會從指定的靜態文件目錄中訪問到 foo.png 這個文件。同時 /robots.txt 和/favicon.ico 也是會自動作爲靜態文件處理（即使它們不是以 /static/ 開頭）。

在上述配置中，我們使用 StaticFileHandler 特別指定了讓 Tornado 從根目錄伺服 apple-touch-icon.png 這個文件，儘管它的物理位置還是在靜態文件目錄中。（正則表達式的匹配分組的目的是向 StaticFileHandler 指定所請求的文件名稱，抓取到的分組會以方法參數的形式傳遞給處理器。）通過相同的方式，你也可以從站點的更目錄伺服sitemap.xml 文件。當然，你也可以通過在 HTML 中使用正確的 <link /> 標籤來避免這樣的根目錄文件僞造行爲。

爲了提高性能，在瀏覽器主動緩存靜態文件是個不錯的主意。這樣瀏覽器就不需要發送不必要的 If-Modified-Since和 Etag 請求，從而影響頁面的渲染速度。 Tornado 可以通過內建的“靜態內容分版(static content versioning)”來直接支持這種功能。

要使用這個功能，在模板中就不要直接使用靜態文件的 URL 地址了，你需要在 HTML 中使用 static_url() 這個方法來提供 URL 地址：

<html>
   <head>
      <title>FriendFeed - {{ _("Home") }}</title>
   </head>
   <body>
     <div><img src="{{ static_url("images/logo.png") }}"/></div>
   </body>
 </html>

static_url() 函數會將相對地址轉成一個類似於 /static/images/logo.png?v=aae54 的 URI，v 參數是 logo.png文件的散列值， Tornado 服務器會把它發給瀏覽器，並以此爲依據讓瀏覽器對相關內容做永久緩存。

由於 v 的值是基於文件的內容計算出來的，如果你更新了文件，或者重啓了服務器，那麼就會得到一個新的 v 值，這樣瀏覽器就會請求服務器以獲取新的文件內容。如果文件的內容沒有改變，瀏覽器就會一直使用本地緩存的文件，這樣可以顯著提高頁面的渲染速度。

在生產環境下，你可能會使用nginx這樣的更有利於靜態文件伺服的服務器，你可以將 Tornado 的文件緩存指定到任何靜態文件服務器上面，下面是 FriendFeed 使用的 nginx 的相關配置：

location /static/ {
    root /var/friendfeed/static;
    if ($query_string) {
        expires max;
    }
 }

本地化

不管有沒有登陸，當前用戶的 locale 設置可以通過兩種方式訪問到：請求處理器的 self.locale 對象、以及模板中的locale 值。Locale 的名稱（如 en_US）可以通過 locale.name 這個變量訪問到，你可以使用 locale.translate 來進行本地化翻譯。在模板中，有一個全局方法叫 _()，它的作用就是進行本地化的翻譯。這個翻譯方法有兩種使用形式：

_("Translate this string")

它會基於當前 locale 設置直接進行翻譯，還有一種是：

_("A person liked this", "%(num)d people liked this", len(people)) % {"num": len(people)}

這種形式會根據第三個參數來決定是使用單數或是複數的翻譯。上面的例子中，如果 len(people) 是 1 的話，就使用第一種形式的翻譯，否則，就使用第二種形式的翻譯。

常用的翻譯形式是使用 Python 格式化字符串時的“固定佔位符(placeholder)”語法，（例如上面的 %(num)d），和普通佔位符比起來，固定佔位符的優勢是使用時沒有順序限制。

一個本地化翻譯的模板例子：

<html>
   <head>
      <title>FriendFeed - {{ _("Sign in") }}</title>
   </head>
   <body>
     <form action="{{ request.path }}" method="post">
       <div>{{ _("Username") }} <input type="text" name="username"/></div>
       <div>{{ _("Password") }} <input type="password" name="password"/></div>
       <div><input type="submit" value="{{ _("Sign in") }}"/></div>
       {{ xsrf_form_html() }}
     </form>
   </body>
 </html>

默認情況下，我們通過 Accept-Language 這個頭來判定用戶的 locale，如果沒有，則取 en_US 這個值。如果希望用戶手動設置一個 locale 偏好，可以在處理請求的類中複寫 get_user_locale 方法：

class BaseHandler(tornado.web.RequestHandler):
    def get_current_user(self):
        user_id = self.get_secure_cookie("user")
        if not user_id: return None
        return self.backend.get_user_by_id(user_id)

    def get_user_locale(self):
        if "locale" not in self.current_user.prefs:
            # Use the Accept-Language header
            return None
        return self.current_user.prefs["locale"]

如果 get_user_locale 返回 None，那麼就會再去取 Accept-Language header 的值。

你可以使用 tornado.locale.load_translations 方法獲取應用中的所有已存在的翻譯。它會找到包含有特定名字的 CSV 文件的目錄，如 es_GT.csv fr_CA.csv 這些 csv 文件。然後從這些 CSV 文件中讀取出所有的與特定語言相關的翻譯內容。典型的用例裏面，我們會在 Tornado 服務器的 main() 方法中調用一次該函數：

def main():
    tornado.locale.load_translations(
        os.path.join(os.path.dirname(__file__), "translations"))
    start_server()

你可以使用 tornado.locale.get_supported_locales() 方法得到支持的 locale 列表。Tornado 會依據用戶當前的 locale 設置以及已有的翻譯，爲用戶選擇一個最佳匹配的顯示語言。比如，用戶的 locale 是 es_GT 而翻譯中只支持了es，那麼 self.locale 就會被設置爲 es。如果找不到最接近的 locale 匹配，self.locale 就會就會取備用值 es_US。

查看 locale 模塊的代碼文檔以瞭解 CSV 文件的格式，以及其它的本地化方法函數。

UI 模塊

Tornado 支持一些 UI 模塊，它們可以幫你創建標準的，易被重用的應用程序級的 UI 組件。這些 UI 模塊就跟特殊的函數調用一樣，可以用來渲染頁面組件，而這些組件可以有自己的 CSS 和 JavaScript。

例如你正在寫一個博客的應用，你希望在首頁和單篇文章的頁面都顯示文章列表，你可以創建一個叫做 Entry 的 UI 模塊，讓他在兩個地方分別顯示出來。首選需要爲你的 UI 模塊創建一個 Python 模組文件，就叫 uimodules.py 好了:

class Entry(tornado.web.UIModule):
    def render(self, entry, show_comments=False):
        return self.render_string(
            "module-entry.html", entry=entry, show_comments=show_comments)

然後通過 ui_modules 配置項告訴 Tornado 在應用當中使用 uimodules.py：

class HomeHandler(tornado.web.RequestHandler):
    def get(self):
        entries = self.db.query("SELECT * FROM entries ORDER BY date DESC")
        self.render("home.html", entries=entries)

class EntryHandler(tornado.web.RequestHandler):
    def get(self, entry_id):
        entry = self.db.get("SELECT * FROM entries WHERE id = %s", entry_id)
        if not entry: raise tornado.web.HTTPError(404)
        self.render("entry.html", entry=entry)

settings = {
    "ui_modules": uimodules,
}
application = tornado.web.Application([
    (r"/", HomeHandler),
    (r"/entry/([0-9]+)", EntryHandler),
], **settings)

在 home.html 中，你不需要寫繁複的 HTML 代碼，只要引用 Entry 就可以了：

{% for entry in entries %}
  {% module Entry(entry) %}
{% end %}

在 entry.html 裏面，你需要使用 show_comments 參數來引用 Entry 模塊，用來顯示展開的 Entry 內容：

{% module Entry(entry, show_comments=True) %}

你可以爲 UI 模型配置自己的 CSS 和 JavaScript ，只要複寫 embedded_css、embedded_javascript、javascipt_files、css_files 就可以了：

class Entry(tornado.web.UIModule):
    def embedded_css(self):
        return ".entry { margin-bottom: 1em; }"

    def render(self, entry, show_comments=False):
        return self.render_string(
            "module-entry.html", show_comments=show_comments)

即使一頁中有多個相同的 UI 組件，UI 組件的 CSS 和 JavaScript 部分只會被渲染一次。 CSS 是在頁面的 <head> 部分，而 JavaScript 被渲染在頁面結尾 </body> 之前的位置。

在不需要額外 Python 代碼的情況下，模板文件也可以當做 UI 模塊直接使用。例如前面的例子可以以下面的方式實現，只要把這幾行放到 module-entry.html 中就可以了：

{{ set_resources(embedded_css=".entry { margin-bottom: 1em; }") }}
<!-- more template html... -->

這個修改過的模塊式模板可以通過下面的方法調用：

{% module Template("module-entry.html", show_comments=True) %}

set_resources 函數只能在 {% module Template(...) %} 調用的模板中訪問到。和 {% include ... %} 不同，模塊式模板使用了和它們的上級模板不同的命名空間——它們只能訪問到全局模板命名空間和它們自己的關鍵字參數。

非阻塞式異步請求

當一個處理請求的行爲被執行之後，這個請求會自動地結束。因爲 Tornado 當中使用了一種非阻塞式的 I/O 模型，所以你可以改變這種默認的處理行爲——讓一個請求一直保持連接狀態，而不是馬上返回，直到一個主處理行爲返回。要實現這種處理方式，只需要使用 tornado.web.asynchronous 裝飾器就可以了。

使用了這個裝飾器之後，你必須調用 self.finish() 以完成 HTTP 請求，否則用戶的瀏覽器會一直處於等待服務器響應的狀態：

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

下面是一個使用 Tornado 內置的異步請求 HTTP 客戶端去調用 FriendFeed 的 API 的例子：

class MainHandler(tornado.web.RequestHandler):
    @tornado.web.asynchronous
    def get(self):
        http = tornado.httpclient.AsyncHTTPClient()
        http.fetch("http://friendfeed-api.com/v2/feed/bret",
                   callback=self.on_response)

    def on_response(self, response):
        if response.error: raise tornado.web.HTTPError(500)
        json = tornado.escape.json_decode(response.body)
        self.write("Fetched " + str(len(json["entries"])) + " entries "
                   "from the FriendFeed API")
        self.finish()

例子中，當 get() 方法返回時，請求處理還沒有完成。在 HTTP 客戶端執行它的回調函數 on_response() 時，從瀏覽器過來的請求仍然是存在的，只有在顯式調用了 self.finish() 之後，纔會把響應返回到瀏覽器。

關於更多異步請求的高級例子，可以參閱 demo 中的 chat 這個例子。它是一個使用 long polling 方式的 AJAX 聊天室。如果你使用到了 long polling，你可能需要複寫on_connection_close()，這樣你可以在客戶連接關閉以後做相關的清理動作。（請查看該方法的代碼文檔，以防誤用。）

異步 HTTP 客戶端

Tornado 包含了兩種非阻塞式 HTTP 客戶端實現：

SimpleAsyncHTTPClient 和 CurlAsyncHTTPClient。

前者是直接基於 IOLoop 實現的，因此無需外部依賴關係。

後者作爲 Curl 客戶端，需要安裝 libcurl 和 pycurl 後才能正常工作，但是對於使用到 HTTP 規範中一些不常用內容的站點來說，它的兼容性會更好。爲防止碰到舊版本中異步界面的 bug，我們建議你安裝最近的版本的 libcurl 和 pycurl。

這些客戶端都有它們自己的模組(tornado.simple_httpclient 和 tornado.curl_httpclient)，你可以通過tornado.httpclient 來指定使用哪一種客戶端，默認情況下使用的是 SimpleAsyncHTTPClient，如果要修改默認值，只要在一開始調用 AsyncHTTPClient.configure 方法即可：

AsyncHTTPClient.configure('tornado.curl_httpclient.CurlAsyncHTTPClient')

第三方認證

Tornado 的 auth 模塊實現了現在很多流行站點的用戶認證方式，包括 Google/Gmail、Facebook、Twitter、Yahoo 以及 FriendFeed。這個模塊可以讓用戶使用這些站點的賬戶來登陸你自己的應用，然後你就可以在授權的條件下訪問原站點的一些服務，比如下載用戶的地址薄，在 Twitter 上發推等。

下面的例子使用了 Google 的賬戶認證，Google 賬戶的身份被保存到 cookie 當中，以便以後的訪問使用：

class GoogleHandler(tornado.web.RequestHandler, tornado.auth.GoogleMixin):
    @tornado.web.asynchronous
    def get(self):
        if self.get_argument("openid.mode", None):
            self.get_authenticated_user(self._on_auth)
            return
        self.authenticate_redirect()

    def _on_auth(self, user):
        if not user:
            self.authenticate_redirect()
            return
        # Save the user with, e.g., set_secure_cookie()

請查看 auth 模塊的代碼文檔以瞭解更多的細節。

調試模式和自動重載

如果你將 debug=True 傳遞給 Application 構造器，該 app 將以調試模式運行。在調試模式下，模板將不會被緩存，而這個 app 會監視代碼文件的修改，如果發現修改動作，這個 app 就會被重新加載。在開發過程中，這會大大減少手動重啓服務的次數。然而有些問題（例如 import 時的語法錯誤）還是會讓服務器下線，目前的 debug 模式還無法避免這些情況。

調試模式和 HTTPServer 的多進程模式不兼容。在調試模式下，你必須將 HTTPServer.start 的參數設爲不大於 1 的數字。

調試模式下的自動重載功能可以通過獨立的模塊 tornado.autoreload 調用，作爲測試運行器的一個可選項目，tornado.testing.main 中也有用到它。

性能

一個 Web 應用的性能表現，主要看它的整體架構，而不僅僅是前端的表現。和其它的 Python Web 框架相比，Tornado 的速度要快很多。

我們在一些流行的 Python Web 框架上（Django、 web.py、CherryPy），針對最簡單的 Hello, world 例子作了一個測試。對於 Django 和 web.py，我們使用 Apache/mod_wsgi 的方式來帶，CherryPy 就讓它自己裸跑。這也是在生產環境中各框架常用的部署方案。對於我們的 Tornado，使用的部署方案爲前端使用 nginx 做反向代理，帶動 4 個線程模式的 Tornado，這種方案也是我們推薦的在生產環境下的 Tornado 部署方案（根據具體的硬件情況，我們推薦一個 CPU 覈對應一個 Tornado 伺服實例，我們的負載測試使用的是四核處理器）。

我們使用 Apache Benchmark (ab)，在另外一臺機器上使用瞭如下指令進行負載測試：

ab -n 100000 -c 25 http://10.0.1.x/

在 AMD Opteron 2.4GHz 的四核機器上，結果如下圖所示：

在我們的測試當中，相較於第二快的服務器，Tornado 在數據上的表現也是它的 4 倍之多。即使只用了一個 CPU 核的裸跑模式，Tornado 也有 33% 的優勢。

這個測試不見得非常科學，不過從大體上你可以看出，我們開發 Tornado 時對於性能的注重程度。和其他的 Python Web 開發框架相比，它不會爲你帶來多少延時。

生產環境下的部署

在 FriendFeed 中，我們使用 nginx 做負載均衡和靜態文件伺服。我們在多臺服務器上，同時部署了多個 Tornado 實例，通常，一個 CPU 內核會對應一個 Tornado 線程。

因爲我們的 Web 服務器是跑在負載均衡服務器（如 nginx）後面的，所以需要把 xheaders=True 傳到 HTTPServer 的構造器當中去。這是爲了讓 Tornado 使用 X-Real-IP 這樣的的 header 信息來獲取用戶的真實 IP地址，如果使用傳統的方法，你只能得到這臺負載均衡服務器的 IP 地址。

下面是 nginx 配置文件的一個示例，整體上與我們在 FriendFeed 中使用的差不多。它假設 nginx 和 Tornado 是跑在同一臺機器上的，四個 Tornado 服務跑在 8000-8003 端口上：

user nginx;
worker_processes 1;

error_log /var/log/nginx/error.log;
pid /var/run/nginx.pid;

events {
    worker_connections 1024;
    use epoll;
}

http {
    # Enumerate all the Tornado servers here
    upstream frontends {
        server 127.0.0.1:8000;
        server 127.0.0.1:8001;
        server 127.0.0.1:8002;
        server 127.0.0.1:8003;
    }

    include /etc/nginx/mime.types;
    default_type application/octet-stream;

    access_log /var/log/nginx/access.log;

    keepalive_timeout 65;
    proxy_read_timeout 200;
    sendfile on;
    tcp_nopush on;
    tcp_nodelay on;
    gzip on;
    gzip_min_length 1000;
    gzip_proxied any;
    gzip_types text/plain text/html text/css text/xml
               application/x-javascript application/xml
               application/atom+xml text/javascript;

    # Only retry if there was a communication error, not a timeout
    # on the Tornado server (to avoid propagating "queries of death"
    # to all frontends)
    proxy_next_upstream error;

    server {
        listen 80;

        # Allow file uploads
        client_max_body_size 50M;

        location ^~ /static/ {
            root /var/www;
            if ($query_string) {
                expires max;
            }
        }
        location = /favicon.ico {
            rewrite (.*) /static/favicon.ico;
        }
        location = /robots.txt {
            rewrite (.*) /static/robots.txt;
        }

        location / {
            proxy_pass_header Server;
            proxy_set_header Host $http_host;
            proxy_redirect false;
            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header X-Scheme $scheme;
            proxy_pass http://frontends;
        }
    }
}

WSGI 和 Google AppEngine

Tornado 對 WSGI 只提供了有限的支持，即使如此，因爲 WSGI 並不支持非阻塞式的請求，所以如果你使用 WSGI 代替 Tornado 自己的 HTTP 服務的話，那麼你將無法使用 Tornado 的異步非阻塞式的請求處理方式。比如@tornado.web.asynchronous、httpclient 模塊、auth 模塊，這些將都無法使用。

你可以通過 wsgi 模塊中的 WSGIApplication 創建一個有效的 WSGI 應用（區別於我們用過的tornado.web.Application）。下面的例子展示了使用內置的 WSGI CGIHandler 來創建一個有效的 Google AppEngine 應用。

import tornado.web
import tornado.wsgi
import wsgiref.handlers

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

if __name__ == "__main__":
    application = tornado.wsgi.WSGIApplication([
        (r"/", MainHandler),
    ])
    wsgiref.handlers.CGIHandler().run(application)

請查看 demo 中的 appengine 範例，它是一個基於 Tornado 的完整的 AppEngine 應用。

注意事項和社區支持

因爲 FriendFeed 以及其他 Tornado 的主要用戶在使用時都是基於 nginx或者 Apache 代理之後的。所以現在 Tornado 的 HTTP 服務部分並不完整，它無法處理多行的 header 信息，同時對於一些非標準的輸入也無能爲力。

你可以在 Tornado 開發者郵件列表中討論和提交 bug。

Tornado入門教程

Overview

下載和安裝

安裝需求

模塊索引

主要模塊

底層模塊

Tornado 攻略

請求處理程序和請求參數

重寫 RequestHandler 的方法函數

重定向(redirect)

模板

用戶認證

跨站僞造請求的防範

靜態文件和主動式文件緩存

本地化

UI 模塊

非阻塞式異步請求

異步 HTTP 客戶端

第三方認證

調試模式和自動重載

性能

生產環境下的部署

WSGI 和 Google AppEngine

注意事項和社區支持

Tornado入門教程

asp.net webapi 的Request如何獲取參數

Python製作Windows系統服務

python(十二)下：ORM框架SQLAlchemy使用學習

Tornado異步筆記（一）--- 異步任務

https://yachay.unat.edu.pe/blog/index.php?comment_area=format_blog&comment_component=blog&comment_co

linux以太網驅動總結

Tornado入門教程

Overview

下載和安裝

安裝需求

模塊索引

主要模塊

底層模塊

Tornado 攻略

請求處理程序和請求參數

重寫 RequestHandler 的方法函數

重定向(redirect)

模板

Cookie 和安全 Cookie

用戶認證

跨站僞造請求的防範

靜態文件和主動式文件緩存

本地化

UI 模塊

非阻塞式異步請求

異步 HTTP 客戶端

第三方認證

調試模式和自動重載

性能

生產環境下的部署

WSGI 和 Google AppEngine

注意事項和社區支持