摘要：譯者說(shuō)于年月日發(fā)布，該版本正式支持的關(guān)鍵字，并且用舊版本編譯同樣可以使用這兩個(gè)關(guān)鍵字，這無(wú)疑是一種進(jìn)步。其次，這是最后一個(gè)支持和的版本了，在后續(xù)的版本了會(huì)移除對(duì)它們的兼容。本節(jié)最好直接在或者閱讀，以獲得更好的閱讀體驗(yàn)格式支持。

Tornado 4.3于2015年11月6日發(fā)布，該版本正式支持Python3.5的async/await關(guān)鍵字，并且用舊版本CPython編譯Tornado同樣可以使用這兩個(gè)關(guān)鍵字，這無(wú)疑是一種進(jìn)步。其次，這是最后一個(gè)支持Python2.6和Python3.2的版本了，在后續(xù)的版本了會(huì)移除對(duì)它們的兼容。現(xiàn)在網(wǎng)絡(luò)上還沒(méi)有Tornado4.3的中文文檔，所以為了讓更多的朋友能接觸并學(xué)習(xí)到它，我開(kāi)始了這個(gè)翻譯項(xiàng)目，希望感興趣的小伙伴可以一起參與翻譯，項(xiàng)目地址是tornado-zh on Github，翻譯好的文檔在Read the Docs上直接可以看到。歡迎Issues or PR。

tornado.web 提供了一種帶有異步功能并允許它擴(kuò)展到大量開(kāi)放連接的 簡(jiǎn)單的web 框架, 使其成為處理 長(zhǎng)連接(long polling) 的一種理想選擇.

這里有一個(gè)簡(jiǎn)單的”Hello, world”示例應(yīng)用:

import tornado.ioloop
import tornado.web

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

if __name__ == "__main__":
    application = tornado.web.Application([
        (r"/", MainHandler),
    ])
    application.listen(8888)
    tornado.ioloop.IOLoop.current().start()

查看 用戶(hù)指南 以了解更多信息.

一般情況下, 在 RequestHandler 中的方法和Tornado 中其他的方法不是 線程安全的. 尤其是一些方法, 例如 write(), finish(), 和 flush() 要求只能從 主線程調(diào)用. 如果你使用多線程, 那么在結(jié)束請(qǐng)求之前, 使用 IOLoop.add_callback 來(lái)把控制權(quán)傳送回主線程是很重要的.

HTTP請(qǐng)求處理的基類(lèi).

子類(lèi)至少應(yīng)該定義以下”Entry points” 部分中被定義的方法其中之一.

子類(lèi)初始化(Hook).

作為url spec的第三個(gè)參數(shù)傳遞的字典, 將作為關(guān)鍵字參數(shù)提供給 initialize().

例子:

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

    def get(self, username):
        ...

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

在每個(gè)請(qǐng)求的最開(kāi)始被調(diào)用, 在 get/post/等方法之前.

通過(guò)復(fù)寫(xiě)這個(gè)方法, 可以執(zhí)行共同的初始化, 而不用考慮每個(gè)請(qǐng)求方法.

異步支持: 這個(gè)方法使用 gen.coroutine 或 return_future 裝飾器來(lái)使它異步( asynchronous 裝飾器不能被用在 prepare). 如果這個(gè)方法返回一個(gè) Future 對(duì)象, 執(zhí)行將不再進(jìn)行, 直到 Future 對(duì)象完成.

3.1 新版功能: 異步支持.

在一個(gè)請(qǐng)求結(jié)束后被調(diào)用.

復(fù)寫(xiě)這個(gè)方法來(lái)執(zhí)行清理, 日志記錄等. 這個(gè)方法和 prepare 是相 對(duì)應(yīng)的. on_finish 可能不產(chǎn)生任何輸出, 因?yàn)樗窃陧憫?yīng)被送 到客戶(hù)端后才被調(diào)用.

執(zhí)行后面任何的方法 (統(tǒng)稱(chēng)為HTTP 動(dòng)詞(verb) 方法) 來(lái)處理相應(yīng)的HTTP方法. 這些方法可以通過(guò)使用下面的裝飾器: gen.coroutine, return_future, 或 asynchronous 變成異步.

為了支持不再列表中的方法, 可以復(fù)寫(xiě)類(lèi)變量 SUPPORTED_METHODS:

class WebDAVHandler(RequestHandler):
    SUPPORTED_METHODS = RequestHandler.SUPPORTED_METHODS + ("PROPFIND",)

    def propfind(self):
        pass

返回指定的name參數(shù)的值.

如果沒(méi)有提供默認(rèn)值, 那么這個(gè)參數(shù)將被視為是必須的, 并且當(dāng) 找不到這個(gè)參數(shù)的時(shí)候我們會(huì)拋出一個(gè) MissingArgumentError.

如果一個(gè)參數(shù)在url上出現(xiàn)多次, 我們返回最后一個(gè)值.

返回值永遠(yuǎn)是unicode.

返回指定name的參數(shù)列表.

如果參數(shù)不存在, 返回一個(gè)空列表.

返回值永遠(yuǎn)是unicode.

從請(qǐng)求的query string返回給定name的參數(shù)的值.

如果沒(méi)有提供默認(rèn)值, 這個(gè)參數(shù)將被視為必須的, 并且當(dāng)找不到這個(gè) 參數(shù)的時(shí)候我們會(huì)拋出一個(gè) MissingArgumentError 異常.

如果這個(gè)參數(shù)在url中多次出現(xiàn), 我們將返回最后一次的值.

返回值永遠(yuǎn)是unicode.

3.2 新版功能.

返回指定name的參數(shù)列表.

如果參數(shù)不存在, 將返回空列表.

返回值永遠(yuǎn)是unicode.

3.2 新版功能.

返回請(qǐng)求體中指定name的參數(shù)的值.

如果沒(méi)有提供默認(rèn)值, 那么這個(gè)參數(shù)將被視為是必須的, 并且當(dāng) 找不到這個(gè)參數(shù)的時(shí)候我們會(huì)拋出一個(gè) MissingArgumentError.

如果一個(gè)參數(shù)在url上出現(xiàn)多次, 我們返回最后一個(gè)值.

返回值永遠(yuǎn)是unicode.

3.2 新版功能.

返回由指定請(qǐng)求體中指定name的參數(shù)的列表.

如果參數(shù)不存在, 返回一個(gè)空列表.

返回值永遠(yuǎn)是unicode.

3.2 新版功能.

從請(qǐng)求中解碼一個(gè)參數(shù).

這個(gè)參數(shù)已經(jīng)被解碼現(xiàn)在是一個(gè)字節(jié)字符串(byte string). 默認(rèn)情況下, 這個(gè)方法會(huì)把參數(shù)解碼成utf-8并且返回一個(gè)unicode字符串, 但是它可以 被子類(lèi)復(fù)寫(xiě).

這個(gè)方法既可以在 get_argument() 中被用作過(guò)濾器, 也可以用來(lái)從url 中提取值并傳遞給 get()/post()/等.

如果知道的話(huà)參數(shù)的name會(huì)被提供, 但也可能為None (e.g. 在url正則表達(dá)式中未命名的組).

