Как вы работаете с WebSockets в FastAPI?

Question

Accepted Answer

FastAPI поддерживает **WebSockets** для real-time, двусторонней коммуникации (чат, живые обновления, уведомления) через декоратор `@app.websocket`. В отличие от request-response HTTP, соединение WebSocket остаётся открытым, позволяя серверу и клиенту свободно отправлять сообщения.

## Базовый endpoint 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 включают **real-time, двусторонние** функции — чат, живые уведомления, присутствие, совместное редактирование, живые панели — которые модель request-response HTTP не может предоставить (сервер может отправлять клиентам, а не только отвечать).

Понимание поддержки WebSocket в FastAPI ценно для создания современных интерактивных приложений: декоратор `@app.websocket` с циклом accept/receive/send охватывает базовую real-time коммуникацию, а управление активными соединениями включает **трансляцию** (основу многопользовательских функций, таких как чат).

Асинхронная архитектура FastAPI хорошо подходит для WebSockets.

Критически важно **замечание о масштабировании**: соединения WebSocket являются stateful и привязаны к единственному экземпляру сервера, поэтому масштабирование на несколько экземпляров требует **Redis Pub/Sub backplane** для передачи сообщений между экземплярами — распространённая ловушка, так как (как и сессии) состояние соединения не может находиться в памяти одного процесса при запуске нескольких экземпляров.

Знание базового паттерна WebSocket, трансляции, обработки отключения и вопросов масштабирования — это важные знания уровня senior для построения real-time, интерактивных опытов, которые всё чаще ожидаются в современных приложениях.