摘要：譯者說(shuō)于年月日發(fā)布，該版本正式支持的關(guān)鍵字，并且用舊版本編譯同樣可以使用這兩個(gè)關(guān)鍵字，這無(wú)疑是一種進(jìn)步。其次，這是最后一個(gè)支持和的版本了，在后續(xù)的版本了會(huì)移除對(duì)它們的兼容。本節(jié)感謝翻譯本節(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。本節(jié)感謝@thisisx7翻譯

WebSocket 協(xié)議的實(shí)現(xiàn)

WebSockets 允許瀏覽器和服務(wù)器之間進(jìn)行 雙向通信

所有主流瀏覽器的現(xiàn)代版本都支持WebSockets(支持情況詳見(jiàn)：http://caniuse.com/websockets)

該模塊依照最新 WebSocket 協(xié)議 RFC 6455 實(shí)現(xiàn).

在 4.0 版更改: Removed support for the draft 76 protocol version.

通過(guò)繼承該類來(lái)創(chuàng)建一個(gè)基本的 WebSocket handler.

重寫(xiě) on_message 來(lái)處理收到的消息, 使用 write_message 來(lái)發(fā)送消息到客戶端. 你也可以重寫(xiě) open 和 on_close 來(lái)處理連接打開(kāi)和關(guān)閉這兩個(gè)動(dòng)作.

有關(guān)JavaScript 接口的詳細(xì)信息： http://dev.w3.org/html5/websockets/ 具體的協(xié)議： http://tools.ietf.org/html/rfc6455

一個(gè)簡(jiǎn)單的 WebSocket handler 的實(shí)例： 服務(wù)端直接返回所有收到的消息給客戶端

class EchoWebSocket(tornado.websocket.WebSocketHandler):
    def open(self):
        print("WebSocket opened")

    def on_message(self, message):
        self.write_message(u"You said: " + message)

    def on_close(self):
        print("WebSocket closed")

WebSockets 并不是標(biāo)準(zhǔn)的 HTTP 連接. “握手”動(dòng)作符合 HTTP 標(biāo)準(zhǔn),但是在”握手”動(dòng)作之后, 協(xié)議是基于消息的. 因此,Tornado 里大多數(shù)的 HTTP 工具對(duì)于這類 handler 都是不可用的. 用來(lái)通訊的方法只有 write_message() , ping() , 和 close() . 同樣的,你的 request handler 類里應(yīng)該使用 open() 而不是 get() 或者 post()

如果你在應(yīng)用中將這個(gè) handler 分配到 /websocket, 你可以通過(guò)如下代碼實(shí)現(xiàn):

var ws = new WebSocket("ws://localhost:8888/websocket");
ws.onopen = function() {
   ws.send("Hello, world");
};
ws.onmessage = function (evt) {
   alert(evt.data);
};

這個(gè)腳本將會(huì)彈出一個(gè)提示框 :”You said: Hello, world”

瀏覽器并沒(méi)有遵循同源策略(same-origin policy),相應(yīng)的允許了任意站點(diǎn)使用 javascript 發(fā)起任意 WebSocket 連接來(lái)支配其他網(wǎng)絡(luò).這令人驚訝,并且是一個(gè)潛在的安全漏洞,所以 從 Tornado 4.0 開(kāi)始 WebSocketHandler 需要對(duì)希望接受跨域請(qǐng)求的應(yīng)用通過(guò)重寫(xiě).

check_origin (詳細(xì)信息請(qǐng)查看文檔中有關(guān)該方法的部分)來(lái)進(jìn)行設(shè)置. 沒(méi)有正確配置這個(gè)屬性,在建立 WebSocket 連接時(shí)候很可能會(huì)導(dǎo)致 403 錯(cuò)誤.

當(dāng)使用安全的 websocket 連接(wss://) 時(shí), 來(lái)自瀏覽器的連接可能會(huì)失敗,因?yàn)?websocket 沒(méi)有地方輸出 “認(rèn)證成功” 的對(duì)話. 你在 websocket 連接建立成功之前,必須 使用相同的證書(shū)訪問(wèn)一個(gè)常規(guī)的 HTML 頁(yè)面.

當(dāng)打開(kāi)一個(gè)新的 WebSocket 時(shí)調(diào)用

open 的參數(shù)是從 tornado.web.URLSpec 通過(guò)正則表達(dá)式獲取的, 就像獲取 tornado.web.RequestHandler.get 的參數(shù)一樣

處理在 WebSocket 中收到的消息

這個(gè)方法必須被重寫(xiě)

當(dāng)關(guān)閉該 WebSocket 時(shí)調(diào)用

當(dāng)連接被徹底關(guān)閉并且支持 status code 或 reason phtase 的時(shí)候, 可以通過(guò) self.close_code 和 self.close_reason 這兩個(gè)屬性來(lái)獲取它們

在 4.0 版更改: Added close_code and close_reason attributes. 添加 close_code 和 close_reason 這兩個(gè)屬性

當(dāng)一個(gè)新的 WebSocket 請(qǐng)求特定子協(xié)議(subprotocols)時(shí)調(diào)用

subprotocols 是一個(gè)由一系列能夠被客戶端正確識(shí)別出相應(yīng)的子協(xié)議 （subprotocols）的字符串構(gòu)成的 list . 這個(gè)方法可能會(huì)被重載,用來(lái)返回 list 中某 個(gè)匹配字符串, 沒(méi)有匹配到則返回 None. 如果沒(méi)有找到相應(yīng)的子協(xié)議,雖然服務(wù)端并 不會(huì)自動(dòng)關(guān)閉 WebSocket 連接,但是客戶端可以選擇關(guān)閉連接.

將給出的 message 發(fā)送到客戶端

message 可以是 string 或者 dict（將會(huì)被編碼成 json ) 如果 binary 為 false, message 將會(huì)以 utf8 的編碼發(fā)送; 在 binary 模式下 message 可以是 任何 byte string.

如果連接已經(jīng)關(guān)閉, 則會(huì)觸發(fā) WebSocketClosedError

在 3.2 版更改: 添加了 WebSocketClosedError (在之前版本會(huì)觸發(fā) AttributeError)

在 4.3 版更改: 返回能夠被用于 flow control 的 Future.

關(guān)閉當(dāng)前 WebSocket

一旦揮手動(dòng)作成功,socket將會(huì)被關(guān)閉.

code 可能是一個(gè)數(shù)字構(gòu)成的狀態(tài)碼, 采用 RFC 6455 section 7.4.1. 定義的值.

reason 可能是描述連接關(guān)閉的文本消息. 這個(gè)值被提給客戶端,但是不會(huì)被 WebSocket 協(xié)議多帶帶解釋.

在 4.0 版更改: Added the code and reason arguments.

通過(guò)重寫(xiě)這個(gè)方法來(lái)實(shí)現(xiàn)域的切換

參數(shù) origin 的值來(lái)自 HTTP header 中的Origin,url 負(fù)責(zé)初始化這個(gè)請(qǐng)求. 這個(gè)方法并不是要求客戶端不發(fā)送這樣的 heder;這樣的請(qǐng)求一直被允許（因?yàn)樗械臑g覽器 實(shí)現(xiàn)的 websockets 都支持這個(gè) header ,并且非瀏覽器客戶端沒(méi)有同樣的跨域安全問(wèn)題.

返回 True 代表接受,相應(yīng)的返回 False 代表拒絕.默認(rèn)拒絕除 host 外其他域的請(qǐng)求.

這個(gè)是一個(gè)瀏覽器防止 XSS 攻擊的安全策略,因?yàn)?WebSocket 允許繞過(guò)通常的同源策略 以及不使用 CORS 頭.