tornado.httputil.HTTPServerRequest 對(duì)象包含附加的 請(qǐng)求參數(shù)包括e.g. 頭部和body數(shù)據(jù).

path_args 和 path_kwargs 屬性包含傳遞給 HTTP verb methods 的位置和關(guān)鍵字參數(shù). 這些屬性被設(shè)置, 在這些方法被調(diào)用之前, 所以這些值 在 prepare 之間是可用的.

設(shè)置響應(yīng)的狀態(tài)碼.

參數(shù):
status_code (int) – 響應(yīng)狀態(tài)碼. 如果 reason 是 None, 它必須存在于 httplib.responses.
reason (string) – 用人類(lèi)可讀的原因短語(yǔ)來(lái)描述狀態(tài)碼. 如果是 None, 它會(huì)由來(lái)自 httplib.responses 的reason填滿(mǎn).
RequestHandler.set_header(name, value)
給響應(yīng)設(shè)置指定的頭部和對(duì)應(yīng)的值.

如果給定了一個(gè)datetime, 我們會(huì)根據(jù)HTTP規(guī)范自動(dòng)的對(duì)它格式化. 如果值不是一個(gè)字符串, 我們會(huì)把它轉(zhuǎn)換成字符串. 之后所有頭部的值 都將用UTF-8 編碼.

添加指定的響應(yīng)頭和對(duì)應(yīng)的值.

不像是 set_header, add_header 可以被多次調(diào)用來(lái)為相同的頭 返回多個(gè)值.

清除輸出頭, 取消之前的 set_header 調(diào)用.

注意這個(gè)方法不適用于被 add_header 設(shè)置了多個(gè)值的頭.

復(fù)寫(xiě)這個(gè)方法可以在請(qǐng)求開(kāi)始的時(shí)候設(shè)置HTTP頭.

例如, 在這里可以設(shè)置一個(gè)自定義 Server 頭. 注意在一般的 請(qǐng)求過(guò)程流里可能不會(huì)實(shí)現(xiàn)你預(yù)期的效果, 因?yàn)轭^部可能在錯(cuò)誤處 理(error handling)中被重置.

把給定塊寫(xiě)到輸出buffer.

為了把輸出寫(xiě)到網(wǎng)絡(luò), 使用下面的flush()方法.

如果給定的塊是一個(gè)字典, 我們會(huì)把它作為JSON來(lái)寫(xiě)同時(shí)會(huì)把響應(yīng)頭 設(shè)置為 application/json. (如果你寫(xiě)JSON但是設(shè)置不同的 Content-Type, 可以調(diào)用set_header 在調(diào)用write()之后 ).

注意列表不能轉(zhuǎn)換為JSON 因?yàn)橐粋€(gè)潛在的跨域安全漏洞. 所有的JSON 輸出應(yīng)該包在一個(gè)字典中. 更多細(xì)節(jié)參考 http://haacked.com/archive/20... 和 https://github.com/facebook/t...

將當(dāng)前輸出緩沖區(qū)寫(xiě)到網(wǎng)絡(luò).

callback 參數(shù), 如果給定則可用于流控制: 它會(huì)在所有數(shù)據(jù)被寫(xiě)到 socket后執(zhí)行. 注意同一時(shí)間只能有一個(gè)flush callback停留; 如果另 一個(gè)flush在前一個(gè)flush的callback運(yùn)行之前發(fā)生, 那么前一個(gè)callback 將會(huì)被丟棄.

在 4.0 版更改: 現(xiàn)在如果沒(méi)有給定callback, 會(huì)返回一個(gè) Future 對(duì)象.

完成響應(yīng), 結(jié)束HTTP 請(qǐng)求.

使用給定參數(shù)渲染模板并作為響應(yīng).

使用給定的參數(shù)生成指定模板.

我們返回生成的字節(jié)字符串(以u(píng)tf8). 為了生成并寫(xiě)一個(gè)模板 作為響應(yīng), 使用上面的render().

返回一個(gè)字典被用做默認(rèn)的模板命名空間.

可以被子類(lèi)復(fù)寫(xiě)來(lái)添加或修改值.

這個(gè)方法的結(jié)果將與 tornado.template 模塊中其他的默認(rèn)值 還有 render 或 render_string 的關(guān)鍵字參數(shù)相結(jié)合.

重定向到給定的URL(可以選擇相對(duì)路徑).

如果指定了 status 參數(shù), 這個(gè)值將作為HTTP狀態(tài)碼; 否則 將通過(guò) permanent 參數(shù)選擇301 (永久) 或者 302 (臨時(shí)). 默認(rèn)是 302 (臨時(shí)重定向).

給瀏覽器發(fā)送給定的HTTP 錯(cuò)誤碼.

如果 flush() 已經(jīng)被調(diào)用, 它是不可能發(fā)送錯(cuò)誤的, 所以這個(gè)方法將終止 響應(yīng). 如果輸出已經(jīng)被寫(xiě)但尚未flush, 它將被丟棄并被錯(cuò)誤頁(yè)代替.

復(fù)寫(xiě) write_error() 來(lái)自定義它返回的錯(cuò)誤頁(yè). 額外的關(guān)鍵字參數(shù)將 被傳遞給 write_error.

復(fù)寫(xiě)這個(gè)方法來(lái)實(shí)現(xiàn)自定義錯(cuò)誤頁(yè).

write_error 可能調(diào)用 write, render, set_header,等 來(lái)產(chǎn)生一般的輸出.

如果錯(cuò)誤是由未捕獲的異常造成的(包括HTTPError), 三個(gè)一組的 exc_info 將變成可用的通過(guò) kwargs["exc_info"]. 注意這個(gè)異常可能不是”當(dāng)前(current)” 目的或方法的異常就像 sys.exc_info() 或 traceback.format_exc.

重置這個(gè)響應(yīng)的所有頭部和內(nèi)容.

實(shí)現(xiàn)這個(gè)方法來(lái)處理請(qǐng)求數(shù)據(jù)流.

需要 stream_request_body 裝飾器.

self.request.cookies 的別名.

獲取給定name的cookie值, 如果未獲取到則返回默認(rèn)值.

設(shè)置給定的cookie 名稱(chēng)/值還有其他給定的選項(xiàng).

另外的關(guān)鍵字參數(shù)在Cookie.Morsel直接設(shè)置. 參見(jiàn) https://docs.python.org/2/lib... 查看可用的屬性.

刪除給定名稱(chēng)的cookie.

受cookie協(xié)議的限制, 必須傳遞和設(shè)置該名稱(chēng)cookie時(shí)候相同的path 和domain來(lái)清除這個(gè)cookie(但是這里沒(méi)有方法來(lái)找出在服務(wù)端所使 用的該cookie的值).

刪除用戶(hù)在本次請(qǐng)求中所有攜帶的cookie.

查看 clear_cookie 方法來(lái)獲取關(guān)于path和domain參數(shù)的更多信息.

在 3.2 版更改: 添加 path 和 domain 參數(shù).

如果給定的簽名過(guò)的cookie是有效的,則返回，否則返回None.

解碼后的cookie值作為字節(jié)字符串返回(不像 get_cookie ).

在 3.2.1 版更改: 添加 min_version 參數(shù). 引進(jìn)cookie version 2; 默認(rèn)版本 1 和 2 都可以接受.

