Quart框架中的WebSocket使用指南

曹令琨Iris

于 2025-06-11 09:18:33 发布

阅读量323

点赞数 4

CC 4.0 BY-SA版权

本文链接：https://blog.youkuaiyun.com/gitblog_00251/article/details/148578812

Quart框架中的WebSocket使用指南

quart An async Python micro framework for building web applications. 项目地址: https://gitcode.com/gh_mirrors/qu/quart

WebSocket是现代Web应用中实现实时双向通信的重要技术。作为基于asyncio的Python微框架，Quart为开发者提供了简洁而强大的WebSocket支持。本文将深入讲解如何在Quart应用中高效使用WebSocket。

WebSocket基础用法

在Quart中创建WebSocket端点与创建普通HTTP路由类似，但需要使用@app.websocket装饰器而非@app.route。一个基本的WebSocket处理函数如下：

@app.websocket('/ws')
async def ws():
    while True:
        data = await websocket.receive()
        await websocket.send(data)

这里的websocket对象类似于Flask/Quart中的request对象，是全局可用的。它包含了许多有用的属性，如headers等。

连接控制

手动接受或拒绝连接

WebSocket连接是通过HTTP升级请求建立的，服务器可以选择拒绝连接请求。拒绝连接只需像普通路由函数一样返回响应：

@app.websocket('/ws')
async def ws():
    if not validate_credentials(websocket.authorization):
        return '认证失败', 401
    # 连接会自动在接受或发送数据时被接受
    ...

显式接受连接

虽然Quart会在首次接收或发送数据时自动接受连接，但也可以显式调用accept()方法：

@app.websocket('/ws')
async def ws():
    await websocket.accept()
    ...

高级通信模式

独立收发

基础示例需要客户端先发送消息才能响应。要实现服务器主动推送，需要创建独立的任务：

async def sender():
    while True:
        await websocket.send(generate_data())
        await asyncio.sleep(1)

async def receiver():
    while True:
        data = await websocket.receive()
        process_data(data)

@app.websocket('/ws')
async def ws():
    sender_task = asyncio.create_task(sender())
    receiver_task = asyncio.create_task(receiver())
    await asyncio.gather(sender_task, receiver_task)

asyncio.gather是关键，它确保函数不会提前返回导致连接关闭。

处理断开连接

当客户端断开连接时，会引发CancelledError异常：

@app.websocket('/ws')
async def ws():
    try:
        while True:
            data = await websocket.receive()
            await websocket.send(data)
    except asyncio.CancelledError:
        print("客户端断开连接")
        raise  # 必须重新抛出异常

主动关闭连接

服务器可以主动关闭连接，并指定关闭状态码：

@app.websocket('/ws')
async def ws():
    await websocket.accept()
    if some_condition:
        await websocket.close(1000)  # 正常关闭

数据类型处理

WebSocket协议支持传输二进制数据和文本数据。Quart会自动处理类型转换：

receive()返回的数据类型取决于客户端发送的内容
send()可以接受str或bytes类型参数

混合路由

Quart允许同一路径同时定义WebSocket和HTTP路由：

@app.route("/chat")
async def http_chat():
    return "请使用WebSocket连接"

@app.websocket("/chat")
async def ws_chat():
    ...  # WebSocket处理逻辑

如果只定义WebSocket路由而未定义HTTP路由，Quart会对HTTP请求返回400错误而非404。

测试WebSocket

Quart提供了方便的测试工具：

async def test_websocket():
    test_client = app.test_client()
    async with test_client.websocket('/ws') as test_ws:
        await test_ws.send("test")
        response = await test_ws.receive()
        assert response == "echo: test"

如果WebSocket路由返回HTTP响应，测试客户端会抛出WebsocketResponseError异常。