要允許所有跨域通信的話（這在 Tornado 4.0 之前是默認(rèn)的）,只要簡(jiǎn)單的重寫(xiě)這個(gè)方法 讓它一直返回 true 就可以了:

def check_origin(self, origin):
    return True

要允許所有所有子域下的連接,可以這樣實(shí)現(xiàn):

def check_origin(self, origin):
    parsed_origin = urllib.parse.urlparse(origin)
    return parsed_origin.netloc.endswith(".mydomain.com")

4.0 新版功能.

重寫(xiě)該方法返回當(dāng)前連接的 compression 選項(xiàng)

如果這個(gè)方法返回 None (默認(rèn)), compression 將會(huì)被禁用. 如果它返回 dict (即使 是空的),compression 都會(huì)被開(kāi)啟. dict 的內(nèi)容將會(huì)被用來(lái)控制 compression 所 使用的內(nèi)存和CPU.但是這類的設(shè)置現(xiàn)在還沒(méi)有被實(shí)現(xiàn).

4.1 新版功能.

為當(dāng)前 stream 設(shè)置 no-delay

在默認(rèn)情況下, 小塊數(shù)據(jù)會(huì)被延遲和/或合并以減少發(fā)送包的數(shù)量. 這在有些時(shí)候會(huì)因?yàn)?Nagle’s 算法和 TCP ACKs 相互作用會(huì)造成 200-500ms 的延遲.在 WebSocket 連接 已經(jīng)建立的情況下,可以通過(guò)設(shè)置 self.set_nodelay(True) 來(lái)降低延遲（這可能 會(huì)占用更多帶寬）