返回安全cookie(secure cookie)的簽名key版本.

返回的版本號(hào)是int型的.

給cookie簽名和時(shí)間戳以防被偽造.

你必須在你的Application設(shè)置中指定 cookie_secret 來(lái)使用這個(gè)方法. 它應(yīng)該是一個(gè)長(zhǎng)的, 隨機(jī)的字節(jié)序列作為HMAC密鑰來(lái)做簽名.

使用 get_secure_cookie() 方法來(lái)閱讀通過(guò)這個(gè)方法設(shè)置的cookie.

注意 expires_days 參數(shù)設(shè)置cookie在瀏覽器中的有效期, 并且它是 獨(dú)立于 get_secure_cookie 的 max_age_days 參數(shù)的.

安全cookie(Secure cookies)可以包含任意字節(jié)的值, 而不只是unicode 字符串(不像是普通cookie)

在 3.2.1 版更改: 添加 version 參數(shù). 提出cookie version 2 并將它作為默認(rèn)設(shè)置.

產(chǎn)生用時(shí)間戳簽名的字符串, 防止被偽造.

一般通過(guò)set_secure_cookie 使用, 但對(duì)于無(wú)cookie使用來(lái)說(shuō)就 作為獨(dú)立的方法來(lái)提供. 為了解碼不作為cookie存儲(chǔ)的值, 可以 在 get_secure_cookie 使用可選的value參數(shù).

在 3.2.1 版更改: 添加 version 參數(shù). 提出cookie version 2 并將它作為默認(rèn)設(shè)置.

這個(gè)Tornado版本所支持的最舊的簽名值版本.

比這個(gè)簽名值更舊的版本將不能被解碼.

3.2.1 新版功能.

這個(gè)Tornado版本所支持的最新的簽名值版本.

比這個(gè)簽名值更新的版本將不能被解碼.

3.2.1 新版功能.

簽名值版本通過(guò) RequestHandler.create_signed_value 產(chǎn)生.

可通過(guò)傳遞一個(gè) version 關(guān)鍵字參數(shù)復(fù)寫(xiě).

3.2.1 新版功能.

可以被 RequestHandler.get_secure_cookie 接受的最舊的簽名值.

可通過(guò)傳遞一個(gè) min_version 關(guān)鍵字參數(shù)復(fù)寫(xiě).

3.2.1 新版功能.

為請(qǐng)求提供服務(wù)的 Application 對(duì)象

針對(duì)請(qǐng)求的 If-None-Match 頭檢查 Etag 頭.

如果請(qǐng)求的ETag 匹配則返回 True 并將返回一個(gè)304. 例如:

self.set_etag_header()
if self.check_etag_header():
    self.set_status(304)
    return

這個(gè)方法在請(qǐng)求結(jié)束的時(shí)候會(huì)被自動(dòng)調(diào)用, 但也可以被更早的調(diào)用 當(dāng)復(fù)寫(xiě)了 compute_etag 并且想在請(qǐng)求完成之前先做一個(gè) If-None-Match 檢查. Etag 頭應(yīng)該在這個(gè)方法被調(diào)用前設(shè)置 (可以使用 set_etag_header).

確認(rèn) _xsrf cookie匹配 _xsrf 參數(shù).

為了預(yù)防cross-site請(qǐng)求偽造, 我們?cè)O(shè)置一個(gè) _xsrf cookie和包含相同值的一個(gè)non-cookie字段在所有 POST 請(qǐng)求中. 如果這兩個(gè)不匹配, 我們拒絕這個(gè) 表單提交作為一個(gè)潛在的偽造請(qǐng)求.

_xsrf 的值可以被設(shè)置為一個(gè)名為 _xsrf 的表單字段或 在一個(gè)名為 X-XSRFToken 或 X-CSRFToken 的自定義 HTTP頭部(后者被接受為了兼容Django).

查看 http://en.wikipedia.org/wiki/...

發(fā)布1.1.1 之前, 這個(gè)檢查會(huì)被忽略如果當(dāng)前的HTTP頭部是 X-Requested-With: XMLHTTPRequest . 這個(gè)異常已被證明是 不安全的并且已經(jīng)被移除. 更多信息請(qǐng)查看 http://www.djangoproject.com/... http://weblog.rubyonrails.org/2011/2/8/csrf-protection-bypass-in-ruby-on-rails

在 3.2.2 版更改: 添加cookie 2版本的支持. 支持版本1和2.

計(jì)算被用于這個(gè)請(qǐng)求的etag頭.

到目前為止默認(rèn)使用輸出內(nèi)容的hash值.

可以被復(fù)寫(xiě)來(lái)提供自定義的etag實(shí)現(xiàn), 或者可以返回None來(lái)禁止 tornado 默認(rèn)的etag支持.

返回給定路徑的新模板裝載器.

可以被子類(lèi)復(fù)寫(xiě). 默認(rèn)返回一個(gè)在給定路徑上基于目錄的裝載器, 使用應(yīng)用程序的 autoescape 和 template_whitespace 設(shè)置. 如果應(yīng)用設(shè)置中提供了一個(gè) template_loader , 則使用它來(lái)替代.

返回請(qǐng)求中被認(rèn)證的用戶(hù).

可以使用以下兩者之一的方式來(lái)設(shè)置:

子類(lèi)可以復(fù)寫(xiě) get_current_user(), 這將會(huì)在第一次訪問(wèn) self.current_user 時(shí)自動(dòng)被調(diào)用. get_current_user() 在每次請(qǐng)求時(shí)只會(huì)被調(diào)用一次, 并為 將來(lái)訪問(wèn)做緩存:

def get_current_user(self):
    user_cookie = self.get_secure_cookie("user")
    if user_cookie:
        return json.loads(user_cookie)
    return None

它可以被設(shè)置為一個(gè)普通的變量, 通常在來(lái)自被復(fù)寫(xiě)的 prepare():

@gen.coroutine
def prepare(self):
    user_id_cookie = self.get_secure_cookie("user_id")
    if user_id_cookie:
        self.current_user = yield load_user(user_id_cookie)

注意 prepare() 可能是一個(gè)協(xié)程, 盡管 get_current_user() 可能不是, 所以如果加載用戶(hù)需要異步操作后面的形式是必要的.

用戶(hù)對(duì)象可以是application選擇的任意類(lèi)型.

從 Accept-Language 頭決定用戶(hù)的位置.

參考 http://www.w3.org/Protocols/r...

復(fù)寫(xiě)來(lái)實(shí)現(xiàn)獲取當(dāng)前用戶(hù), e.g., 從cookie得到.

這個(gè)方法可能不是一個(gè)協(xié)程.

復(fù)寫(xiě)這個(gè)方法自定義基于請(qǐng)求的登陸URL.

默認(rèn)情況下, 我們使用application設(shè)置中的 login_url 值.

返回響應(yīng)的狀態(tài)碼.

可以復(fù)寫(xiě)為每個(gè)handler指定自定義模板路徑.

默認(rèn)情況下, 我們使用應(yīng)用設(shè)置中的 template_path . 如果返回None則使用調(diào)用文件的相對(duì)路徑加載模板.

