Flask-SocketIO 簡單使用指南

歡迎關注個人微信公衆號 AlwaysBeta，更多精彩內容等你來。javascript

Flask-SocketIO 使 Flask 應用程序可以訪問客戶端和服務器之間的低延遲雙向通訊。客戶端應用程序可使用 Javascript，C ++，Java 和 Swift 中的任何 SocketIO 官方客戶端庫或任何兼容的客戶端來創建與服務器的永久鏈接。html

安裝

直接使用 pip 來安裝：java

pip install flask-socketio
複製代碼

要求

Flask-SocketIO 兼容 Python 2.7 和 Python 3.3+。能夠從如下三個選項中選擇此程序包所依賴的異步服務：python

eventlet 性能最佳，支持長輪詢和 WebSocket 傳輸。
gevent 在許多不一樣的配置中獲得支持。gevent 包徹底支持長輪詢傳輸，但與 eventlet 不一樣，gevent 沒有本機 WebSocket 支持。要添加對 WebSocket 的支持，目前有兩種選擇：安裝 gevent-websocket 包爲 gevent 增長 WebSocket 支持，或者可使用帶有 WebSocket 功能的 uWSGI Web 服務器。gevent 的使用也是一種高性能選項，但略低於 eventlet。
也可使用基於 Werkzeug 的 Flask 開發服務器，但須要注意的是，它缺少其餘兩個選項的性能，所以它只應用於簡單的開發環境。此選項僅支持長輪詢傳輸。

擴展會根據安裝的內容自動檢測要使用的異步框架。優先考慮 eventlet，而後是 gevent。對於 gevent 中的WebSocket 支持，首選 uWSGI，而後是 gevent-websocket。若是既未安裝 eventlet 也未安裝 gevent，則使用 Flask 開發服務器。jquery

若是使用多個進程，則進程使用消息隊列服務來協調諸如廣播之類的操做。支持的隊列是 Redis，RabbitMQ以及 Kombu 軟件包支持的任何其餘消息隊列。git

在客戶端，官方 Socket.IO Javascript 客戶端庫可用於創建與服務器的鏈接。還有使用 Swift，Java 和 C ++ 編寫的官方客戶端。非官方客戶端也能夠工做，只要它們實現 Socket.IO協議。github

初始化

如下代碼示例演示如何將 Flask-SocketIO 添加到 Flask 應用程序：web

from flask import Flask, render_template
from flask_socketio import SocketIO

app = Flask(__name__)
app.config['SECRET_KEY'] = 'secret!'
socketio = SocketIO(app)

if __name__ == '__main__':
    socketio.run(app, host='0.0.0.0', debug=True)
複製代碼

以上代碼即完成了一個簡單的 Web 服務器。ajax

socketio.run()函數封裝了 Web 服務器的啓動，並替換了app.run()標準的 Flask 開發服務器啓動。redis

當應用程序處於調試模式時，Werkzeug 開發服務器仍然在內部使用和配置正確socketio.run()。

在生產模式中，若是可用，則使用 eventlet Web 服務器，不然使用 gevent Web 服務器。若是未安裝 eventlet 和gevent，則使用 Werkzeug 開發 Web 服務器。

基於 Flask 0.11 中引入的單擊的命令行界面。此擴展提供了適用於啓動 Socket.IO 服務器的新版本命令。用法示例：flask run

$ FLASK_APP=my_app.py flask run
複製代碼

或者直接使用下面方式，也能夠啓動項目：

$ python2.7 app.py
複製代碼

鏈接事件

Flask-SocketIO 調度鏈接和斷開事件。如下示例顯示如何爲它們註冊處理程序：

@socketio.on('connect', namespace='/test')
def test_connect():
    emit('my response', {'data': 'Connected'})

@socketio.on('disconnect', namespace='/test')
def test_disconnect():
    print('Client disconnected')
複製代碼

鏈接事件處理程序能夠選擇返回False以拒絕鏈接。這樣就能夠在此時對客戶端進行身份驗證。

請注意，鏈接和斷開鏈接事件將在使用的每一個命名空間上單獨發送。

接收消息

使用 SocketIO 時，雙方都會將消息做爲事件接收。在客戶端使用 Javascript 回調。使用 Flask-SocketIO，服務器須要爲這些事件註冊處理程序，相似於視圖函數處理路由的方式。

如下示例爲未命名的事件建立服務器端事件處理程序：

@socketio.on('message')
def handle_message(message):
    print('received message: ' + message)
複製代碼

上面的示例使用字符串消息。另外一種類型的未命名事件使用 JSON 數據：

@socketio.on('json')
def handle_json(json):
    print('received json: ' + str(json))
複製代碼

最靈活的方式是使用自定義事件名稱，在開發過程當中最經常使用的也是這種方式。

事件的消息數據能夠是字符串，字節，整數或 JSON：

@socketio.on('my event')
def handle_my_custom_event(json):
    print('received json: ' + str(json))
