FastAPI에서 WebSocket을 어떻게 처리합니까?

Question

Accepted Answer

FastAPI는 `@app.websocket` 데코레이터를 통해 실시간 양방향 통신(채팅, 실시간 업데이트, 알림)을 위한 **WebSocket**을 지원합니다. HTTP의 요청-응답과 달리, WebSocket 연결은 열린 채로 유지되어, 서버와 클라이언트가 자유롭게 메시지를 보낼 수 있습니다.

## 기본 WebSocket 엔드포인트

```python
from fastapi import WebSocket, WebSocketDisconnect

@app.websocket("/ws")
async def websocket_endpoint(websocket: WebSocket):
    await websocket.accept()                  # 연결 수락
    try:
        while True:
            data = await websocket.receive_text()    # 클라이언트로부터 메시지 수신
            await websocket.send_text(f"Echo: {data}")  # 메시지 회신
    except WebSocketDisconnect:
        print("client disconnected")           # 연결 끊김 처리 (정리)
```

패턴: 연결을 `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)          # 연결된 모든 클라이언트에 전송

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)        # 모두가 메시지를 받음
    except WebSocketDisconnect:
        manager.disconnect(ws)                  # 연결 끊기면 제거
```

활성 연결 목록을 관리하면 모든 클라이언트에 **브로드캐스트**할 수 있습니다. 채팅과 실시간 업데이트 기능의 기초입니다.

## 스케일링 주의 사항

```text
⚠️ WebSocket 연결은 상태를 가지며(stateful) 하나의 서버 인스턴스에 존재합니다.
여러 인스턴스로 확장하려면, 메시지/브로드캐스트가 다른 인스턴스에 연결된
클라이언트에 도달하도록 Redis Pub/Sub(또는 유사한) 백플레인을 사용하세요.
(세션처럼, 수평 확장 시 연결 상태를 한 프로세스에만 두지 마세요.)
```

## 왜 중요한가

WebSocket은 HTTP의 요청-응답 모델이 제공할 수 없는 **실시간 양방향** 기능—채팅, 실시간 알림, 프레즌스, 협업 편집, 실시간 대시보드—을 가능하게 합니다(서버가 응답만이 아니라 클라이언트에 푸시할 수 있음).

FastAPI의 WebSocket 지원을 이해하는 것은 현대적인 대화형 애플리케이션을 구축하는 데 가치가 있습니다: accept/receive/send 루프가 있는 `@app.websocket` 데코레이터가 기본 실시간 통신을 다루고, 활성 연결을 관리하면 **브로드캐스트**(채팅 같은 다중 사용자 기능의 핵심)가 가능합니다.

FastAPI의 async 기반은 WebSocket에 잘 맞습니다.

결정적으로 중요한 것은 **스케일링 주의 사항**입니다: WebSocket 연결은 상태를 가지며 단일 서버 인스턴스에 묶여 있으므로, 여러 인스턴스로 확장하려면 인스턴스 간에 메시지를 중계하는 **Redis Pub/Sub 백플레인**이 필요합니다. (세션처럼) 여러 인스턴스를 실행할 때 연결 상태가 한 프로세스의 메모리에 있을 수 없으므로 흔한 함정입니다.

기본 WebSocket 패턴, 브로드캐스트, 연결 끊김 처리, 스케일링 고려 사항을 아는 것은 현대 애플리케이션에서 점점 더 기대되는 실시간 대화형 경험을 구축하기 위한 중요한 시니어 수준 지식입니다.