復(fù)寫(xiě)這個(gè)方法確定認(rèn)證過(guò)的用戶(hù)所在位置.

如果返回了None , 我們退回選擇 get_browser_locale().

這個(gè)方法應(yīng)該返回一個(gè) tornado.locale.Locale 對(duì)象, 就像調(diào)用 tornado.locale.get("en") 得到的那樣

返回當(dāng)前session的位置.

通過(guò) get_user_locale 來(lái)確定, 你可以復(fù)寫(xiě)這個(gè)方法設(shè)置 獲取locale的條件, e.g., 記錄在數(shù)據(jù)庫(kù)中的用戶(hù)偏好, 或 get_browser_locale, 使用 Accept-Language 頭部.

復(fù)寫(xiě)來(lái)自定義未捕獲異常的日志.

默認(rèn)情況下 HTTPError 的日志實(shí)例作為警告(warning)沒(méi)有堆棧追蹤(在 tornado.general logger), 其他作為錯(cuò)誤(error)的異常帶有堆棧 追蹤(在 tornado.application logger).

3.1 新版功能.

在異步處理中, 如果客戶(hù)端關(guān)閉了連接將會(huì)被調(diào)用.

復(fù)寫(xiě)這個(gè)方法來(lái)清除與長(zhǎng)連接相關(guān)的資源. 注意這個(gè)方法只有當(dāng)在異步處理 連接被關(guān)閉才會(huì)被調(diào)用; 如果你需要在每個(gè)請(qǐng)求之后做清理, 請(qǐng)復(fù)寫(xiě) on_finish 方法來(lái)代替.

在客戶(hù)端離開(kāi)后, 代理可能會(huì)保持連接一段時(shí)間 (也可能是無(wú)限期), 所以這個(gè)方法在終端用戶(hù)關(guān)閉他們的連接時(shí)可能不會(huì)被立即執(zhí)行.

如果給定的app設(shè)置未定義則拋出一個(gè)異常.

Application.reverse_url 的別名.

設(shè)置響應(yīng)的Etag頭使用 self.compute_etag() 計(jì)算.

注意: 如果 compute_etag() 返回 None 將不會(huì)設(shè)置頭.

這個(gè)方法在請(qǐng)求結(jié)束的時(shí)候自動(dòng)調(diào)用.

self.application.settings 的別名.

為給定的相對(duì)路徑的靜態(tài)文件返回一個(gè)靜態(tài)URL.

這個(gè)方法需要你在你的應(yīng)用中設(shè)置 static_path (既你 靜態(tài)文件的根目錄).

這個(gè)方法返回一個(gè)帶有版本的url (默認(rèn)情況下會(huì)添加 ?v=), 這會(huì)允許靜態(tài)文件被無(wú)限期緩存. 這可以被 禁用通過(guò)傳遞 include_version=False (默認(rèn)已經(jīng)實(shí)現(xiàn); 其他靜態(tài)文件的實(shí)現(xiàn)不需要支持這一點(diǎn), 但它們可能支持其他選項(xiàng)).

默認(rèn)情況下這個(gè)方法返回當(dāng)前host的相對(duì)URL, 但是如果 include_host 為true則返回的將是絕對(duì)路徑的URL. 如果這個(gè)處理函數(shù)有一個(gè) include_host 屬性, 該值將被所有的 static_url 調(diào)用默認(rèn)使用, 而不需要傳遞 include_host 作為一個(gè)關(guān)鍵字參數(shù).

一個(gè)將被包含在所有POST表單中的HTML 標(biāo)簽.

它定義了我們?cè)谒蠵OST請(qǐng)求中為了預(yù)防偽造跨站請(qǐng)求所檢查的 _xsrf 的輸入值. 如果你設(shè)置了 xsrf_cookies application設(shè)置, 你必須包含這個(gè)HTML 在你所有的HTML表單.

在一個(gè)模板中, 這個(gè)方法應(yīng)該使用 {% module xsrf_form_html() %} 這種方式調(diào)用

查看上面的 check_xsrf_cookie() 了解更多信息.

當(dāng)前用戶(hù)/會(huì)話(huà)的XSRF-prevention token.

為了防止偽造跨站請(qǐng)求, 我們?cè)O(shè)置一個(gè) ‘_xsrf’ cookie 并在所有POST 請(qǐng)求中包含相同的 ‘_xsrf’ 值作為一個(gè)參數(shù). 如果這兩個(gè)不匹配, 我們會(huì)把這個(gè)提交當(dāng)作潛在的偽造請(qǐng)求而拒絕掉.

查看 http://en.wikipedia.org/wiki/...

在 3.2.2 版更改: 該xsrf token現(xiàn)在已經(jīng)在每個(gè)請(qǐng)求都有一個(gè)隨機(jī)mask這使得它 可以簡(jiǎn)潔的把token包含在頁(yè)面中是安全的. 查看 http://breachattack.com 瀏覽更多信息關(guān)于這個(gè)更改修復(fù)的 問(wèn)題. 舊(版本1)cookies 將被轉(zhuǎn)換到版本2 當(dāng)這個(gè)方法被調(diào)用 除非 xsrf_cookie_version Application 被設(shè)置為1.

在 4.3 版更改: 該 xsrf_cookie_kwargs Application 設(shè)置可能被用來(lái) 補(bǔ)充額外的cookie 選項(xiàng)(將會(huì)直接傳遞給 set_cookie). 例如, xsrf_cookie_kwargs=dict(httponly=True, secure=True) 將設(shè)置 secure 和 httponly 標(biāo)志在 _xsrf cookie.

class tornado.web.Application(handlers=None, default_host="", transforms=None, **settings)
組成一個(gè)web應(yīng)用程序的請(qǐng)求處理程序的集合.

該類(lèi)的實(shí)例是可調(diào)用的并且可以被直接傳遞給HTTPServer為應(yīng)用程序 提供服務(wù):

application = web.Application([
    (r"/", MainPageHandler),
])
http_server = httpserver.HTTPServer(application)
http_server.listen(8080)
ioloop.IOLoop.current().start()

這個(gè)類(lèi)的構(gòu)造器帶有一個(gè)列表包含 URLSpec 對(duì)象或 (正則表達(dá)式, 請(qǐng)求類(lèi))元組. 當(dāng)我們接收到請(qǐng)求, 我們按順序迭代該列表 并且實(shí)例化和請(qǐng)求路徑相匹配的正則表達(dá)式所對(duì)應(yīng)的第一個(gè)請(qǐng)求類(lèi). 請(qǐng)求類(lèi)可以被指定為一個(gè)類(lèi)對(duì)象或一個(gè)(完全有資格的)名字.

每個(gè)元組可以包含另外的部分, 只要符合 URLSpec 構(gòu)造器參數(shù)的條件. (在Tornado 3.2之前, 只允許包含兩個(gè)或三個(gè)元素的元組).

一個(gè)字典可以作為該元組的第三個(gè)元素被傳遞, 它將被用作處理程序 構(gòu)造器的關(guān)鍵字參數(shù)和 initialize 方法. 這種模式也被用于例子中的 StaticFileHandler (注意一個(gè) StaticFileHandler 可以被自動(dòng)掛載連帶下面的static_path設(shè)置):

