[翻译] flask-SocketIO

最近开发工作需要用到websocket去替代老办法轮询，因为我们的web系统使用flask搭建，所以使用flask-SocketIO作为我们的websocket方案，因此顺手翻译官方文档

---

Flask-SocketIO 赋予了Flask应用在客户端和服务器之间使用低延迟的双向通讯的能力。客户端可使用任意的SocketIO官方提供的clients库（包括 Javascript, C++, Java及Swift）或者所有兼容的第三方client库与server端建立一个长久连接。

安装##

使用pip安装：

pip install flask-socketio

必备##

Flask-SocketIO兼容ython 2.7 和 Python 3.3+. 这个包中异步services所依赖的可从以下三种中选择:

1.eventlet 是最佳选择, 支持长轮询和WebSocket传输.

2.gevent 在一系列不同的配置中被支持. 长轮询被gevent完全支持,但不同于eventlet, gevent 没有原生的WebSocket支持. 想要增加对WebSocket的支持有两种办法. 安装gevent-websocket 增加gevent对WebSocket的支持或是使用带有WebSocket功能的uWSGI web server.使用gevent也是一个高效的选项，但不如eventlet.

3.基于Werkzeug的Flask 开发环境server也是可以的，不过注意它的性能比不上上面两项，所以它应该只在简单的开发工作流中使用，它只支持长轮询.

这一扩展（即flask-SocketIO）自动检查哪一个异步框架被安装了，从而决定使用哪一个作为它的异步框架。最好是使用eventlet，其次gevent。对于gevent中的WebSocket支持，首选uWSGI，然后是gevent-websocket。如果既没有安装eventlet也没有安装gevent，则使用Flask开发服务器。

如果使用了多进程，一个消息队列将被进程用来协调操作（例如广播），支持的队列有redis，rabbitMQ和其它被 Kombu支持的消息队列。

在客户端一侧，官方Socket.IO Javascript client 库可创建连接到server的连接. 同样也有Swift, Java and 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)

init_app()风格的初始化同样支持。注意Web服务器的启动方式。 socketio.run()函数封装了Web服务器的启动，代替了app.run()标准的Flask开发服务器启动。当应用处于debug模式时，Werkzeug开发服务器仍在socketio.run()中使用并正确配置。在生产模式下使用eventlet Web服务器（如果可用），否则使用gevent Web服务器。如果没有安装eventlet和gevent，则使用Werkzeug development Web服务器。

同样也支持基于click的命令行接口（Flask 0.11引入）。该扩展提供了适用于启动Socket.IO服务器的flask run命令的新版本。用法举例：

$ FLASK_APP=my_app.py flask run

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

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

接收消息##

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

下面的栗子是一个处理未命名事件的服务端事件处理程序

@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

在上面的例子中，客户端回调函数将被两个参数“1”和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（）使用传入消息的名称空间。可以使用可选的命名空间参数来指定不同的命名空间：

@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和optional（可选参数）来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.', 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()函数接受一个可选的房间参数，使得消息被发送到给定房间中的所有客户端。

所有的客户端在连接时被分配一个房间，用连接的会话ID命名，可以从request.sid中获得。一个给定的客户可以加入任何房间，可以给任何名字。当一个客户端断开连接时，它将从它所在的所有房间中移除。上下文无关的socketio.send()和socketio.emit()函数也接受一个房间参数来广播给房间中的所有客户端。

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

连接事件##

Flask-SocketIO也调度连接和断开事件。以下示例显示如何为其注册处理程序：

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

@socketio.on('disconnect', namespace='/chat')
def test_disconnect():
    print('Client disconnected')

连接事件处理程序可以选择返回False来拒绝连接。这样就可以在这个时候验证客户端。 请注意，连接和断开连接事件是在每个使用的命名空间上单独发送的。

基于类的命名空间##

作为上述基于装饰器的事件处理程序的替代方法，属于命名空间的事件处理程序可以创建为类的方法。 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类中几个方法的版本，当没有给出命名空间参数时，默认为适当的命名空间。

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

错误处理##

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

错误处理程序以Exception对象作为参数

当前请求的消息和数据参数也可以使用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,)

用nginx 做WebSocket的反向代理

你可能会使用nginx做前端反向代理，但是只有nginx 1.4及以上版本支持websocket的代理，下面是代理http和websocket请求的基本配置：

