Tornado Web 服務器概覽

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 PUT DELET 請求中沒有這個 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() 已完成 HTTTP 請求，否則用戶的瀏覽器會一直處于等待服務器響應的狀態：

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。

概覽