Flask-SocketIO 简单使用指南

Flask-SocketIO 使 Flask 应用程序可以访问客户端和服务器之间的低延迟双向通讯。客户端应用程序可使用 Javascript，C ++，Java 和 Swift 中的任何 SocketIO 官方客户端库或任何兼容的客户端来创建与服务器的永久链接。

安装

直接使用 pip 来安装：

pip install flask-socketio
复制代码

要求

Flask-SocketIO 兼容 Python 2.7 和 Python 3.3+。能够从如下三个选项中选择此程序包所依赖的异步服务：

• 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 开发服务器。

若是使用多个进程，则进程使用消息队列服务来协调诸如广播之类的操做。支持的队列是 Redis，RabbitMQ以及 Kombu 软件包支持的任何其余消息队列 。

在客户端，官方 Socket.IO Javascript 客户端库可用于创建与服务器的链接。还有使用 Swift，Java 和 C ++ 编写的官方客户端。非官方客户端也能够工做，只要它们实现 Socket.IO协议。

初始化

如下代码示例演示如何将 Flask-SocketIO 添加到 Flask 应用程序：

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 服务器。

socketio.run()函数封装了 Web 服务器的启动，并替换了app.run()标准的 Flask 开发服务器启动。

当应用程序处于调试模式时，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/…