tornado 框架2

時間 2019-11-12

原文原文鏈接

轉自 http://sebug.net/paper/books/tornado/javascript

Overview

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

Tornado 就是咱們在 FriendFeed 的 Web 服務器及其經常使用工具的開源版本。Tornado 和如今的主流 Web 服務器框架（包括大多數 Python 的框架）有着明顯的區別：它是非阻塞式服務器，並且速度至關快。得利於其非阻塞的方式和對 epoll的運用，Tornado 每秒能夠處理數以千計的鏈接，所以 Tornado 是實時 Web 服務的一個理想框架。咱們開發這個 Web 服務器的主要目的就是爲了處理 FriendFeed 的實時功能 ——在 FriendFeed 的應用裏每個活動用戶都會保持着一個服務器鏈接。（關於如何擴容服務器，以處理數以千計的客戶端的鏈接的問題，請參閱 The C10K problem ）html

如下是經典的「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 包的細節。java

咱們清理了 Tornado 的基礎代碼，減小了各模塊之間的相互依存關係，因此理論上講，你能夠在本身的項目中獨立地使用任何模塊，而不須要使用整個包。node

下載和安裝

自動安裝： Tornado 已經列入 PyPI ，所以能夠經過 pip 或者 easy_install 來安裝。若是你沒有安裝 libcurl 的話，你須要將其單獨安裝到系統中。請參見下面的安裝依賴一節。注意一點，使用 pip 或 easy_install 安裝的 Tornado 並無包含源代碼中的 demo 程序。python

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

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 就可使用了。ios

安裝需求

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

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。

Cookie 和安全 Cookie

你可使用 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 應用。