筆者最近在學(xué)習(xí)flask-SocketIO倡缠，由于找不到中文文檔攒菠，就選擇了自己翻譯官方的英文文檔迫皱，并分享給大家，希望感興趣的朋友可以一起學(xué)習(xí)辖众。筆者水平有限卓起，難以做到盡善盡美和敬。如有錯(cuò)漏懇，請(qǐng)各位不吝賜教戏阅。
flask-SocketIO 給flask應(yīng)用一個(gè)客戶端和服務(wù)器之間低延遲的雙向通信昼弟。客戶端應(yīng)用可以用Javascript,C++,Java,Swift或者其它任意的編程語(yǔ)言的socketio官方庫(kù)的客戶端奕筐，去和服務(wù)端創(chuàng)建一個(gè)永久的連接私杜。
1.安裝
你可以使用pip這樣常規(guī)的方式來(lái)安裝這個(gè)包
> pip install flask-socketio
2.依賴
Flask-SocketIO兼容python2.7和python3.3+。這個(gè)異步的服務(wù)的包的依賴可以有三個(gè)選擇：
- eventlet：這是最好的選擇救欧，支持長(zhǎng)連接(long-polling)和websocket傳輸。
- gevent: 支持許多不同的配置锣光，長(zhǎng)連接傳輸是完全支持的笆怠，但是不同于eventlet，gevent并沒(méi)有原生支持websocket誊爹。有兩個(gè)辦法去添加websocket蹬刷。gevent-websocket包為gevent添加了websocket支持，但是不幸的是频丘，這個(gè)包只能用于python2办成。至于另外一個(gè)選擇，是用uWSGI網(wǎng)絡(luò)服務(wù)器搂漠，這個(gè)能夠在功能上支持websocket迂卢。gevent依然是可操作的選擇，但是優(yōu)先級(jí)輕微地低于eventlet桐汤。
- 基于Werkzeug開(kāi)發(fā)的flask服務(wù)器也是可行的而克，使用缺乏可操作性的caveat，它僅可以被用于簡(jiǎn)化workflow的開(kāi)發(fā)怔毛。這個(gè)方案僅支持長(zhǎng)連接方式傳輸员萍。
這個(gè)擴(kuò)展自動(dòng)尋找已安裝的異步框架來(lái)使用。最優(yōu)先的是eventlet拣度，其次是gevent碎绎。在gevent中，對(duì)于websocket的支持抗果，uWSGI是優(yōu)先考慮的筋帖，其次是gevent-websocket。如果eventlet和gevent都沒(méi)有被安裝冤馏，那么flask-development將會(huì)被啟用幕随。
如果使用多進(jìn)程，一個(gè)消息隊(duì)列服務(wù)將會(huì)被進(jìn)程用來(lái)協(xié)調(diào)操作宿接，例如廣播赘淮。支持這個(gè)隊(duì)列的有Redis,RabbitMQ,還有其他由Kombu支持的包辕录。
在客戶端，Javascript官方的SOcket.IO可以用來(lái)創(chuàng)建一個(gè)與服務(wù)端通信的連接梢卸。這里有許多用Swift,Java,C++編寫(xiě)的官方客戶端走诞。非官方的客戶端也是可以工作的，只要他們支持了Socket.IO協(xié)議蛤高。
3.初始化
接下來(lái)的代碼例子揭示了蚣旱，怎樣去把Flask-SocketIO引入到Flask應(yīng)用：
from flask import Flask, render_template
from flask_socketio import SocketIO
app = Flask(__name__)
app.configp['SECRET_KEY'] = 'secret!'
socketio = SocketIO(app)
if __name__ == '__main__':
socketio.run(app)
init_app()風(fēng)格的初始化也是支持的。注意網(wǎng)絡(luò)服務(wù)器的啟動(dòng)戴陡。函數(shù)socketio.run()封裝了網(wǎng)絡(luò)服務(wù)器的啟動(dòng)部分塞绿，并且代替了flask開(kāi)發(fā)服務(wù)器的標(biāo)準(zhǔn)啟動(dòng)語(yǔ)句app.run()。當(dāng)應(yīng)用在debug模式下恤批，Werkzeug開(kāi)發(fā)服務(wù)器也是在socketio.run()中被合理地應(yīng)用和配置异吻。如果可用的話，在生產(chǎn)模式下eventlet網(wǎng)絡(luò)服務(wù)器也是被應(yīng)用的喜庞，否則诀浪，gevent網(wǎng)絡(luò)服務(wù)器將會(huì)被啟用。如果eventlet和gevent都沒(méi)有被安裝延都，那么將會(huì)使用Werkzeug開(kāi)發(fā)網(wǎng)絡(luò)服務(wù)器雷猪。
在flask 0.11中被引入的可點(diǎn)擊命令行界面也是被支持的。這個(gè)擴(kuò)展提供了一個(gè)新版的flask run命令晰房，適合啟動(dòng)一個(gè)Socket.IO服務(wù)器求摇。用法示例：
FLASK_APP = my_app flask run
這個(gè)應(yīng)用只能為那種連接到客戶端的頁(yè)面服務(wù)，這個(gè)客戶端引用了Socket.IO庫(kù)并且建立一個(gè)連接：
<script type="text/javascript" scr="http://cdn.cloudflare.com/ajax/libs/socket.io/1.3.6/socket.io.min.js"></scritp>
<script type="text/javascript" charset="utf-8">
var socket = io.connect(location.protocol + '//' + document.domain + ':' + location.port);
socket.on('connect', function() {
socket.emit('my event', {data: 'I\'m connected!'});
});
</script>
4.接收消息
在使用SocketIO的時(shí)候殊者，消息將被作為活動(dòng)(event)的兩端接收月帝。在客戶端使用JavaScript回叫信號(hào)。使用Flask-SocketIO服務(wù)器幽污，需要為這些活動(dòng)注冊(cè)處理器(handler)嚷辅，類似于視圖函數(shù)怎樣處理路由。
下面的例子是為一個(gè)未命名的活動(dòng)創(chuàng)建了一個(gè)服務(wù)端的活動(dòng)處理器(event handler)：
@socketio.on('message')
def handle_message(message):
print('received message: ' + message)
在上面的例子中距误，使用了字符串消息簸搞。此外，另一種未命名的活動(dòng)使用了JSON數(shù)據(jù)：
@socketio.on('json')
def handle_json(json):
print('received json: '+ str(json))
最靈活的一種活動(dòng)使用了自定義的活動(dòng)名稱准潭。這些活動(dòng)的消息數(shù)據(jù)類型可以是字符串趁俊，字節(jié)，整型刑然，或者JSON：
@socketio.on('my event')
def handle_my_custom_event(json):
print('received json: ' + str(json))
自定義名稱的活動(dòng)可以支持多參數(shù)：
@socketio.on('my event')
def handle_my_sustom_event(arg1, arg2, arg3):
print('received args: ' + arg1 + arg2 + arg3)
命名活動(dòng)是極度復(fù)雜的寺擂，在其消除了額外的元數(shù)據(jù)(metadata)來(lái)描述消息類型的時(shí)候。
Flask-SocketIO同樣支持命名空間(namespace)，這個(gè)功能允許客戶端在一個(gè)相同的物理socket上多路復(fù)用幾個(gè)獨(dú)立的連接：
@scoketio.on('my event', namespace='/test')
def handle_my_custom_namespace_event(json):
print('received json: ' + str(json))
當(dāng)一個(gè)命名空間沒(méi)有具體指出怔软，一個(gè)全局的命名空間'/'將會(huì)被啟用
有時(shí)垦细，裝飾器的語(yǔ)法并不方便，on_event()方法可以作為替代
def my_function_handler(data):
pass
socketio.on_event('my event', my_function_handler, namespace='/test')
客戶端要求一個(gè)確認(rèn)回復(fù)挡逼，來(lái)確認(rèn)消息的接收括改。任何一個(gè)從處理函數(shù)(handler function)中返回的值都會(huì)在回調(diào)函數(shù)中作為一個(gè)參數(shù)返回給客戶端。
@socketio.on('my event')
def handle_my_custom_event(json):
print('received json: ' + str(json))
return('one', 2)
在上面的例子中家坎，客戶端回調(diào)函數(shù)將會(huì)回調(diào)兩個(gè)參數(shù)嘱能，'one'和'2'。如果處理函數(shù)沒(méi)有返回值虱疏，這個(gè)客戶端回調(diào)函數(shù)將以沒(méi)有參數(shù)的情況返回惹骂。
5.發(fā)送消息
之前章節(jié)定義的SocketIO活動(dòng)處理函數(shù)可以憑借send()函數(shù)和emit()函數(shù)來(lái)連接客戶端
接下來(lái)的例子是將接收到的消息退回到發(fā)送它們的客戶端：
from flask_socketio import send, emit
@socketio.on('message')
def handle_message(message):
send(message)
@socketio.on('json')
def handle_json(json):
send(json, json=True)
@socket.on('my event')
def handle_my_custom_event(json):
emit('my response', json)
注釋一下，send()和emit()是怎樣用在已命名和未命名的活動(dòng)上的
當(dāng)運(yùn)作在有命名空間的活動(dòng)中時(shí)做瞪，send()和emit()默認(rèn)用在接下來(lái)的消息中对粪。不同的命名空間可以被具體化到可選擇的可選擇的命名空間參數(shù)上：
@socketio.on('message')
def handle_message(message):
send(message, namespace='/chat')
@socketio.on('message')
def handle_my_sustom_event(json):
emit('my response', json, namespace='/chat')
為了實(shí)現(xiàn)發(fā)送一個(gè)多參數(shù)的活動(dòng)，發(fā)送一個(gè)元組：
def ack():
print('message was received!')
@socketio.on('my event')
def handle_my_custom_event(json):
emit('my response', json, callback=ack)
使用回調(diào)時(shí)穿扳，JavaScript客戶端使用回調(diào)函數(shù)在接收到的信息時(shí)回調(diào)。在客戶端應(yīng)用啟用回調(diào)函數(shù)時(shí)国旷，服務(wù)器會(huì)啟用服務(wù)端相匹配的函數(shù)去響應(yīng)矛物。如果客戶端沒(méi)有回調(diào)任何值，這些將會(huì)作為服務(wù)端的響應(yīng)被提供跪但。
客戶端的應(yīng)用同樣要求一個(gè)來(lái)自服務(wù)端的確認(rèn)信息履羞。如果服務(wù)端想為一次響應(yīng)提供一個(gè)參數(shù)，它必須要在活動(dòng)處理函數(shù)中被返回屡久。
@socketio.on('my event')
def handle_my_custom_event(json):
# ... handle the event
return 'foo', 'bar', 123 # client callback will receive these 3 arguments