server {
    listen 80;
    server_name _;

    location / {
        include proxy_params;
        proxy_pass http://127.0.0.1:5000;
    }

    location /socket.io {
        include proxy_params;
        proxy_http_version 1.1;
        proxy_buffering off;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "Upgrade";
        proxy_pass http://127.0.0.1:5000/socket.io;
    }
}

下面的栗子增加了对多worker servers的负载均衡支持

upstream socketio_nodes {
    ip_hash;

    server 127.0.0.1:5000;
    server 127.0.0.1:5001;
    server 127.0.0.1:5002;
    # to scale the app, just add more nodes here!
}

server {
    listen 80;
    server_name _;

    location / {
        include proxy_params;
        proxy_pass http://127.0.0.1:5000;
    }

    location /socket.io {
        include proxy_params;
        proxy_http_version 1.1;
        proxy_buffering off;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "Upgrade";
        proxy_pass http://socketio_nodes/socket.io;
    }
}

虽然上述示例可以作为初始配置，但请注意，nginx作为生产环境需要更完整的配置，涵盖其他部署方面，如提供静态文件资源和SSL支持。

使用多worker##

Flask-SocketIO从release 2.0版本开始支持在负载均衡器下的多worker模式。部署多个worker使得使用Flask-SocketIO的应用程序能够在多个进程和主机之间传播客户端连接，并以这种方式进行扩展以支持大量的并发客户端。

使用多workers需要满足以下两个要求：

1.负载均衡器必须配置为可以把来自给定客户端的所有HTTP请求始终转发给同一个worker。这有时被称为“粘性会话”（sticky sessions）。对于nginx，使用ip_hash指令来实现这一点。 Gunicorn不能在多worker模式下使用，因为其负载平衡器算法不支持粘性会话

2.由于每个server只管理一部分的客户端连接，所以必须要有一个消息队列用来协调处理复杂的操作，例如广播和聊天室功能

使用消息队列需要安装一些依赖：

1.对于Redis，redis包需要安装(pip install redis)

2.对于RabbitMQ，kombu包需要安装(pip install kombu)

3.对于其他kombu支持的消息队列，查看Kombu documentation去寻找需要哪些依赖

4.如果使用了gevent或eventlet，那么通常需要修补Python标准库来强制消息队列包使用协程友好的函数和类

要启动多个Flask-SocketIO服务器，必须首先确保你有消息队列服务正在运行。要启动Socket.IO服务器并将其连接到消息队列，请将message_queue参数添加到SocketIO构造函数中：

socketio = SocketIO(app, message_queue='redis://')

message_queue参数的值是使用的队列服务的连接URL。对于在与server相同的主机上运行的redis队列，可以使用'redis：//'URL。同样，对于默认的RabbitMQ队列，可以使用'amqp：//'URL。 Kombu软件包有一个documentation section，描述了所有受支持队列的URL格式

从外部进程发布##

对于许多类型的应用程序，有必要从不是SocketIO server的进程发出事件，例如Celery worker。如果将SocketIO server配置为按照上一节所述在消息队列中进行侦听，则其他任何进程都可以创建自己的SocketIO实例并使用它来以与server相同的方式发出事件。

例如，对于在eventlet Web server上运行并使用Redis消息队列的应用程序，以下Python脚本向所有客户端广播一个事件：

   socketio.emit('my event', {'data': 'foo'}, namespace='/test')```
以这种方式使用SocketIO实例时，Flask应用程序实例不会传递给构造函数。
SocketIO的通道参数可用于通过消息队列选择特定的通信通道。当有多个独立的SocketIO服务共享相同的队列时，需要使用自定义通道名称。
当使用eventlet或gevent时，Flask-SocketIO不适用monkey patching，但是在处理消息队列时，如果Python标准库没有做monkey patching，那么与消息队列服务对话的Python包很可能会挂起。
需要注意的是，想要连接到SocketIO服务器的外部进程不需要像主服务器那样使用eventlet或gevent。服务器使用协程框架，但外部进程不需要，例如Celery workers不需要被配置成使用gevent或eventlet，但是如果你的外部进程出于任何原因确实使用了协程框架，那么可能需要monkey patching，以便消息队列能访问协程友好的函数和类。