Làm thế nào để xử lý WebSocket trong FastAPI?

Question

Accepted Answer

FastAPI hỗ trợ **WebSocket** cho giao tiếp thời gian thực, hai chiều (chat, cập nhật trực tiếp, thông báo) qua decorator `@app.websocket`. Khác với request-response của HTTP, một kết nối WebSocket vẫn mở, cho phép server và client gửi message tự do.

## Một WebSocket endpoint cơ bản

```python
from fastapi import WebSocket, WebSocketDisconnect

@app.websocket("/ws")
async def websocket_endpoint(websocket: WebSocket):
    await websocket.accept()                  # chấp nhận kết nối
    try:
        while True:
            data = await websocket.receive_text()    # nhận một message từ client
            await websocket.send_text(f"Echo: {data}")  # gửi một message trở lại
    except WebSocketDisconnect:
        print("client disconnected")           # xử lý ngắt kết nối (cleanup)
```

Pattern: `accept()` kết nối, rồi vòng lặp — `receive_text()`/`receive_json()` đọc message, `send_text()`/`send_json()` gửi chúng. Một exception `WebSocketDisconnect` báo hiệu client đã rời đi (nơi bạn cleanup).

## Broadcast tới nhiều client (ví dụ chat)

```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)          # gửi tới TẤT CẢ client đã kết nối

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)        # mọi người nhận được message
    except WebSocketDisconnect:
        manager.disconnect(ws)                  # xóa khi ngắt kết nối
```

Quản lý một danh sách các kết nối đang hoạt động cho phép bạn **broadcast** tới tất cả client — cơ sở của các tính năng chat và cập nhật trực tiếp.

## Lưu ý về mở rộng

```text
⚠️ Kết nối WebSocket là CÓ TRẠNG THÁI và sống trên MỘT instance server.
Để mở rộng trên nhiều instance, dùng một backplane Redis Pub/Sub (hoặc tương tự) để
message/broadcast tới được các client kết nối trên các instance KHÁC.
(Như session, đừng giữ trạng thái kết nối chỉ trong một tiến trình khi mở rộng theo chiều ngang.)
```

## Tại sao điều này quan trọng

WebSocket cho phép các tính năng **thời gian thực, hai chiều** — chat, thông báo trực tiếp, hiện diện (presence), chỉnh sửa cộng tác, dashboard trực tiếp — mà mô hình request-response của HTTP không thể cung cấp (server có thể push tới client, không chỉ phản hồi).

Hiểu hỗ trợ WebSocket của FastAPI có giá trị để xây dựng ứng dụng tương tác hiện đại: decorator `@app.websocket` với vòng lặp accept/receive/send bao quát giao tiếp thời gian thực cơ bản, và quản lý các kết nối đang hoạt động cho phép **broadcast** (cốt lõi của các tính năng đa người dùng như chat).

Nền tảng async của FastAPI phù hợp tốt với WebSocket.

Quan trọng then chốt là **lưu ý về mở rộng**: kết nối WebSocket có trạng thái và gắn với một instance server duy nhất, nên mở rộng trên nhiều instance yêu cầu một **backplane Redis Pub/Sub** để chuyển tiếp message giữa các instance — một cạm bẫy phổ biến, vì (như session) trạng thái kết nối không thể sống trong bộ nhớ của một tiến trình khi chạy nhiều instance.

Biết pattern WebSocket cơ bản, broadcast, xử lý ngắt kết nối, và cân nhắc mở rộng là kiến thức cấp senior quan trọng để xây dựng các trải nghiệm thời gian thực, tương tác ngày càng được mong đợi trong ứng dụng hiện đại.