application = web.Application([
    (r"/static/(.*)", web.StaticFileHandler, {"path": "/var/www"}),
])

我們支持虛擬主機(jī)通過(guò) add_handlers 方法, 該方法帶有一個(gè)主機(jī) 正則表達(dá)式作為第一個(gè)參數(shù):

application.add_handlers(r"www.myhost.com", [
    (r"/article/([0-9]+)", ArticleHandler),
])

你可以提供靜態(tài)文件服務(wù)通過(guò)傳遞 static_path 配置作為關(guān)鍵字 參數(shù). 我們將提供這些文件從 /static/ URI (這是可配置的通過(guò) static_url_prefix 配置), 并且我們將提供 /favicon.ico 和 /robots.txt 從相同目錄下. 一個(gè) StaticFileHandler 的 自定義子類(lèi)可以被指定, 通過(guò) static_handler_class 設(shè)置.

傳遞給構(gòu)造器的附加關(guān)鍵字參數(shù)保存在 settings 字典中, 并經(jīng)常在文檔中被稱(chēng)為”application settings”. Settings被用于 自定義Tornado的很多方面(雖然在一些情況下, 更豐富的定制可能 是通過(guò)在 RequestHandler 的子類(lèi)中復(fù)寫(xiě)方法). 一些應(yīng)用程序 也喜歡使用 settings 字典作為使一些處理程序可以使用應(yīng)用 程序的特定設(shè)置的方法, 而無(wú)需使用全局變量. Tornado中使用的 Setting描述如下.

autoreload: 如果為 True, 服務(wù)進(jìn)程將會(huì)在任意資源文件 改變的時(shí)候重啟, 正如 Debug模式和自動(dòng)重載 中描述的那樣. 這個(gè)選項(xiàng)是Tornado 3.2中新增的; 在這之前這個(gè)功能是由 debug 設(shè)置控制的.
debug: 一些調(diào)試模式設(shè)置的速記, 正如 Debug模式和自動(dòng)重載 中描述的那樣. debug=True 設(shè)置等同于 autoreload=True, compiled_template_cache=False, static_hash_cache=False, serve_traceback=True.
default_handler_class 和 default_handler_args: 如果沒(méi)有發(fā)現(xiàn)其他匹配則會(huì)使用這個(gè)處理程序; 使用這個(gè)來(lái)實(shí)現(xiàn)自 定義404頁(yè)面(Tornado 3.2新增).
compress_response: 如果為 True, 以文本格式的響應(yīng) 將被自動(dòng)壓縮. Tornado 4.0新增.
gzip: 不推薦使用的 compress_response 別名自從 Tornado 4.0.
log_function: 這個(gè)函數(shù)將在每次請(qǐng)求結(jié)束的時(shí)候調(diào)用以記錄 結(jié)果(有一次參數(shù), 該 RequestHandler 對(duì)象). 默認(rèn)實(shí)現(xiàn)是寫(xiě)入 logging 模塊的根logger. 也可以通過(guò)復(fù)寫(xiě) Application.log_request 自定義.
serve_traceback: 如果為true, 默認(rèn)的錯(cuò)誤頁(yè)將包含錯(cuò)誤信息 的回溯. 這個(gè)選項(xiàng)是在Tornado 3.2中新增的; 在此之前這個(gè)功能 由 debug 設(shè)置控制.
ui_modules 和 ui_methods: 可以被設(shè)置為 UIModule 或UI methods 的映射提供給模板. 可以被設(shè)置為一個(gè)模塊, 字典, 或一個(gè)模塊的列表和/或字典. 參見(jiàn) UI 模塊 了解更多 細(xì)節(jié).
認(rèn)證和安全設(shè)置(Authentication and security settings):

cookie_secret: 被 RequestHandler.get_secure_cookie 使用, set_secure_cookie 用來(lái)給cookies簽名.
key_version: 被requestHandler set_secure_cookie 使用一個(gè)特殊的key給cookie簽名當(dāng) cookie_secret 是一個(gè) key字典.
login_url: authenticated 裝飾器將會(huì)重定向到這個(gè)url 如果該用戶(hù)沒(méi)有登陸. 更多自定義特性可以通過(guò)復(fù)寫(xiě) RequestHandler.get_login_url 實(shí)現(xiàn)
xsrf_cookies: 如果true, 跨站請(qǐng)求偽造(防護(hù)) 將被開(kāi)啟.
xsrf_cookie_version: 控制由該server產(chǎn)生的新XSRF cookie的版本. 一般應(yīng)在默認(rèn)情況下(這將是最高支持的版本), 但是可以被暫時(shí)設(shè)置為一個(gè)較低的值, 在版本切換之間. 在Tornado 3.2.2 中新增, 這里引入了XSRF cookie 版本2.
xsrf_cookie_kwargs: 可設(shè)置為額外的參數(shù)字典傳遞給 RequestHandler.set_cookie 為該XSRF cookie.
twitter_consumer_key, twitter_consumer_secret, friendfeed_consumer_key, friendfeed_consumer_secret, google_consumer_key, google_consumer_secret, facebook_api_key, facebook_secret: 在 tornado.auth 模塊中使用來(lái)驗(yàn)證各種APIs.
模板設(shè)置:

autoescape: 控制對(duì)模板的自動(dòng)轉(zhuǎn)義. 可以被設(shè)置為 None 以禁止轉(zhuǎn)義, 或設(shè)置為一個(gè)所有輸出都該傳遞過(guò)去的函數(shù) name . 默認(rèn)是 "xhtml_escape". 可以在每個(gè)模板中改變使用 {% autoescape %} 指令.
compiled_template_cache: 默認(rèn)是 True; 如果是 False 模板將會(huì)在每次請(qǐng)求重新編譯. 這個(gè)選項(xiàng)是Tornado 3.2中新增的; 在這之前這個(gè)功能由 debug 設(shè)置控制.
template_path: 包含模板文件的文件夾. 可以通過(guò)復(fù)寫(xiě) RequestHandler.get_template_path 進(jìn)一步定制
template_loader: 分配給 tornado.template.BaseLoader 的一個(gè)實(shí)例自定義模板加載. 如果使用了此設(shè)置, 則 template_path 和 autoescape 設(shè)置都會(huì)被忽略. 可 通過(guò)復(fù)寫(xiě) RequestHandler.create_template_loader 進(jìn)一步 定制.
template_whitespace: 控制處理模板中的空格; 參見(jiàn) tornado.template.filter_whitespace 查看允許的值. 在Tornado 4.3中新增.
靜態(tài)文件設(shè)置:

static_hash_cache: 默認(rèn)為 True; 如果是 False 靜態(tài)url將會(huì)在每次請(qǐng)求重新計(jì)算. 這個(gè)選項(xiàng)是Tornado 3.2中 新增的; 在這之前這個(gè)功能由 debug 設(shè)置控制.
static_path: 將被提供服務(wù)的靜態(tài)文件所在的文件夾.
static_url_prefix: 靜態(tài)文件的Url前綴, 默認(rèn)是 "/static/".
static_handler_class, static_handler_args: 可 設(shè)置成為靜態(tài)文件使用不同的處理程序代替默認(rèn)的 tornado.web.StaticFileHandler. static_handler_args, 如果設(shè)置, 應(yīng)該是一個(gè)關(guān)鍵字參數(shù)的字典傳遞給處理程序 的 initialize 方法.
listen(port, address="", **kwargs)
為應(yīng)用程序在給定端口上啟動(dòng)一個(gè)HTTP server.

