Jak obsługujesz WebSockets w FastAPI?

Question

Accepted Answer

FastAPI obsługuje **WebSockets** do real-time, dwukierunkowej komunikacji (czat, aktualizacje na żywo, powiadomienia) za pośrednictwem dekoratora `@app.websocket`. W przeciwieństwie do request-response HTTP, połączenie WebSocket pozostaje otwarte, umożliwiając serwerowi i klientowi swobodne wysyłanie wiadomości.

## Podstawowy 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)
```

Wzorzec: `accept()` połączenie, następnie pętla — `receive_text()`/`receive_json()` odczytuje wiadomości, `send_text()`/`send_json()` je wysyła. Wyjątek `WebSocketDisconnect` sygnalizuje, że klient się rozłączył (gdzie sprzątasz).

## Emisja do wielu klientów (np. czat)

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

Zarządzanie listą aktywnych połączeń pozwala **emitować** do wszystkich klientów — podstawę funkcji czatu i aktualizacji na żywo.

## Zastrzeżenie dotyczące skalowania

```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.)
```

## Dlaczego to ważne

WebSockets umożliwiają **real-time, dwukierunkowe** funkcje — czat, powiadomienia na żywo, obecność, edycję wspólną, live dashboards — których model request-response HTTP nie może zapewnić (serwer może wysyłać do klientów, a nie tylko odpowiadać).

Zrozumienie obsługi WebSocketów w FastAPI jest cenne do budowania nowoczesnych interaktywnych aplikacji: dekorator `@app.websocket` z pętlą accept/receive/send obejmuje podstawową komunikację real-time, a zarządzanie aktywnymi połączeniami umożliwia **emisję** (podstawę funkcji wielouserowych, takich jak czat).

Asynchroniczna podstawa FastAPI dobrze nadaje się do WebSocketów.

Zwłaszcza ważne jest **zastrzeżenie dotyczące skalowania**: połączenia WebSocket są stanowe i powiązane z pojedynczą instancją serwera, więc skalowanie na wiele instancji wymaga **Redis Pub/Sub backplane** do przekazywania wiadomości między instancjami — częsta pułapka, ponieważ (jak sesje) stan połączenia nie może żyć w pamięci jednego procesu, gdy uruchomione są wiele instancji.

Znajomość podstawowego wzorca WebSocket, emisji, obsługi rozłączenia i zagadnienia skalowania jest ważną wiedzą na poziomie seniora do budowania doświadczeń real-time i interaktywnych, które są coraz bardziej oczekiwane w nowoczesnych aplikacjach.