FastAPI'de WebSocket'ları nasıl işlersiniz?

Question

Accepted Answer

FastAPI, `@app.websocket` dekoratörü aracılığıyla gerçek zamanlı, çift yönlü iletişim (sohbet, canlı güncellemeler, bildirimler) için **WebSocket** desteği sunar. HTTP'nin istek-yanıt modelinden farklı olarak, bir WebSocket bağlantısı açık kalır ve sunucu ile istemci mesajları serbestçe gönderebilir.

## Temel bir WebSocket endpoint'i

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

Desen: bağlantıyı `accept()` ile kabul edin, ardından döngüye girin — `receive_text()`/`receive_json()` mesajları okur, `send_text()`/`send_json()` mesajları gönderir. Bir `WebSocketDisconnect` istisnası istemcinin ayrıldığını gösterir (temizlik yapabileceğiniz yer).

## Birden fazla istemciye yayınlama (örneğin sohbet)

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

Aktif bağlantıların bir listesini yönetmek, tüm istemcilere **yayınlama** yapmanızı sağlar — bu, sohbet ve canlı güncelleme özelliklerinin temelini oluşturur.

## Ölçeklendirme uyarısı

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

## Neden önemli

WebSocket'lar **gerçek zamanlı, çift yönlü** özellikler — sohbet, canlı bildirimler, varlık (presence), işbirlikçi düzenleme, canlı panolar — sağlar, bunlar HTTP'nin istek-yanıt modelinin sağlayamayacağı şeylerdir (sunucu istemcilere ileti gönderebilir, sadece yanıt vermekle sınırlı değildir).

FastAPI'nin WebSocket desteğini anlamak, modern etkileşimli uygulamalar geliştirmek için değerlidir: `@app.websocket` dekoratörü accept/receive/send döngüsü ile temel gerçek zamanlı iletişimi kapsar ve aktif bağlantıları yönetmek **yayınlamayı** sağlar (sohbet gibi çok kullanıcılı özelliklerin çekirdeği).

FastAPI'nin async temeli WebSocket'lara çok uygun.

Kritik olarak önemli olan **ölçeklendirme uyarısıdır**: WebSocket bağlantıları durum taşıyan ve tek bir sunucu örneğine bağlı olduğundan, birden fazla örnek arasında ölçeklendirme, örnekler arasında mesajları iletmek için bir **Redis Pub/Sub arka planı** gerektirir — yaygın bir tuzak, çünkü (oturumlar gibi) birden fazla örnek çalıştırırken bağlantı durumu bir işlemin belleğinde yaşayamaz.

Temel WebSocket deseni, yayınlama, bağlantı kesme işleme ve ölçeklendirme dikkate almayı bilmek, modern uygulamalarda giderek beklenen gerçek zamanlı, etkileşimli deneyimler geliştirmek için önemli üst düzey bilgidir.