FastAPI WebSocket实战:从稳健连接到优雅退出的深度解析
如果你已经用FastAPI写过几个WebSocket的“Hello World”示例,但一到生产环境就遇到连接莫名断开、内存悄悄上涨,或者消息偶尔“丢包”的困扰,那么这篇文章正是为你准备的。我们不再重复教科书上的基础定义,而是直接切入那些在真实项目里才会踩到的“坑”,以及如何用更健壮、更优雅的方式填平它们。无论是构建实时聊天应用、数据仪表盘,还是游戏服务器,一个稳定的WebSocket服务都是核心。本文将围绕FastAPI框架,深入探讨从连接握手、消息生命周期管理、到异常处理和资源清理的完整闭环,目标是让你写出的WebSocket服务不仅能跑起来,更能扛得住。
1. 连接建立:超越 await websocket.accept()
很多人以为WebSocket连接就是一行 await websocket.accept(),但实际上,从TCP握手升级到WebSocket协议,再到应用层准备就绪,中间有许多细节决定了连接的初始质量。
1.1 握手阶段的精细化控制
FastAPI的 WebSocket 对象在 accept() 之前,其实已经承载了原始的HTTP请求。这意味着你可以像处理普通HTTP请求一样,进行前置的验证和协商。
from fastapi import FastAPI, WebSocket, WebSocketDisconnect, status
from fastapi.exceptions import HTTPException
import jwt # 示例使用PyJWT
app = FastAPI()
SECRET_KEY = "your-secret-key-here"
@app.websocket("/ws/chat")
async def websocket_endpoint(websocket: WebSocket):
# 1. 检查请求头,例如进行Token认证
token = websocket.headers.get("authorization")
if not token or not token.startswith("Bearer "):
# 在accept之前拒绝连接
await websocket.close(code=status.WS_1008_POLICY_VIOLATION)
return
try:
payload = jwt.decode(token[7:], SECRET_KEY, algorithms=["HS256"])
user_id = payload.get("sub")
except jwt.ExpiredSignatureError:
await websocket.close(code=status.WS_1008_POLICY_VIOLATION)
return
except jwt.InvalidTokenError:
await websocket.close(code=status.WS_1008_POLICY_VIOLATION)
return
# 2. 协商子协议(可选,常用于特定场景如WAMP)
# 客户端可能在请求头中携带 `Sec-WebSocket-Protocol`
# 我们可以选择接受或不接受
subprotocols = websocket.headers.get("sec-websocket-protocol")
# 这里简单选择第一个,实际应根据业务逻辑判断
accepted_protocol = subprotocols.split(", ")[0] if subprotocols else None
# 3. 接受连接,可指定子协议
await websocket.accept(subprotocol=accepted_protocol)
# ... 后续消息处理循环
注意:在
accept()之前调用close()是合法的,这允许你在握手阶段就拒绝不符合条件的连接,避免无效连接占用服务器资源。
1.2 连接状态管理与心跳机制
连接建立后,如何知道它是否还“活着”?尤其是在网络不稳定的移动端或长距离传输场景下,实现一个心跳(Ping/Pong)机制至关重要。FastAPI的WebSocket对象直接支持Ping/Pong帧。
import asyncio
from datetime import datetime
@app.websocket("/ws/with_heartbeat")
async def websocket_with_heartbeat(websocket: WebSocket):
await websocket.accept()
last_pong = datetime.now()
async def heartbeat_checker():
"""后台任务,定期发送Ping并检查Pong响应"""
nonlocal last_pong
while True:
await asyncio.sleep(30) # 每30秒发送一次Ping
try:
# 发送Ping帧
await websocket.send_bytes(b"") # Ping帧通常通过底层库自动处理
# 更直接的方式是使用asyncio.wait_for设置超时接收Pong
# 这里演示一个简单的超时检查逻辑
if (datetime.now() - last_pong).seconds > 45:
print(f"心跳超时,关闭连接")
await websocket.close(code=status.WS_1002_PROTOCOL_ERROR)
break
except Exception:
break # 连接可能已断开
async def message_handler():
"""主消息处理循环"""
nonlocal last_pong
try:
while True:
# 接收消息,这里可以区分文本、二进制或Pong帧
data = await websocket.receive()
if data["type"] == "websocket.receive":
message = data.get("text") or data.get("bytes")
# 处理业务消息...
await websocket.send_text(f"Echo: {message}")
elif data["type"] == "websocket.disconnect":
break
# 注意:FastAPI/Starlette的`receive()`方法返回的字典中,
# Pong帧可能没有单独的类型标识,需要根据具体版本或底层实现调整。
# 一种实践是业务层自己定义心跳消息格式。
except WebSocketDisconnect:
pass
# 启动心跳任务
heartbeat_task = asyncio.create_task(heartbeat_checker())
try:
await message_handler()
finally:
heartbeat_task.cancel() # 确保退出时清理后台任务
try:
await heartbeat_task
except asyncio.CancelledError:
pass
在实际项目中,我更喜欢在应用层定义一种简单的心跳消息格式(如 {"type": "ping"} / {"type": "pong"}),这样兼容性更好,也便于日志记录。
2. 消息收发:处理并发与流量控制
当多个客户端同时发送消息,或者单个客户端发送大量消息时,不加控制的处理会导致服务器资源耗尽或消息顺序错乱。
2.1 使用异步队列解耦生产与消费
直接将消息接收循环和业务处理逻辑耦合在一起,是很多初级实现的通病。一旦业务处理(如数据库写入、调用外部API)变慢,会阻塞整个WebSocket连接,甚至拖垮事件循环。引入 asyncio.Queue 是一个优雅的解决方案。
import asyncio
from collections import defaultdict
from typing import Dict
class ConnectionManager:
def __init__(self):
# 为每个连接ID维护一个消息队列和事件
self.connection_queues: Dict[str, asyncio.Queue] = {}
self.connection_events: Dict[str, asyncio.Event] = {}
async def connect(self, websocket: WebSocket, client_id: str):
await websocket.accept()
self.connection_queues[client_id] = asyncio.Queue(maxsize=100) # 设置队列大小防止内存爆炸
self.connection_events[client_id] = asyncio.Event()
# 启动两个独立的任务:消费者(发送)和生产者(接收)
consumer_task = asyncio.create_task(self._consumer(websocket, client_id))
producer_task = asyncio.create_task(self._producer(websocket, client_id))
# 等待任意一个任务结束(通常意味着连接断开)
done, pending = await asyncio.wait(
[consumer_task, producer_task],
return_when=asyncio.FIRST_COMPLETED
)
# 取消未完成的任务
for task in pending:
task.cancel()
# 清理资源
self._cleanup(client_id)
async def _producer(self, websocket: WebSocket, client_id: str):
"""从WebSocket接收消息并放入队列"""
try:
while True:
data = await websocket.receive_text()
queue = self.connection_queues.get(client_id)
if queue:
try:
# 如果队列已满,等待一段时间(背压控制)
await asyncio.wait_for(queue.put(data), timeout=5.0)
except asyncio.TimeoutError:
# 处理队列满的情况,例如丢弃消息或关闭连接
print(f"客户端 {client_id} 消息队列已满,丢弃消息")
await websocket.close(code=status.WS_1008_POLICY_VIOLATION)
break
except WebSocketDisconnect:
pass
finally:
# 通知消费者可以退出了
event = self.connection_events.get(client_id)
if event:
event.set()
async def _consumer(self, websocket: WebSocket, client_id: str):
"""从队列取出消息并发送给客户端"""
queue = self.connection_queues.get(client_id)
event = self.connection_events.get(client_id)
while True:
# 等待队列中有消息或收到退出事件
try:
# 使用asyncio.wait同时等待消息和退出信号
done, pending = await asyncio.wait(
[
asyncio.create_task(queue.get()),
asyncio.create_task(event.wait())
],
return_when=asyncio.FIRST_COMPLETED
)
if event.is_set():
break # 收到退出信号
# 获取到消息
for task in done:
if task is not pending[0]: # 是消息任务完成了
message = task.result()
# 这里可以插入复杂的业务逻辑,不会阻塞接收消息
processed_message = await self._process_message(message)
await websocket.send_text(processed_message)
# 取消未完成的任务(理论上另一个任务)
for task in pending:
task.cancel()
except asyncio.CancelledError:
break
except Exception as e:
print(f"消费者任务异常: {e}")
break
async def _process_message(self, message: str) -> str:
"""模拟耗时的消息处理"""
await asyncio.sleep(0.1) # 模拟IO操作
return f"Processed: {message}"
def _cleanup(self, client_id: str):
"""清理连接资源"""
self.connection_queues.pop(client_id, None)
self.connection_events.pop(client_id, None)
manager = ConnectionManager()
@app.websocket("/ws/queue")
async def websocket_queue(websocket: WebSocket, client_id: str = "default"):
await manager.connect(websocket, client_id)
这种模式的优势非常明显:
- 解耦:接收消息和发送消息(以及业务处理)在不同的异步任务中,互不阻塞。
- 背压控制:通过有界队列(
maxsize)防止生产者速度远超消费者时导致内存溢出。 - 优雅关闭:通过
Event机制协调多个任务的退出。
2.2 消息序列化与协议设计
直接发送纯文本或JSON字符串虽然简单,但在复杂应用中,定义清晰的通信协议能极大提升可维护性。考虑使用类似以下的结构:
from pydantic import BaseModel, Field
from enum import Enum
import json
from typing import Optional, Any
class MessageType(str, Enum):
CHAT = "chat"
HEARTBEAT = "heartbeat"
NOTIFICATION = "notification"
ERROR = "error"
class WebSocketMessage(BaseModel):
type: MessageType
payload: Optional[Any] = None
request_id: Optional[str] = None # 用于请求-响应匹配
timestamp: int = Field(default_factory=lambda: int(time.time() * 1000))
@app.websocket("/ws/structured")
async def websocket_structured(websocket: WebSocket):
await websocket.accept()
try:
while True:
raw_data = await websocket.receive_text()
try:
message = WebSocketMessage.parse_raw(raw_data)
except ValidationError as e:
# 发送格式错误响应
error_msg = WebSocketMessage(
type=MessageType.ERROR,
payload={"error": "Invalid message format", "detail": str(e)}
)
await websocket.send_text(error_msg.json())
continue
# 根据消息类型路由到不同的处理器
if message.type == MessageType.CHAT:
response = await handle_chat(message.payload)
elif message.type == MessageType.HEARTBEAT:
response = await handle_heartbeat()
else:
response = None
if response:
# 如果原始消息有request_id,在响应中带回
response_msg = WebSocketMessage(
type=MessageType.CHAT if message.type == MessageType.CHAT else message.type,
payload=response,
request_id=message.request_id
)
await websocket.send_text(response_msg.json())
except WebSocketDisconnect:
pass
使用Pydantic进行消息验证和序列化,配合枚举类型,能让代码更健壮,也便于前后端协作。
3. 错误处理:从异常捕获到连接恢复
WebSocket连接中的错误处理远比HTTP复杂,因为连接是持久化的,错误可能发生在任何时刻,且需要区分是连接级错误还是应用级错误。
3.1 系统化异常捕获与分类处理
下面这个表格整理了WebSocket中常见的异常类型及其处理策略:
| 异常类型 | 可能原因 | 检测方式 | 推荐处理策略 |
|---|---|---|---|
| WebSocketDisconnect | 客户端主动关闭或网络断开 | except WebSocketDisconnect: | 清理连接资源,记录日志 |
| ConnectionClosedError | 在已关闭的连接上发送消息 | 发送前检查状态,或捕获特定异常 | 从连接池移除,避免重复操作 |
| RuntimeError (如事件循环关闭) | 服务器关闭或重启 | 全局异常捕获 | 记录严重错误,尝试优雅关闭 |
| TimeoutError | 网络延迟或客户端无响应 | asyncio.wait_for 超时 | 发送Ping确认,超时后关闭连接 |
| PayloadTooLarge | 单条消息超过服务器限制 | 接收消息时异常 | 立即关闭连接(协议错误) |
| 自定义业务逻辑错误 | 消息格式错误、权限不足等 | 业务代码中抛出 | 发送错误消息给客户端,不关闭连接 |
一个综合的错误处理示例:
from starlette.websockets import WebSocketState
@app.websocket("/ws/robust")
async def websocket_robust(websocket: WebSocket, client_id: str = Query(...)):
await websocket.accept()
# 将连接加入全局管理器(如果有)
connection_manager.active_connections[client_id] = websocket
try:
while True:
try:
# 设置接收超时,防止客户端“发呆”占用连接
data = await asyncio.wait_for(
websocket.receive_text(),
timeout=300.0 # 5分钟无消息则超时
)
# 处理消息,可能抛出业务异常
response = await process_message_safely(data, client_id)
# 发送前检查连接状态
if websocket.client_state == WebSocketState.CONNECTED:
await websocket.send_text(response)
else:
break # 连接已不可用,退出循环
except asyncio.TimeoutError:
# 长时间无活动,发送Ping探测
try:
# 尝试发送一个Ping(通过发送空消息或使用底层方法)
# 注意:具体实现取决于FastAPI/Starlette版本
await websocket.send_text(json.dumps({"type": "ping"}))
# 等待Pong响应
pong = await asyncio.wait_for(websocket.receive_text(), timeout=10.0)
if json.loads(pong).get("type") != "pong":
raise ConnectionError("Invalid pong response")
except (asyncio.TimeoutError, ConnectionError):
# 心跳失败,关闭连接
print(f"客户端 {client_id} 心跳失败")
break
except WebSocketDisconnect:
# 客户端正常断开
print(f"客户端 {client_id} 断开连接")
break
except Exception as e:
# 其他未预料异常
print(f"处理客户端 {client_id} 消息时发生未预料错误: {e}")
# 尝试发送错误信息给客户端
try:
error_response = json.dumps({
"type": "error",
"payload": {"message": "Internal server error"}
})
await websocket.send_text(error_response)
except:
pass # 发送也失败了,可能连接已坏
# 根据错误类型决定是否断开
if should_disconnect_on_error(e):
break
# 否则继续处理下一条消息
finally:
# 无论何种方式退出,都要执行清理
connection_manager.active_connections.pop(client_id, None)
# 确保连接被关闭
try:
await websocket.close()
except:
pass # 连接可能已经关闭了
3.2 连接恢复与重连策略
对于客户端来说,网络波动导致的连接中断是常态而非异常。服务端虽然不能直接控制客户端,但可以通过设计支持会话恢复。
import redis.asyncio as redis
from uuid import uuid4
# 使用Redis存储会话状态
redis_client = redis.from_url("redis://localhost:6379", decode_responses=True)
@app.websocket("/ws/with_session")
async def websocket_with_session(
websocket: WebSocket,
session_token: Optional[str] = Query(None)
):
await websocket.accept()
# 检查是否有之前的会话
if session_token and await redis_client.exists(f"ws_session:{session_token}"):
# 恢复会话:获取未送达的消息、用户状态等
pending_messages = await redis_client.lrange(
f"ws_session:{session_token}:queue", 0, -1
)
user_context = await redis_client.get(f"ws_session:{session_token}:context")
# 发送未送达的消息
for msg in pending_messages:
await websocket.send_text(msg)
# 清理旧的队列(已送达)
await redis_client.delete(f"ws_session:{session_token}:queue")
current_session = session_token
else:
# 新会话
current_session = str(uuid4())
# 将会话token发送给客户端,用于重连时使用
await websocket.send_text(json.dumps({
"type": "session_init",
"payload": {"session_token": current_session}
}))
try:
while True:
data = await websocket.receive_text()
message = json.loads(data)
# 处理消息...
response = await handle_message(message)
# 发送响应
await websocket.send_text(response)
# 更新会话活跃时间(用于清理过期会话)
await redis_client.setex(
f"ws_session:{current_session}:alive",
300, # 5分钟过期
"1"
)
except WebSocketDisconnect:
# 连接断开,但保留会话状态一段时间
# 可以将未发送成功的消息存入队列
pass
finally:
# 完全清理(当客户端主动注销或会话过期时)
# 这里可以根据业务逻辑决定何时清理
pass
这种模式在需要保证消息可靠性的场景(如即时通讯、交易通知)中非常有用。客户端在断线重连时携带 session_token,服务端可以恢复用户的未读消息和上下文状态。
4. 连接管理与资源清理
内存泄漏是WebSocket服务最常见的“慢性病”。不活跃的连接没有及时关闭,或者连接相关的资源没有释放,都会导致服务性能逐渐下降直至崩溃。
4.1 实现连接管理器与健康检查
一个健壮的连接管理器应该具备以下功能:
- 跟踪所有活跃连接
- 定期检查连接健康状态
- 清理僵尸连接
- 提供广播和定向发送接口
from typing import Dict, Set
import asyncio
from dataclasses import dataclass
from datetime import datetime, timedelta
@dataclass
class ConnectionInfo:
websocket: WebSocket
user_id: str
connected_at: datetime
last_activity: datetime
metadata: Dict[str, Any] = None
class WebSocketManager:
def __init__(self):
self.active_connections: Dict[str, ConnectionInfo] = {}
self._lock = asyncio.Lock()
self._cleanup_task = None
async def start_cleanup_task(self):
"""启动后台清理任务"""
if self._cleanup_task is None:
self._cleanup_task = asyncio.create_task(self._periodic_cleanup())
async def connect(self, websocket: WebSocket, user_id: str, metadata: Dict = None):
"""注册新连接"""
async with self._lock:
# 如果用户已有连接,先关闭旧的(避免重复登录)
if user_id in self.active_connections:
old_conn = self.active_connections[user_id]
try:
await old_conn.websocket.close(code=status.WS_1000_NORMAL_CLOSURE)
except:
pass
conn_info = ConnectionInfo(
websocket=websocket,
user_id=user_id,
connected_at=datetime.now(),
last_activity=datetime.now(),
metadata=metadata or {}
)
self.active_connections[user_id] = conn_info
# 确保清理任务在运行
await self.start_cleanup_task()
return conn_info
async def update_activity(self, user_id: str):
"""更新用户最后活动时间"""
async with self._lock:
if user_id in self.active_connections:
self.active_connections[user_id].last_activity = datetime.now()
async def disconnect(self, user_id: str):
"""断开指定用户的连接"""
async with self._lock:
if user_id in self.active_connections:
conn_info = self.active_connections.pop(user_id)
try:
await conn_info.websocket.close()
except:
pass
return True
return False
async def send_to_user(self, user_id: str, message: str):
"""向指定用户发送消息"""
async with self._lock:
if user_id in self.active_connections:
conn_info = self.active_connections[user_id]
try:
await conn_info.websocket.send_text(message)
conn_info.last_activity = datetime.now()
return True
except Exception as e:
print(f"向用户 {user_id} 发送消息失败: {e}")
# 发送失败,可能是连接已断开,清理之
await self.disconnect(user_id)
return False
async def broadcast(self, message: str, exclude_user_ids: Set[str] = None):
"""广播消息给所有连接的用户"""
exclude_user_ids = exclude_user_ids or set()
failed_connections = []
async with self._lock:
items = list(self.active_connections.items())
for user_id, conn_info in items:
if user_id in exclude_user_ids:
continue
try:
await conn_info.websocket.send_text(message)
conn_info.last_activity = datetime.now()
except Exception:
failed_connections.append(user_id)
# 清理发送失败的连接
for user_id in failed_connections:
await self.disconnect(user_id)
async def _periodic_cleanup(self):
"""定期清理不活跃的连接"""
while True:
await asyncio.sleep(60) # 每分钟检查一次
now = datetime.now()
inactive_threshold = now - timedelta(minutes=5) # 5分钟无活动视为不活跃
async with self._lock:
to_remove = []
for user_id, conn_info in self.active_connections.items():
if conn_info.last_activity < inactive_threshold:
to_remove.append(user_id)
for user_id in to_remove:
print(f"清理不活跃连接: {user_id}")
conn_info = self.active_connections.pop(user_id)
try:
await conn_info.websocket.close(
code=status.WS_1000_NORMAL_CLOSURE,
reason="Inactive timeout"
)
except:
pass
async def shutdown(self):
"""关闭所有连接(用于服务关闭时)"""
if self._cleanup_task:
self._cleanup_task.cancel()
try:
await self._cleanup_task
except asyncio.CancelledError:
pass
async with self._lock:
for conn_info in self.active_connections.values():
try:
await conn_info.websocket.close(
code=status.WS_1001_GOING_AWAY,
reason="Server shutting down"
)
except:
pass
self.active_connections.clear()
# 全局管理器实例
manager = WebSocketManager()
@app.on_event("shutdown")
async def shutdown_event():
"""应用关闭时清理所有WebSocket连接"""
await manager.shutdown()
4.2 集成到FastAPI应用生命周期
为了让WebSocket服务更健壮,需要将其与FastAPI的应用生命周期挂钩:
from contextlib import asynccontextmanager
from fastapi import FastAPI
@asynccontextmanager
async def lifespan(app: FastAPI):
# 启动时
print("WebSocket服务启动中...")
# 这里可以初始化数据库连接、Redis连接等
yield # 应用运行中
# 关闭时
print("WebSocket服务关闭中...")
await manager.shutdown()
# 这里可以关闭数据库连接等
app = FastAPI(lifespan=lifespan)
@app.websocket("/ws/managed")
async def websocket_managed(
websocket: WebSocket,
user_id: str = Query(...),
token: str = Query(...)
):
# 验证token...
if not validate_token(token, user_id):
await websocket.close(code=status.WS_1008_POLICY_VIOLATION)
return
# 使用管理器注册连接
conn_info = await manager.connect(websocket, user_id, metadata={"ip": websocket.client.host})
try:
while True:
data = await websocket.receive_text()
# 更新活动时间
await manager.update_activity(user_id)
# 处理消息...
response = await process_message(data, user_id)
# 发送响应
await websocket.send_text(response)
except WebSocketDisconnect:
print(f"用户 {user_id} 断开连接")
finally:
# 注意:管理器中的disconnect方法会在新连接建立时自动调用,
# 所以这里不一定需要手动调用,除非有特殊清理逻辑
pass
# 提供一个HTTP端点来查看当前连接状态(用于监控)
@app.get("/connections/status")
async def get_connections_status():
async with manager._lock:
return {
"total_connections": len(manager.active_connections),
"connections": [
{
"user_id": info.user_id,
"connected_at": info.connected_at.isoformat(),
"last_activity": info.last_activity.isoformat(),
"metadata": info.metadata
}
for info in manager.active_connections.values()
]
}
5. 性能优化与生产就绪配置
当WebSocket连接数上升到数百甚至数千时,一些在开发阶段不明显的问题会成为性能瓶颈。
5.1 选择合适的ASGI服务器与配置
FastAPI基于ASGI,你可以选择不同的服务器实现。uvicorn是最常用的,但在生产环境中可能需要调整配置:
# uvicorn_config.py
import multiprocessing
# 服务器配置
workers = multiprocessing.cpu_count() * 2 + 1
worker_class = "uvicorn.workers.UvicornWorker"
# WebSocket特定配置
ws_ping_interval = 20 # 每20秒发送一次Ping
ws_ping_timeout = 30 # 等待Pong响应的超时时间
ws_max_size = 16 * 1024 * 1024 # 最大消息大小16MB
# 启动命令示例:
# uvicorn main:app --host 0.0.0.0 --port 8000 --workers 4 --ws-ping-interval 20 --ws-ping-timeout 30 --ws-max-size 16777216
对于更高并发需求,可以考虑:
hypercorn:支持HTTP/2,对WebSocket有更好的支持daphne:Django Channels的官方服务器,专为WebSocket优化
5.2 连接数限制与负载均衡
当单个实例无法承载所有连接时,需要考虑水平扩展。但WebSocket的有状态特性使得负载均衡变得复杂。
方案一:会话粘滞(Session Affinity) 在负载均衡器(如Nginx、HAProxy)上配置基于IP或Cookie的粘滞会话:
# nginx配置示例
upstream websocket_backend {
ip_hash; # 基于IP的会话粘滞
server backend1.example.com:8000;
server backend2.example.com:8000;
server backend3.example.com:8000;
}
server {
listen 80;
server_name ws.example.com;
location /ws/ {
proxy_pass http://websocket_backend;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
# 重要:增加超时时间
proxy_read_timeout 3600s;
proxy_send_timeout 3600s;
}
}
方案二:使用Redis Pub/Sub进行跨实例通信 当连接分布在不同实例上时,可以通过Redis的发布订阅功能实现跨实例的消息传递:
import redis.asyncio as redis
class DistributedWebSocketManager:
def __init__(self):
self.redis = redis.from_url("redis://localhost:6379", decode_responses=True)
self.local_connections = {} # 本地连接的映射
self.pubsub = self.redis.pubsub()
async def subscribe_to_global(self):
"""订阅全局频道,接收其他实例的消息"""
await self.pubsub.subscribe("websocket:messages")
async for message in self.pubsub.listen():
if message["type"] == "message":
data = json.loads(message["data"])
await self._dispatch_locally(data)
async def send_to_user_global(self, user_id: str, message: str):
"""向用户发送消息(可能在其他实例上)"""
# 先尝试本地发送
if user_id in self.local_connections:
await self.send_to_user_local(user_id, message)
else:
# 发布到Redis,让其他实例处理
await self.redis.publish("websocket:messages", json.dumps({
"type": "direct",
"target_user": user_id,
"message": message
}))
async def broadcast_global(self, message: str):
"""全局广播"""
# 本地广播
await self.broadcast_local(message)
# 通知其他实例也进行广播
await self.redis.publish("websocket:messages", json.dumps({
"type": "broadcast",
"message": message
}))
5.3 监控与日志
生产环境的WebSocket服务需要完善的监控。除了常规的服务器指标(CPU、内存),还需要关注:
# monitoring.py
from prometheus_client import Counter, Gauge, Histogram
import time
# 定义指标
WS_CONNECTIONS_TOTAL = Counter(
'websocket_connections_total',
'Total WebSocket connections',
['path']
)
WS_CONNECTIONS_ACTIVE = Gauge(
'websocket_connections_active',
'Active WebSocket connections',
['path']
)
WS_MESSAGES_RECEIVED = Counter(
'websocket_messages_received_total',
'Total messages received',
['path']
)
WS_MESSAGES_SENT = Counter(
'websocket_messages_sent_total',
'Total messages sent',
['path']
)
WS_MESSAGE_PROCESSING_TIME = Histogram(
'websocket_message_processing_seconds',
'Time spent processing WebSocket messages',
['path'],
buckets=(0.001, 0.005, 0.01, 0.05, 0.1, 0.5, 1.0, 5.0)
)
# 在WebSocket处理器中集成监控
@app.websocket("/ws/monitored")
async def websocket_monitored(websocket: WebSocket):
WS_CONNECTIONS_TOTAL.labels(path="/ws/monitored").inc()
WS_CONNECTIONS_ACTIVE.labels(path="/ws/monitored").inc()
try:
await websocket.accept()
while True:
data = await websocket.receive_text()
WS_MESSAGES_RECEIVED.labels(path="/ws/monitored").inc()
# 记录处理时间
start_time = time.time()
response = await process_message(data)
processing_time = time.time() - start_time
WS_MESSAGE_PROCESSING_TIME.labels(path="/ws/monitored").observe(processing_time)
await websocket.send_text(response)
WS_MESSAGES_SENT.labels(path="/ws/monitored").inc()
except WebSocketDisconnect:
pass
finally:
WS_CONNECTIONS_ACTIVE.labels(path="/ws/monitored").dec()
将这些指标暴露给Prometheus,再配合Grafana仪表板,可以实时监控:
- 当前活跃连接数
- 消息吞吐量
- 消息处理延迟分布
- 错误率
6. 测试策略:从单元测试到压力测试
WebSocket的测试比HTTP接口复杂,因为涉及持久连接和双向通信。
6.1 使用pytest-asyncio进行单元测试
# test_websocket.py
import pytest
from fastapi.testclient import TestClient
import asyncio
from unittest.mock import AsyncMock, MagicMock
@pytest.mark.asyncio
async def test_websocket_connection():
"""测试基本的WebSocket连接"""
from main import app # 你的FastAPI应用
# 使用TestClient测试WebSocket
with TestClient(app) as client:
with client.websocket_connect("/ws/chat") as websocket:
# 测试连接建立
assert websocket.client_state.name == "CONNECTED"
# 测试消息发送和接收
test_message = "Hello, WebSocket!"
websocket.send_text(test_message)
data = websocket.receive_text()
assert data == f"Echo: {test_message}"
@pytest.mark.asyncio
async def test_websocket_authentication():
"""测试需要认证的WebSocket连接"""
with TestClient(app) as client:
# 测试无token连接被拒绝
with pytest.raises(Exception): # 具体异常类型取决于实现
with client.websocket_connect("/ws/secure") as websocket:
pass
# 测试有效token连接成功
valid_token = create_test_token()
with client.websocket_connect(f"/ws/secure?token={valid_token}") as websocket:
assert websocket.client_state.name == "CONNECTED"
@pytest.mark.asyncio
async def test_websocket_reconnect():
"""测试重连逻辑"""
with TestClient(app) as client:
# 第一次连接,获取session token
with client.websocket_connect("/ws/with_session") as websocket1:
# 接收session token
init_msg = websocket1.receive_text()
session_data = json.loads(init_msg)
session_token = session_data["payload"]["session_token"]
# 发送一些消息
websocket1.send_text("Message 1")
response1 = websocket1.receive_text()
# 模拟断开(不调用close,直接退出上下文)
# 使用相同的session token重连
with client.websocket_connect(f"/ws/with_session?session_token={session_token}") as websocket2:
# 应该收到未送达的消息(如果有)
# 这取决于具体实现
pass
6.2 使用Locust进行压力测试
# locustfile.py
from locust import User, task, between, events
import websocket
import json
import time
import threading
class WebSocketUser(User):
wait_time = between(1, 3)
def on_start(self):
"""连接建立时调用"""
self.ws = websocket.WebSocket()
self.connect_time = time.time()
try:
self.ws.connect(f"ws://{self.host}/ws/chat")
self.connected = True
except Exception as e:
self.connected = False
print(f"连接失败: {e}")
@task
def send_message(self):
if not self.connected:
return
start_time = time.time()
try:
# 发送消息
message = json.dumps({"text": f"Test message at {time.time()}"})
self.ws.send(message)
# 接收响应(带超时)
response = self.ws.recv()
response_time = time.time() - start_time
# 记录成功的请求
events.request.fire(
request_type="WS",
name="send_message",
response_time=response_time * 1000, # 转毫秒
response_length=len(response),
exception=None,
context=self.context()
)
except Exception as e:
# 记录失败的请求
events.request.fire(
request_type="WS",
name="send_message",
response_time=(time.time() - start_time) * 1000,
response_length=0,
exception=e,
context=self.context()
)
self.connected = False
def on_stop(self):
"""用户停止时调用"""
if hasattr(self, 'ws'):
self.ws.close()
def context(self):
return {"user": self.id}
# 启动Locust:
# locust -f locustfile.py --host=http://localhost:8000
压力测试时关注的关键指标:
- 最大并发连接数:服务器能保持多少活跃连接
- 消息延迟分布:P50、P95、P99延迟
- 内存增长:长时间运行是否有内存泄漏
- CPU使用率:消息处理是否成为瓶颈
6.3 混沌测试:模拟网络异常
在生产环境中,网络问题随时可能发生。模拟这些异常有助于发现潜在问题:
# chaos_test.py
import asyncio
import random
from unittest.mock import patch, AsyncMock
async def test_websocket_under_chaos():
"""在模拟网络异常的情况下测试WebSocket"""
# 模拟随机断开
original_receive = WebSocket.receive_text
receive_count = 0
async def chaotic_receive(self):
nonlocal receive_count
receive_count += 1
# 每10次接收模拟一次断开
if receive_count % 10 == 0:
raise WebSocketDisconnect()
# 5%的概率模拟超时
if random.random() < 0.05:
await asyncio.sleep(30) # 模拟长时间无响应
raise asyncio.TimeoutError()
# 正常接收
return await original_receive(self)
with patch.object(WebSocket, 'receive_text', chaotic_receive):
# 运行测试,确保应用能处理这些异常
await test_websocket_reconnection()
在实际项目中,我遇到过最棘手的问题不是功能实现,而是那些在高压下才暴露的边界情况。比如,某个客户端异常断开后,服务端没有及时清理连接状态,导致内存缓慢增长,运行一周后服务崩溃。又或者,广播消息时没有做好流量控制,当在线用户突然暴涨时,广播操作阻塞了事件循环,导致所有连接响应变慢。这些经验让我意识到,WebSocket服务的健壮性需要从架构设计之初就考虑,而不是事后修补。
1108



被折叠的 条评论
为什么被折叠?