這是一個(gè)方便的別名用來(lái)創(chuàng)建一個(gè) HTTPServer 對(duì)象并調(diào)用它 的listen方法. HTTPServer.listen 不支持傳遞關(guān)鍵字參數(shù)給 HTTPServer 構(gòu)造器. 對(duì)于高級(jí)用途 (e.g. 多進(jìn)程模式), 不要使用這個(gè)方法; 創(chuàng)建一個(gè) HTTPServer 并直接調(diào)用它的 TCPServer.bind/TCPServer.start 方法.

注意在調(diào)用這個(gè)方法之后你仍然需要調(diào)用 IOLoop.current().start() 來(lái)啟動(dòng)該服務(wù).

返回 HTTPServer 對(duì)象.

在 4.3 版更改: 現(xiàn)在返回 HTTPServer 對(duì)象.

添加給定的handler到我們的handler表.

Host 模式將按照它們的添加順序進(jìn)行處理. 所有匹配模式將被考慮.

返回名為 name 的handler的URL路徑

處理程序必須作為 URLSpec 添加到應(yīng)用程序.

捕獲組的參數(shù)將在 URLSpec 的正則表達(dá)式被替換. 如有必要它們將被轉(zhuǎn)換成string, 編碼成utf8,及 網(wǎng)址轉(zhuǎn)義(url-escaped).

寫(xiě)一個(gè)完成的HTTP 請(qǐng)求到日志中.

默認(rèn)情況下會(huì)寫(xiě)到python 根(root)logger. 要改變這種行為 無(wú)論是子類(lèi)應(yīng)用和復(fù)寫(xiě)這個(gè)方法, 或者傳遞一個(gè)函數(shù)到應(yīng)用的 設(shè)置字典中作為 log_function.

指定URL和處理程序之間的映射.

Parameters:

pattern: 被匹配的正則表達(dá)式. 任何在正則表達(dá)式的group 都將作為參數(shù)傳遞給處理程序的get/post/等方法.
handler: 被調(diào)用的 RequestHandler 子類(lèi).
kwargs (optional): 將被傳遞給處理程序構(gòu)造器的額外 參數(shù)組成的字典.
name (optional): 該處理程序的名稱(chēng). 被 Application.reverse_url 使用.
URLSpec 類(lèi)在 tornado.web.url 名稱(chēng)下也是可用的.

裝飾器(Decorators)
tornado.web.asynchronous(method)
用這個(gè)包裝請(qǐng)求處理方法如果它們是異步的.

這個(gè)裝飾器適用于回調(diào)式異步方法; 對(duì)于協(xié)程, 使用 @gen.coroutine 裝飾器而沒(méi)有 @asynchronous. (這是合理的, 因?yàn)檫z留原因使用兩個(gè) 裝飾器一起來(lái)提供 @asynchronous 在第一個(gè), 但是在這種情況下 @asynchronous 將被忽略)

這個(gè)裝飾器應(yīng)僅適用于 HTTP verb methods; 它的行為是未定義的對(duì)于任何其他方法. 這個(gè)裝飾器不會(huì) 使 一個(gè)方法異步; 它告訴框架該方法 是 異步(執(zhí)行)的. 對(duì)于這個(gè)裝飾器, 該方法必須(至少有時(shí))異步的做一 些事情這是有用的.

如果給定了這個(gè)裝飾器, 當(dāng)方法返回的時(shí)候響應(yīng)并沒(méi)有結(jié)束. 它是由請(qǐng)求處理程序調(diào)用 self.finish() 來(lái)結(jié)束該HTTP請(qǐng)求的. 沒(méi)有這個(gè)裝飾器, 請(qǐng)求會(huì)自動(dòng)結(jié)束當(dāng) get() 或 post() 方法返回時(shí). 例如:

class MyRequestHandler(RequestHandler):
    @asynchronous
    def get(self):
       http = httpclient.AsyncHTTPClient()
       http.fetch("http://friendfeed.com/", self._on_download)

    def _on_download(self, response):
       self.write("Downloaded!")
       self.finish()

在 3.1 版更改: 可以使用 @gen.coroutine 而不需 @asynchronous.

在 4.3 版更改: 可以返回任何東西但 None 或者一個(gè) 可yield的對(duì)象來(lái)自于被 @asynchronous 裝飾的方法是錯(cuò)誤的. 這樣的返回值之前是默認(rèn)忽略的.

使用這個(gè)裝飾的方法要求用戶(hù)必須登陸.

如果用戶(hù)未登陸, 他們將被重定向到已經(jīng)配置的 login url.

如果你配置login url帶有查詢(xún)參數(shù), Tornado將假設(shè)你知道你正在 做什么并使用它. 如果不是, 它將添加一個(gè) next 參數(shù)這樣登陸 頁(yè)就會(huì)知道一旦你登陸后將把你送到哪里.

使用這個(gè)裝飾器給請(qǐng)求路徑中添加丟失的slash.

例如, 使用了這個(gè)裝飾器請(qǐng)求 /foo 將被重定向到 /foo/ . 你的請(qǐng)求處理映射應(yīng)該使用正則表達(dá)式類(lèi)似 r"/foo/?" 和使用裝飾器相結(jié)合.

使用這個(gè)裝飾器移除請(qǐng)求路徑尾部的斜杠(slashes).

例如, 使用了這個(gè)裝飾器請(qǐng)求 /foo/ 將被重定向到 /foo . 你的請(qǐng)求處理映射應(yīng)該使用正則表達(dá)式類(lèi)似 r"/foo/*" 和使用裝飾器相結(jié)合.

適用于 RequestHandler 子類(lèi)以開(kāi)啟流式body支持.

這個(gè)裝飾器意味著以下變化:

HTTPServerRequest.body 變成了未定義, 并且body參數(shù)將不再被 RequestHandler.get_argument 所包含.
RequestHandler.prepare 被調(diào)用當(dāng)讀到請(qǐng)求頭而不是在整個(gè)請(qǐng)求體 都被讀到之后.
子類(lèi)必須定義一個(gè)方法 data_received(self, data):, 這將被調(diào) 用0次或多次當(dāng)數(shù)據(jù)是可用狀態(tài)時(shí). 注意如果該請(qǐng)求的body是空的, data_received 可能不會(huì)被調(diào)用.
prepare 和 data_received 可能返回Futures對(duì)象(就像通過(guò) @gen.coroutine, 在這種情況下下一個(gè)方法將不會(huì)被調(diào)用直到這些 futures完成.
常規(guī)的HTTP方法 (post, put, 等)將在整個(gè)body被讀取后被 調(diào)用.
在 data_received 和asynchronous之間有一個(gè)微妙的互動(dòng) prepare: data_received 的第一次調(diào)用可能出現(xiàn)在任何地方 在調(diào)用 prepare 已經(jīng)返回 或 yielded.

一個(gè)將會(huì)成為HTTP錯(cuò)誤響應(yīng)的異常.

拋出一個(gè) HTTPError 是一個(gè)更方便的選擇比起調(diào)用 RequestHandler.send_error 因?yàn)樗詣?dòng)結(jié)束當(dāng)前的函數(shù).

