你如何在FastAPI中处理WebSockets？

Question

Accepted Answer

FastAPI通过`@app.websocket`装饰器支持**WebSockets**进行实时、双向通信（聊天、实时更新、通知）。与HTTP的请求-响应不同，WebSocket连接保持打开状态，允许服务器和客户端自由地发送消息。

## 基本WebSocket端点

```python
from fastapi import WebSocket, WebSocketDisconnect

@app.websocket("/ws")
async def websocket_endpoint(websocket: WebSocket):
    await websocket.accept()                  # accept the connection
    try:
        while True:
            data = await websocket.receive_text()    # receive a message from the client
            await websocket.send_text(f"Echo: {data}")  # send a message back
    except WebSocketDisconnect:
        print("client disconnected")           # handle disconnection (cleanup)
```

模式：`accept()`连接，然后循环——`receive_text()`/`receive_json()`读取消息，`send_text()`/`send_json()`发送消息。`WebSocketDisconnect`异常表示客户端已断开连接（在此处进行清理）。

## 广播给多个客户端（例如聊天）

```python
class ConnectionManager:
    def __init__(self): self.active: list[WebSocket] = []
    async def connect(self, ws): await ws.accept(); self.active.append(ws)
    def disconnect(self, ws): self.active.remove(ws)
    async def broadcast(self, msg):
        for conn in self.active:
            await conn.send_text(msg)          # send to ALL connected clients

manager = ConnectionManager()

@app.websocket("/chat")
async def chat(ws: WebSocket):
    await manager.connect(ws)
    try:
        while True:
            msg = await ws.receive_text()
            await manager.broadcast(msg)        # everyone gets the message
    except WebSocketDisconnect:
        manager.disconnect(ws)                  # remove on disconnect
```

管理活跃连接列表允许你**广播**给所有客户端——这是聊天和实时更新功能的基础。

## 扩展注意事项

```text
⚠️ WebSocket connections are STATEFUL and live on ONE server instance.
To scale across multiple instances, use a Redis Pub/Sub (or similar) backplane so
messages/broadcasts reach clients connected to OTHER instances.
(Like sessions, don't keep connection state only in one process when scaling horizontally.)
```

## 为什么这很重要

WebSockets启用**实时、双向**功能——聊天、实时通知、在线状态、协作编辑、实时仪表板——这些是HTTP的请求-响应模型无法提供的（服务器可以推送给客户端，而不仅仅是响应）。

理解FastAPI的WebSocket支持对于构建现代交互式应用程序很有价值：`@app.websocket`装饰器配合accept/receive/send循环可以覆盖基本的实时通信，管理活跃连接启用**广播**（多用户功能（如聊天）的核心）。

FastAPI的异步基础很适合WebSockets。

至关重要的是**扩展注意事项**：WebSocket连接是有状态的，绑定到单个服务器实例，因此跨多个实例扩展需要**Redis Pub/Sub反向代理**来中继实例之间的消息——这是一个常见的陷阱，因为（像会话一样）连接状态在运行多个实例时无法存在于一个进程的内存中。

了解基本WebSocket模式、广播、断开连接处理和扩展考虑因素对于构建现代应用程序中越来越多预期的实时、交互式体验的高级开发人员知识至关重要。