كيف تتعامل مع WebSockets في FastAPI؟

Question

Accepted Answer

يدعم FastAPI **WebSockets** للاتصال ثنائي الاتجاه في الوقت الفعلي (الدردشة والتحديثات المباشرة والإشعارات) عبر مزخرف `@app.websocket`. بخلاف نموذج 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 للطلب والاستجابة توفيره (يمكن للخادم أن يدفع إلى العملاء وليس فقط الرد).

فهم دعم WebSocket في FastAPI مهم لبناء تطبيقات تفاعلية حديثة: مزخرف `@app.websocket` مع حلقة accept/receive/send تغطي الاتصالات الأساسية في الوقت الفعلي، وإدارة الاتصالات النشطة تمكّن **البث** (جوهر الميزات متعددة المستخدمين مثل الدردشة).

تناسب أساس FastAPI غير المتزامن WebSockets بشكل جيد.

ما يعتبر حاسمًا هو **تحذير التوسع**: اتصالات WebSocket لها حالة وترتبط بمثيل خادم واحد، لذا فإن التوسع عبر مثيلات متعددة يتطلب **Redis Pub/Sub backplane** لنقل الرسائل بين المثيلات — وهي فخ شائع، لأنه (مثل الجلسات) لا يمكن أن تعيش حالة الاتصال في ذاكرة عملية واحدة عند تشغيل مثيلات متعددة.

معرفة نمط WebSocket الأساسي والبث والتعامل مع قطع الاتصال والاعتبار المتعلق بالتوسع مهمة على مستوى المهنيين الأكبر لبناء التجارب الحقيقية والتفاعلية التي يتوقعها المستخدمون بشكل متزايد في التطبيقات الحديثة.