為了自定義 HTTPError 的響應(yīng), 復(fù)寫(xiě) RequestHandler.write_error.

參數(shù):
status_code (int) – HTTP狀態(tài)碼. 必須列在 httplib.responses 之中除非給定了 reason 關(guān)鍵字參數(shù).
log_message (string) – 這個(gè)錯(cuò)誤將會(huì)被寫(xiě)入日志的信息(除非該 Application 是debug模式否則不會(huì)展示給用戶(hù)). 可能含有 %s-風(fēng)格的占位符, 它將填補(bǔ)剩余的位置參數(shù).
reason (string) – 唯一的關(guān)鍵字參數(shù). HTTP “reason” 短語(yǔ) 將隨著 status_code 傳遞給狀態(tài)行. 通常從 status_code, 自動(dòng)確定但可以使用一個(gè)非標(biāo)準(zhǔn)的數(shù)字代碼.

一個(gè)會(huì)結(jié)束請(qǐng)求但不會(huì)產(chǎn)生錯(cuò)誤響應(yīng)的異常.

當(dāng)一個(gè) RequestHandler 拋出 Finish , 該請(qǐng)求將會(huì)結(jié)束(調(diào)用 RequestHandler.finish 如果該方法尚未被調(diào)用), 但是錯(cuò)誤處理方法 (包括 RequestHandler.write_error)將不會(huì)被調(diào)用.

如果 Finish() 創(chuàng)建的時(shí)候沒(méi)有攜帶參數(shù), 則會(huì)發(fā)送一個(gè)pending響應(yīng). 如果 Finish() 給定了參數(shù), 則參數(shù)將會(huì)傳遞給 RequestHandler.finish().

這是比復(fù)寫(xiě) write_error 更加便利的方式用來(lái)實(shí)現(xiàn)自定義錯(cuò)誤頁(yè) (尤其是在library代碼中):

if self.current_user is None:
    self.set_status(401)
    self.set_header("WWW-Authenticate", "Basic realm="something"")
    raise Finish()

在 4.3 版更改: 傳遞給 Finish() 的參數(shù)將被傳遞給 RequestHandler.finish.

由 RequestHandler.get_argument 拋出的異常.

這是 HTTPError 的一個(gè)子類(lèi), 所以如果是未捕獲的400響應(yīng)碼將被 用來(lái)代替500(并且棧追蹤不會(huì)被記錄到日志).

3.1 新版功能.

一個(gè)在頁(yè)面上可復(fù)用, 模塊化的UI單元.

UI模塊經(jīng)常執(zhí)行附加的查詢(xún), 它們也可以包含額外的CSS和 JavaScript, 這些將包含在輸出頁(yè)面上, 在頁(yè)面渲染的時(shí)候自動(dòng)插入.

UIModule的子類(lèi)必須復(fù)寫(xiě) render 方法.

在子類(lèi)中復(fù)寫(xiě)以返回這個(gè)模塊的輸出.

復(fù)寫(xiě)以返回一個(gè)被嵌入頁(yè)面的JavaScript字符串.

復(fù)寫(xiě)以返回這個(gè)模塊需要的JavaScript文件列表.

如果返回值是相對(duì)路徑, 它們將被傳遞給 RequestHandler.static_url; 否則會(huì)被原樣使用.

復(fù)寫(xiě)以返回一個(gè)將被嵌入頁(yè)面的CSS字符串.

復(fù)寫(xiě)以返回這個(gè)模塊需要的CSS文件列表.

如果返回值是相對(duì)路徑, 它們將被傳遞給 RequestHandler.static_url; 否則會(huì)被原樣使用.

復(fù)寫(xiě)以返回一個(gè)將被放入標(biāo)簽的HTML字符串.

復(fù)寫(xiě)以返回一個(gè)將被放入標(biāo)簽最后的HTML字符串.

渲染一個(gè)模板并且將它作為一個(gè)字符串返回.

為所有請(qǐng)求生成一個(gè)帶有 status_code 的錯(cuò)誤響應(yīng).

包裝其他HTTP server回調(diào)的 RequestHandler .

fallback是一個(gè)可調(diào)用的對(duì)象, 它接收一個(gè) HTTPServerRequest, 諸如一個(gè) Application 或 tornado.wsgi.WSGIContainer. 這對(duì)于在相同server中同時(shí)使用 Tornado RequestHandlers 和WSGI是非常有用的. 用法:

wsgi_app = tornado.wsgi.WSGIContainer(
    django.core.handlers.wsgi.WSGIHandler())
application = tornado.web.Application([
    (r"/foo", FooHandler),
    (r".*", FallbackHandler, dict(fallback=wsgi_app),
])

將所有GET請(qǐng)求重定向到給定的URL.

你需要為處理程序提供 url 關(guān)鍵字參數(shù), e.g.:

application = web.Application([
    (r"/oldpath", web.RedirectHandler, {"url": "/newpath"}),
])

可以為一個(gè)目錄提供靜態(tài)內(nèi)容服務(wù)的簡(jiǎn)單處理程序.

StaticFileHandler 是自動(dòng)配置的如果你傳遞了 static_path 關(guān)鍵字參數(shù)給 Application. 這個(gè)處理程序可以被自定義通過(guò) static_url_prefix, static_handler_class, 和 static_handler_args 配置.

為了將靜態(tài)數(shù)據(jù)目錄映射一個(gè)額外的路徑給這個(gè)處理程序你可以在你應(yīng)用程序中 添加一行例如:

application = web.Application([
    (r"/content/(.*)", web.StaticFileHandler, {"path": "/var/www"}),
])

處理程序構(gòu)造器需要一個(gè) path 參數(shù), 該參數(shù)指定了將被服務(wù)內(nèi)容的本地根 目錄.

注意在正則表達(dá)式的捕獲組需要解析 path 參數(shù)的值給get()方法(不同于 上面的構(gòu)造器的參數(shù)); 參見(jiàn) URLSpec 了解細(xì)節(jié).

為了自動(dòng)的提供一個(gè)文件例如 index.html 當(dāng)一個(gè)目錄被請(qǐng)求的時(shí)候, 設(shè)置 static_handler_args=dict(default_filename="index.html") 在你的應(yīng)用程序設(shè)置中(application settings), 或添加 default_filename 作為你的 StaticFileHandler 的初始化參數(shù).

為了最大限度的提高瀏覽器緩存的有效性, 這個(gè)類(lèi)支持版本化的url(默認(rèn)情 況下使用 ?v= 參數(shù)). 如果給定了一個(gè)版本, 我們指示瀏覽器無(wú)限期 的緩存該文件. make_static_url (也可作為 RequestHandler.static_url) 可以被用來(lái)構(gòu)造一個(gè)版本化的url.

該處理程序主要用戶(hù)開(kāi)發(fā)和輕量級(jí)處理文件服務(wù); 對(duì)重型傳輸,使用專(zhuān)用的 靜態(tài)文件服務(wù)是更高效的(例如nginx或Apache). 我們支持HTTP Accept-Ranges 機(jī)制來(lái)返回部分內(nèi)容(因?yàn)橐恍g覽器需要此功能是 為了查找在HTML5音頻或視頻中).