複製代碼

自定義命名事件也能夠支持多個參數：

@socketio.on('my event')
def handle_my_custom_event(arg1, arg2, arg3):
    print('received args: ' + arg1 + arg2 + arg3)
複製代碼

Flask-SocketIO 支持 SocketIO 命名空間，容許客戶端在同一物理套接字上覆用多個獨立鏈接：

@socketio.on('my event', namespace='/test')
def handle_my_custom_namespace_event(json):
    print('received json: ' + str(json))
複製代碼

若是未指定名稱空間，'/'則使用具備名稱的默認全局名稱空間。

對於裝飾器語法不方便的狀況，on_event可使用該方法：

def my_function_handler(data):
    pass

socketio.on_event('my event', my_function_handler, namespace='/test')
複製代碼

客戶端能夠請求確認回叫，確認收到他們發送的消息。處理函數返回的任何值都將做爲回調函數中的參數傳遞給客戶端：

@socketio.on('my event')
def handle_my_custom_event(json):
    print('received json: ' + str(json))
    return 'one', 2
複製代碼

在上面的示例中，將使用兩個參數調用客戶端回調函數，'one'和2。若是處理程序函數未返回任何值，則將調用客戶端回調函數而不帶參數。

發送消息

如上一節所示定義的 SocketIO 事件處理程序可使用send()和emit() 函數將回復消息發送到鏈接的客戶端。

如下示例將收到的事件退回給發送它們的客戶端：

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)

@socketio.on('my event')
def handle_my_custom_event(json):
    emit('my response', json)
複製代碼

注意如何send()和emit()分別用於無名和命名事件。

當有命名空間的工做，send()並emit()默認使用傳入消息的命名空間。可使用可選namespace參數指定不一樣的命名空間：

@socketio.on('message')
def handle_message(message):
    send(message, namespace='/chat')

@socketio.on('my event')
def handle_my_custom_event(json):
    emit('my response', json, namespace='/chat')
複製代碼

要發送具備多個參數的事件，請發送元組：

@socketio.on('my event')
def handle_my_custom_event(json):
    emit('my response', ('foo', 'bar', json), namespace='/chat')
複製代碼

SocketIO 支持確認回調，確認客戶端收到了一條消息：

def ack():
    print 'message was received!'

@socketio.on('my event')
def handle_my_custom_event(json):
    emit('my response', json, callback=ack)
複製代碼

使用回調時，Javascript 客戶端會收到一個回調函數，以便在收到消息時調用。客戶端應用程序調用回調函數後，服務器將調用相應的服務器端回調。若是使用參數調用客戶端回調，則這些回調也做爲服務器端回調的參數提供。

廣播

SocketIO 的另外一個很是有用的功能是廣播消息。SocketIO 支持經過此功能broadcast=True可選參數send()和emit()：

@socketio.on('my event')
def handle_my_custom_event(data):
    emit('my response', data, broadcast=True)
複製代碼

在啓用廣播選項的狀況下發送消息時，鏈接到命名空間的全部客戶端都會接收它，包括髮件人。若是未使用名稱空間，則鏈接到全局名稱空間的客戶端將收到該消息。請注意，不會爲廣播消息調用回調。

在此處顯示的全部示例中，服務器響應客戶端發送的事件。但對於某些應用程序，服務器須要是消息的發起者。這對於向客戶端發送通知在服務器中的事件（例如在後臺線程中）很是有用。socketio.send()和socketio.emit()方法可用於廣播到全部鏈接的客戶端：

def some_function():
    socketio.emit('some event', {'data': 42})
複製代碼

請注意，socketio.send()與socketio.emit()在上下文理解上和send()與emit()功能不一樣。另請注意，在上面的用法中沒有客戶端上下文，所以broadcast=True是默認的，不須要指定。

房間

對於許多應用程序，有必要將用戶分組爲能夠一塊兒尋址的子集。最好的例子是具備多個房間的聊天應用程序，其中用戶從他們所在的房間接收消息，而不是從其餘用戶所在的其餘房間接收消息。SocketIO 支持經過房間的概念join_room()和leave_room()功能：

from flask_socketio import join_room, leave_room

@socketio.on('join')
def on_join(data):
    username = data['username']
    room = data['room']
    join_room(room)
    send(username + ' has entered the room.', room=room)

@socketio.on('leave')
def on_leave(data):
    username = data['username']
    room = data['room']
    leave_room(room)
    send(username + ' has left the room.', room=room)
複製代碼

在send()和emit()函數接受一個可選room致使被髮送到全部的都在定房客戶端的消息的說法。

全部客戶端在鏈接時都會被分配一個房間，以鏈接的會話ID命名，能夠從中獲取request.sid。給定的客戶能夠加入任何房間，能夠給出任何名稱。當客戶端斷開鏈接時，它將從其所在的全部房間中刪除。無上下文socketio.send() 和socketio.emit()函數也接受一個room參數，以廣播給房間中的全部客戶端。

