百乐千炮捕鱼

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 的話,你需要將其單獨安裝到系統中。請參見下面的安裝依賴一節。注意一點,使用 pipeasy_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 模塊的使用方法。

主要模塊

底層模塊

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 對象包含了一些有用的屬性,包括:

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

重寫 RequestHandler 的方法函數

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

  1. 程序為每一個請求創建一個 RequestHandler 對象
  2. 程序調用 initialize() 函數,這個函數的參數是 Application 配置中的關鍵字 參數定義。(initialize 方法是 Tornado 1.1 中新添加的,舊版本中你需要 重寫 __init__ 以達到同樣的目的) initialize 方法一般只是把傳入的參數存 到成員變量中,而不會產生一些輸出或者調用像 send_error 之類的方法。
  3. 程序調用 prepare()。無論使用了哪種 HTTP 方法,prepare 都會被調用到,因此 這個方法通常會被定義在一個基類中,然后在子類中重用。prepare可以產生輸出 信息。如果它調用了finish(或send_error` 等函數),那么整個處理流程 就此結束。
  4. 程序調用某個 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)),
    ])

其它設計用來被復寫的方法有:

重定向(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.redirectRedirectHandler 中,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 語句的格式基本完全相同。我們支持 ifforwhiletry,這些語句邏輯結束的位置需要用 {% end %} 做標記。我們還通過 extendsblock 語句實現了模板繼承。這些在 template 模塊 的代碼文檔中有著詳細的描述。

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

當你制作一個實際應用時,你會需要用到 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_cookieget_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_userNone

要在應用程序實現用戶認證的功能,你需要復寫請求處理中 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 + ")"));
    }});
};

對于 PUTDELETE 請求(以及不使用將 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-SinceEtag 請求,從而影響頁面的渲染速度。 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_cssembedded_javascriptjavascipt_filescss_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 客戶端實現:SimpleAsyncHTTPClientCurlAsyncHTTPClient。前者是直接基于 IOLoop 實現的,因此無需外部依賴關系。 后者作為 Curl 客戶端,需要安裝 libcurlpycurl 后才能正常工作,但是對于使用 到 HTTP 規范中一些不常用內容的站點來說,它的兼容性會更好。為防止碰到 舊版本中異步界面的 bug,我們建議你安裝最近的版本的 libcurlpycurl

這些客戶端都有它們自己的模組(tornado.simple_httpclienttornado.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 框架上(Djangoweb.pyCherryPy), 針對最簡單的 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.asynchronoushttpclient 模塊、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。

百乐千炮捕鱼 内蒙古十一选五前三直遗漏数据 黑龙江福彩 山东快乐扑克 江西时时彩开了去年号 新疆11选5规律 网球肘针灸 内蒙古11选5官网走势图 007足球指数 九五至尊游戏棋牌平台下载 平特一肖高手论坛