Overview
FriendFeed使用了一款使用 Python 編寫的，相對簡單的 非阻塞式 Web 服務器。其應用程序使用的 Web 框架看起來有些像 web.py 或者 Google 的 webapp， 不過爲了能有效利用非阻塞式服務器環境，這個 Web 框架還包含了一些相關的有用工具 和優化。javascript
Tornado 就是咱們在 FriendFeed 的 Web 服務器及其經常使用工具的開源版本。Tornado 和如今的主流 Web 服務器框架（包括大多數 Python 的框架）有着明顯的區別：它是非阻塞式服務器，並且速度至關快。得利於其 非阻塞的方式和對 epoll的運用，Tornado 每秒能夠處理數以千計的鏈接，所以 Tornado 是實時 Web 服務的一個 理想框架。咱們開發這個 Web 服務器的主要目的就是爲了處理 FriendFeed 的實時功能 ——在 FriendFeed 的應用裏每個活動用戶都會保持着一個服務器鏈接。（關於如何擴容 服務器，以處理數以千計的客戶端的鏈接的問題，請參閱 The C10K problem ）css
如下是經典的 「Hello, world」 示例：html
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 的基礎代碼，減小了各模塊之間的相互依存關係，因此理論上講， 你能夠在本身的項目中獨立地使用任何模塊，而不須要使用整個包。java
下載和安裝
自動安裝： Tornado 已經列入 PyPI ，所以能夠經過 pip 或者 easy_install 來安裝。若是你沒有安裝 libcurl 的話，你須要將其單獨安裝到系統中。請參見下面的安裝依賴一節。注意一點，使用 pip 或 easy_install 安裝的 Tornado 並無包含源代碼中的 demo 程序。node
手動安裝： 下載 tornado-2.0.tar.gzpython
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 就可使用了。jquery
安裝需求
Tornado 在 Python 2.5, 2.6, 2.7 中都通過了測試。要使用 Tornado 的全部功能，你須要安裝 PycURL (7.18.2 或更高版本) 以及 simplejson (僅適用於Python 2.5，2.6 之後的版本標準庫當中已經包含了對 JSON 的支持)。爲方便起見，下面將列出 Mac OS X 和 Ubuntu 中的完整安裝方式：ios
Mac OS X 10.6 (Python 2.6+)nginx
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-dataPOST 請求上傳的文件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: forhandler.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 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() 已完成 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。