一、初始化

以下代码示例展示了如何将 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)

当然，也支持init_app()这种方式的初始化风格。请注意 Web 服务器的启动方式，现在变为socketio.run()，而不是app.run()。
当应用程序处于调试模式时，socketio.run()仍然使用的是Werkzeug 开发服务器。在生产模式下，如果可用，则使用 eventlet 网络服务器，否则使用 gevent 网络服务器。如果未安装 eventlet 和 gevent，则使用 Werkzeug 开发 Web 服务器。

Flask 0.11 中引入的命令可以用于启动基于 Werkzeug 的 Flask-SocketIO 开发服务器，但由于缺乏 WebSocket 支持，不推荐这种启动 方法。此软件包的先前版本包括该命令的自定义版本，该版本 允许在 eventlet 和 gevent 生产服务器上使用 WebSocket，但此功能已停止使用，取而代之的是上面显示的更健壮的socketio.run(app)启动方法。。

应用程序必须向加载 Socket.IO 库并建立连接的客户端提供一个页面：

<script src="https://cdnjs.cloudflare.com/ajax/libs/socket.io/4.0.1/socket.io.js" integrity="sha512-q/dWJ3kcmjBLU4Qc47E4A9kTB4m3wuTY7vkFJDTZKjTs8jhyGQnaUrxa0Ytd0ssMZhbNua9hE+E7Qv1j+DyZwA==" crossorigin="anonymous"></script>
<script type="text/javascript" charset="utf-8">
    var socket = io();
    socket.on('connect', function() {
        socket.emit('my event', {data: 'I\'m connected!'});
    });
</script>

二、接收消息

使用 SocketIO 时，消息作为事件被双方接收。在客户端使用 Javascript 回调。使用 Flask-SocketIO，服务器需要为这些事件注册处理程序，类似于视图函数处理路由的方式。

以下示例为无名事件创建服务器端事件处理程序：

@socketio.on('message')
def handle_message(data):
    print('received message: ' + data)

上面的示例使用字符串消息。另一种无名事件使用 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)

当事件的名称是一个有效的 Python 标识符并且不会与其他定义的符号发生冲突时，@socketio.event装饰器提供了一种更紧凑的语法，从被装饰的函数中获取事件名称：

@socketio.event
def my_custom_event(arg1, arg2, arg3):
    print('received args: ' + arg1 + arg2 + arg3)

命名事件是最灵活的，因为它们不需要包含额外的元数据来描述消息类型。名称message， json，connect以及disconnect被flask-socketio库保留了，不能用于命名事件。

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。如果函数不返回任何值，则前端在回调的时候就收不到任何参数。

三、发送消息

可以使用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 的另一个非常有用的特性是消息的广播。Flask-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。

五、房间

对于许多应用程序，有必要将用户分组为一个子集。最好的例子是一个有多个房间的聊天应用程序，用户从他们所在的一个或多个房间接收消息，但不会从其他用户所在的其他房间接收消息。Flask-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.', to=room)

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

在send()和emit()函数接受一个to参数，可以让在这个房间的客户端都收到消息。

所有客户端在连接时都会被分配一个房间，以连接的会话 ID 命名，可以从request.sid。一个给定的客户端可以加入任何房间，可以给它任何名字。当一个人断开连接，他将自动离开所有房间。socketio.send() 和socketio.emit()函数也接收to参数来发送消息给这个房间的所有客户端。

由于所有客户端都被分配了一个个人房间，为了向单个客户端发送消息，客户端的会话 ID 可以用作to参数。

六、连接事件

Flask-SocketIO 可以监听连接和断开连接事件。以下示例显示了如何为它们注册处理程序：

@socketio.on('connect')
def test_connect(auth):
    emit('my response', {'data': 'Connected'})

@socketio.on('disconnect')
def test_disconnect():
    print('Client disconnected')

auth参数在连接处理程序中是可选的。客户端可以使用它以字典格式传递身份验证数据，例如令牌。如果客户端不提供身份验证详细信息，则此参数设置为 None。如果服务器定义了一个没有这个参数的连接事件处理程序，那么 cient 传递的任何身份验证数据都会被丢弃。

连接事件处理程序可以返回False以拒绝连接，也可以引发ConectionRefusedError。这是为了此时可以对客户端进行身份验证。使用异常时，任何传递给异常的参数都会在错误包中返回给客户端。例子：

from flask_socketio import ConnectionRefusedError

@socketio.on('connect')
def connect():
    if not self.authenticate(request.args):
        raise ConnectionRefusedError('unauthorized!')

请注意，连接和断开连接事件是在每个使用的命名空间上单独发送的。

七、基于类的命名空间

也可以使用基于类的命名空间，命名空间的事件处理程序可以创建为类的方法。将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没有给出参数时，这些方法 默认为正确的命名空间。（原文：As a convenience to methods defined in a class-based namespace, the namespace instance includes versions of several of the methods in the flask_socketio.SocketIO class that default to the proper namespace when the namespace argument is not given.）这个真的不知道如何翻译o(╥﹏╥)o

如果事件在基于类的命名空间中具有处理程序，并且还有基于装饰器的函数处理程序，则仅调用装饰函数处理程序。

八、错误处理

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,)

九、调试和故障排除

为了帮助你调试问题，可以将服务器配置为将日志输出到终端：

socketio = SocketIO(logger=True, engineio_logger=True)

该logger参数控制与 Socket.IO 协议相关的日志记录，同时engineio_logger控制源自低级 Engine.IO 传输的日志。可以将这些参数设置为True将日志输出到stderr，或输出到 与Python的logging包兼容的对象。如果设置为False则会禁用日志记录。

日志记录可以帮助确定连接问题、400 响应、性能不佳和其他问题的原因。