因爲爲全部客戶端分配了我的房間，爲了向單個客戶端發送消息，客戶端的會話 ID 能夠用做房間參數。

錯誤處理

Flask-SocketIO還能夠處理異常：

@socketio.on_error() # Handles the default namespace
def error_handler(e):
    pass

@socketio.on_error('/chat') # handles the '/chat' namespace
def error_handler_chat(e):
    pass

@socketio.on_error_default # handles all namespaces without an explicit error handler
def default_error_handler(e):
    pass
複製代碼

錯誤處理函數將異常對象做爲參數。

還可使用request.event變量檢查當前請求的消息和數據參數，這對於事件處理程序外部的錯誤記錄和調試頗有用：

from flask import request

@socketio.on("my error event")
def on_my_event(data):
    raise RuntimeError()

@socketio.on_error_default
def default_error_handler(e):
    print(request.event["message"]) # "my error event"
    print(request.event["args"])    # (data,)
複製代碼

基於類的命名空間

做爲上述基於裝飾器的事件處理程序的替代，屬於命名空間的事件處理程序能夠建立爲類的方法。flask_socketio.Namespace做爲基類提供，用於建立基於類的命名空間：

from flask_socketio import Namespace, emit

class MyCustomNamespace(Namespace):
    def on_connect(self):
        pass

    def on_disconnect(self):
        pass

    def on_my_event(self, data):
        emit('my_response', data)

socketio.on_namespace(MyCustomNamespace('/test'))
複製代碼

使用基於類的命名空間時，服務器接收的任何事件都將調度到名爲帶有on_前綴的事件名稱的方法。例如，事件my_event將由名爲的方法處理on_my_event。若是收到的事件沒有在命名空間類中定義的相應方法，則忽略該事件。基於類的命名空間中使用的全部事件名稱必須使用方法名稱中合法的字符。

爲了方便在基於類的命名空間中定義的方法，命名空間實例包括類中的幾個方法的版本，flask_socketio.SocketIO當namespace沒有給出參數時，這些方法默認爲正確的命名空間。

若是事件在基於類的命名空間中具備處理程序，而且還有基於裝飾器的函數處理程序，則僅調用修飾的函數處理程序。

測試

以上是做爲官網文檔的翻譯，下面來講說寫完了代碼以後，應該怎麼來調試。

<script type="text/javascript" src="//cdnjs.cloudflare.com/ajax/libs/socket.io/1.3.6/socket.io.min.js"></script>
<script type="text/javascript" charset="utf-8">
    var socket = io.connect('http://' + document.domain + ':' + location.port);
    socket.on('connect', function() {
        socket.emit('my event', {data: 'I\'m connected!'});
    });
</script>
複製代碼

使用 JavaScript 來鏈接服務端，這裏說一個我遇到的問題，最開始使用的是 jsbin 來測試，但怎麼都連不到後端，緣由就是 jsbin 是 HTTPS 的，而個人請求是 HTTP，因而仍是老老實實寫了一個 HTML 文件，源碼能夠直接在 Github 下載。

<!DOCTYPE HTML>
<html>
<head>
    <title>Flask-SocketIO Test</title>
    <script type="text/javascript" src="//code.jquery.com/jquery-1.4.2.min.js"></script>
    <script type="text/javascript" src="//cdnjs.cloudflare.com/ajax/libs/socket.io/1.3.5/socket.io.min.js"></script>
    <script type="text/javascript" charset="utf-8"> $(document).ready(function() { namespace = '/test'; var socket = io.connect(location.protocol + '//' + document.domain + ':' + location.port + namespace); socket.on('connect', function() { socket.emit('my_event', {data: 'I\'m connected!'}); }); socket.on('my_response', function(msg) { $('#log').append('<br>' + $('<div/>').text('Received #' + msg.count + ': ' + msg.data).html()); }); $('form#emit').submit(function(event) { socket.emit('my_event', {data: $('#emit_data').val()}); return false; }); }); </script>
</head>
<body>
    <h1>Flask-SocketIO Test</h1>
    <p>Async mode is: <b>{{ async_mode }}</b></p>
    <h2>Send:</h2>
    <form id="emit" method="POST" action='#'>
        <input type="text" name="emit_data" id="emit_data" placeholder="Message">
        <input type="submit" value="Echo">
    </form>
    <h2>Receive:</h2>
    <div id="log"></div>
</body>
</html>
複製代碼

有了這個頁面以後，就能夠直接在瀏覽器中輸入 http://127.0.0.1:5000 訪問服務端了，更多功能能夠隨意折騰。

相關文檔：

github.com/miguelgrinb…

flask-socketio.readthedocs.io/en/latest/

windrocblog.sinaapp.com/?p=1628

zhuanlan.zhihu.com/p/31118736

letus.club/2016/04/10/…