子類(lèi)注意事項(xiàng)

這個(gè)類(lèi)被設(shè)計(jì)是可以讓子類(lèi)繼承的, 但由于靜態(tài)url是被類(lèi)方法生成的 而不是實(shí)例方法的方式, 繼承模式有點(diǎn)不同尋常. 一定要使用 @classmethod 裝飾器當(dāng)復(fù)寫(xiě)一個(gè)類(lèi)方法時(shí). 實(shí)例方法可以使用 self.path self.absolute_path, 和 self.modified 屬性.

子類(lèi)應(yīng)該只復(fù)寫(xiě)在本節(jié)討論的方法; 復(fù)寫(xiě)其他方法很容易出錯(cuò). 最重要的 StaticFileHandler.get 問(wèn)題尤其嚴(yán)重, 由于與 compute_etag 還有其他方法緊密耦合.

為了改變靜態(tài)url生成的方式(e.g. 匹配其他服務(wù)或CDN), 復(fù)寫(xiě) make_static_url, parse_url_path, get_cache_time, 和/或 get_version.

為了代替所有與文件系統(tǒng)的相互作用(e.g. 從數(shù)據(jù)庫(kù)提供靜態(tài)內(nèi)容服務(wù)), 復(fù)寫(xiě) get_content, get_content_size, get_modified_time, get_absolute_path, 和 validate_absolute_path.

在 3.1 版更改: 一些為子類(lèi)設(shè)計(jì)的方法在Tornado 3.1 被添加.

設(shè)置 Etag 頭基于static url版本.

這允許高效的針對(duì)緩存版本的 If-None-Match 檢查, 并發(fā)送正確的 Etag 給局部的響應(yīng)(i.e. 相同的 Etag 為完整的文件).

3.1 新版功能.

設(shè)置響應(yīng)的內(nèi)容和緩存頭.

3.1 新版功能.

如果頭部表明我們應(yīng)該返回304則返回True.

3.1 新版功能.

返回 path 相對(duì)于 root 的絕對(duì)路徑.

root 是這個(gè) StaticFileHandler 配置的路徑(在大多數(shù)情 況下是 Application 的 static_path 設(shè)置).

這個(gè)類(lèi)方法可能在子類(lèi)中被復(fù)寫(xiě). 默認(rèn)情況下它返回一個(gè)文件系統(tǒng) 路徑, 但其他字符串可以被使用, 只要它們是獨(dú)特的并且被 子類(lèi)復(fù)寫(xiě)的 get_content 理解.

3.1 新版功能.

驗(yàn)證并返回絕對(duì)路徑.

root 是 StaticFileHandler 配置的路徑,并且 path 是 get_absolute_path 的結(jié)果.

這是一個(gè)實(shí)例方法在請(qǐng)求過(guò)程中被調(diào)用, 所以它可能拋出 HTTPError 或者使用類(lèi)似 RequestHandler.redirect (返回None在重定向到停止進(jìn)一步處理之后) 這種方法. 如果丟失文件將會(huì)生成404錯(cuò)誤.

這個(gè)方法可能在返回路徑之前修改它, 但是注意任何這樣的 修改將不會(huì)被 make_static_url 理解.

在實(shí)例方法, 這個(gè)方法的結(jié)果對(duì) self.absolute_path 是可用的.

3.1 新版功能.

檢索位于所給定絕對(duì)路徑的請(qǐng)求資源的內(nèi)容.

這個(gè)類(lèi)方法可以被子類(lèi)復(fù)寫(xiě). 注意它的特征不同于其他可復(fù)寫(xiě) 的類(lèi)方法(沒(méi)有 settings 參數(shù)); 這是經(jīng)過(guò)深思熟慮的以 確保 abspath 能依靠自己作為緩存鍵(cache key) .

這個(gè)方法返回一個(gè)字節(jié)串或一個(gè)可迭代的字節(jié)串. 對(duì)于大文件 后者是更優(yōu)的選擇因?yàn)樗兄跍p少內(nèi)存碎片.

3.1 新版功能.

返回給定路徑資源的一個(gè)版本字符串.

這個(gè)類(lèi)方法可以被子類(lèi)復(fù)寫(xiě). 默認(rèn)的實(shí)現(xiàn)是對(duì)文件內(nèi)容的hash.

3.1 新版功能.

檢索給定路徑中資源的總大小.

這個(gè)方法可以被子類(lèi)復(fù)寫(xiě).

3.1 新版功能.

在 4.0 版更改: 這個(gè)方法總是被調(diào)用, 而不是僅在部分結(jié)果被請(qǐng)求時(shí).

返回 self.absolute_path 的最后修改時(shí)間.

可以被子類(lèi)復(fù)寫(xiě). 應(yīng)當(dāng)返回一個(gè) datetime 對(duì)象或None.

3.1 新版功能.

返回這個(gè)請(qǐng)求使用的 Content-Type 頭.

3.1 新版功能.

為了子類(lèi)給響應(yīng)添加額外的頭部

復(fù)寫(xiě)來(lái)自定義緩存控制行為.

返回一個(gè)正的秒數(shù)作為結(jié)果可緩存的時(shí)間的量或者返回0標(biāo)記資源 可以被緩存一個(gè)未指定的時(shí)間段(受瀏覽器自身的影響).

默認(rèn)情況下帶有 v 請(qǐng)求參數(shù)的資源返回的緩存過(guò)期時(shí)間是10年.

為給定路徑構(gòu)造一個(gè)的有版本的url.

這個(gè)方法可以在子類(lèi)中被復(fù)寫(xiě)(但是注意他是一個(gè)類(lèi)方法而不是一個(gè) 實(shí)例方法). 子類(lèi)只需實(shí)現(xiàn)簽名 make_static_url(cls, settings, path); 其他關(guān)鍵字參數(shù)可 以通過(guò) static_url 傳遞, 但這不是標(biāo)準(zhǔn).

settings 是 Application.settings 字典. path 是被請(qǐng)求的靜態(tài)路徑. 返回的url應(yīng)該是相對(duì)于當(dāng)前host的.

include_version 決定生成的URL是否應(yīng)該包含含有給定 path 相對(duì)應(yīng)文件的hash版本查詢(xún)字符串.

將靜態(tài)URL路徑轉(zhuǎn)換成文件系統(tǒng)路徑.

url_path 是由去掉 static_url_prefix 的URL組成. 返回值應(yīng)該是相對(duì)于 static_path 的文件系統(tǒng)路徑.

這是逆 make_static_url .

生成用于靜態(tài)URL的版本字符串.

settings 是 Application.settings 字典并且 path 是請(qǐng)求資源在文件系統(tǒng)中的相對(duì)位置. 返回值應(yīng)該是一個(gè)字符串 或 None 如果沒(méi)有版本可以被確定.

在 3.1 版更改: 這個(gè)方法之前建議在子類(lèi)中復(fù)寫(xiě); get_content_version 現(xiàn)在是首選因?yàn)樗试S基類(lèi)來(lái)處理結(jié)果的緩存.