更多詳細(xì)信息： BaseIOStream.set_nodelay.

在 BaseIOStream.set_nodelay 查看詳細(xì)信息.

3.1 新版功能.

發(fā)送 ping 包到遠(yuǎn)端.

當(dāng)收到ping 包的響應(yīng)時(shí)執(zhí)行.

出現(xiàn)關(guān)閉連接錯(cuò)誤觸發(fā).

3.2 新版功能.

客戶端 WebSocket 支持 需要指定 url, 返回一個(gè)結(jié)果為 WebSocketClientConnection 的 Future 對(duì)象

compression_options 作為 WebSocketHandler.get_compression_options 的 返回值, 將會(huì)以同樣的方式執(zhí)行.

這個(gè)連接支持兩種類型的操作.在協(xié)程風(fēng)格下,應(yīng)用程序通常在一個(gè)循環(huán)里調(diào)用～.WebSocket ClientConnection.read_message:

conn = yield websocket_connect(url)
while True:
    msg = yield conn.read_message()
    if msg is None: break
    # Do something with msg

在回調(diào)風(fēng)格下,需要傳遞 on_message_callback 到 websocket_connect 里. 在這兩種風(fēng)格里,一個(gè)內(nèi)容是 None 的 message 都標(biāo)志著 WebSocket 連接已經(jīng).

在 3.2 版更改: 允許使用 HTTPRequest 對(duì)象來(lái)代替 urls.

在 4.1 版更改: 添加 compression_options 和 on_message_callback .

不贊成使用 compression_options .

WebSocket 客戶端連接

這個(gè)類不應(yīng)當(dāng)直接被實(shí)例化, 請(qǐng)使用 websocket_connect

關(guān)閉 websocket 連接

code 和 reason 的文檔在 WebSocketHandler.close 下已給出.

3.2 新版功能.

在 4.0 版更改: 添加 code 和 reason 這兩個(gè)參數(shù)

發(fā)送消息到 websocket 服務(wù)器.

讀取來(lái)自 WebSocket 服務(wù)器的消息.

如果在 WebSocket 初始化時(shí)指定了 on_message_callback ,那么這個(gè)方法永遠(yuǎn)不會(huì)返回消息

如果連接已經(jīng)關(guān)閉,返回結(jié)果會(huì)是一個(gè)結(jié)果是 message 的 future 對(duì)象或者是 None. 如果 future 給出了回調(diào)參數(shù), 這個(gè)參數(shù)將會(huì)在 future 完成時(shí)調(diào)用.