外观
WebSocket 实时通信
开启与配置
WebSocket 模块位于 app/framework/websocket/,为后端提供一套开箱即用的实时双向通信能力:连接级鉴权、心跳保活、按业务类型分发消息、按用户维度单发/群发,以及基于 Redis 发布/订阅的跨实例集群广播。管理端(module_infra/websocket)在其上提供了一个可运行的 Demo 演示。
WebSocket 由全局开关控制,默认关闭:
python
# app/config/settings.py
WEBSOCKET_ENABLE: bool = False # 是否启用 WebSocket(false 时整体禁用,不挂载路由)路由在 module_infra/router.py 中按此开关挂载,关闭时 /infra/ws 不会被注册:
python
if settings.WEBSOCKET_ENABLE:
from app.api.v1.module_infra.websocket.controller import WebSocketRouter
infra_router.include_router(WebSocketRouter)整体架构
WebSocket 的运行时被拆分为「连接管理」「消息发送」「消息分发」三层,路由层只负责握手鉴权与入口转发。
连接与鉴权
WebSocket 握手阶段没有 HTTP 请求头,因此鉴权 token 通过查询参数传入。路由入口通过 get_current_user_ws 依赖在握手阶段完成与 HTTP 接口完全一致的身份认证(JWT 校验、会话在线校验、滑动续期),认证失败则连接无法建立。
python
@WebSocketRouter.websocket("")
async def websocket_endpoint(
websocket: WebSocket,
auth: Annotated[AuthSchema, Depends(get_current_user_ws)],
redis: Annotated[Redis, Depends(redis_getter_ws)],
) -> None:
await handle_websocket(websocket, auth=auth, redis=redis)redis_getter_ws 用于从 websocket.app.state.redis 获取全局异步 Redis 客户端(WebSocket 场景下无法像 HTTP 那样从 Request 获取)。鉴权通过后的 AuthSchema 携带了 user、session_id 等上下文,供后续连接管理使用。
消息协议
客户端与服务端统一使用 JSON 消息帧通信,定义在 schema.py:
JsonWebSocketMessage:传输层信封,包含type(消息类型,用于服务端路由分发)和content(业务消息体的 JSON 字符串)。WebSocketMessage:业务消息基类,自定义业务消息体可继承它,统一携带type等基础字段。
即一次业务通信是两层 JSON:外层固定为 { "type": "...", "content": "..." },内层 content 再根据具体业务反序列化为对应模型。
连接管理器
manager.py 中的 WebSocketSessionManager(全局单例 websocket_manager)按「用户类型 + 用户 ID」维护连接集合。一个用户可拥有多个连接(多端登录),断开时自动清理。
主要能力:
- 按用户维度维护连接,支持单用户多连接
get_user_sockets获取某用户全部连接;get_all_sockets获取全量在线连接用于群发- 额外维护「会话 ID → 连接」的
_session_registry,支持精确投递到某条连接(send_session)
消息发送器
WebSocketMessageSender 提供三种发送姿态:
send:传入user_id时按用户单发,不传时群发全部在线连接;content为 JSON 字符串send_object:在send基础上自动将 pydantic 模型 / dict 序列化为 JSON 字符串,业务侧更友好send_session:按会话(连接)ID 精确投递到某条连接
发送时会逐个连接捕获「已断开」异常并自动清理失效连接;随后通过 _broadcast 将消息发布到 Redis 通道,触发跨实例广播。
python
sender = WebSocketMessageSender(redis=redis)
# 单发给某个用户
await sender.send_object(UserType.ADMIN.value, "demo-message-receive", receive, user_id=uid)
# 群发给所有在线连接
await sender.send_object(UserType.ADMIN.value, "demo-message-receive", receive)心跳保活
框架内置二进制心跳:客户端发送 ping,服务端回复 pong,连接主循环中透明处理,业务监听器无需关心。
消息监听器与分发
业务模块通过继承 WebSocketMessageListener 抽象基类并注册到分发器,即可处理特定 type 的消息,无需改动框架代码:
get_type():声明监听的消息类型message_class:声明消息体反序列化目标类(默认基类)on_message(session, message):收到对应类型消息时的回调
注册只需在模块导入时调用一次 register_listener(...)。运行时 _dispatch 会解析外层 JSON、找到对应监听器、将 content 反序列化为 message_class 后回调,并对解析/执行异常做兜底日志,避免单条消息拖垮整个连接。
业务示例
管理端提供了一个完整的 Demo(单发/群发聊天),展示端到端链路:
DemoSendMessage(客户端 → 服务端):携带text文本,可选to_user_id(指定接收人单发,留空则群发)DemoReceiveMessage(服务端 → 客户端):携带text、from_user_id、single标记DemoWebSocketMessageListener收到demo-message-send后,根据是否指定接收人调用send_object单发或群发demo-message-receive
新增一个业务消息类型的典型步骤如下:
- 在业务
schema.py中定义继承WebSocketMessage的消息体 - 在
service.py中实现WebSocketMessageListener子类 - 在
controller.py导入处register_listener(...)注册 - 通过
WebSocketMessageSender向目标用户推送
前端接入
前端在 apps/web-ele/src/views/infra/webSocket/index.vue 使用 @vueuse/core 的 useWebSocket 接入,关键点为:
- 连接地址:
${VITE_BASE_URL}/infra/ws将http替换为ws,并拼接?token=${accessToken} - 开启
autoReconnect与heartbeat(对应后端 ping/pong) - 发送时先 JSON 化业务内容,再 JSON 化整个信封
{ type, content },与后端协议对齐 - 接收时先判断
pong心跳,再按type(demo-message-receive、notice-push等)解析content处理
ts
const server = `${VITE_BASE_URL}/infra/ws`.replace('http', 'ws') + `?token=${accessToken}`;
const { status, data, send, close, open } = useWebSocket(server, {
autoReconnect: true,
heartbeat: true,
});
// 发送:两层 JSON 包装
const jsonMessage = JSON.stringify({
type: 'demo-message-send',
content: JSON.stringify({ text: sendText.value, toUserId }),
});
send(jsonMessage);集群部署与跨实例广播
多实例部署时,单机的 websocket_manager 只能投递到本进程内的连接。框架通过 Redis 发布/订阅补齐这一缺口:
- 每个连接建立后(若注入
redis)会启动一个订阅任务,监听websocket:broadcast通道 - 任意实例调用
send群发时,都会将消息发布到该通道 - 其他实例收到广播后,向各自本机连接投递,实现全实例覆盖
Redis 未配置时,send 仅在本机投递,不影响单机运行。
最佳实践
- 业务消息务必继承
WebSocketMessage并在message_class中声明,让content反序列化得到强类型对象 - 推送时优先使用
send_object而非手动拼 JSON 字符串,避免序列化不一致 - 精确投递到某条连接(如与某次请求强绑定的回执)使用
send_session+session_id - 监听器
on_message内部应自行捕获业务异常,避免异常上抛中断当前连接循环 - 仅在与用户会话体系一致的前提下连接,token 过期或已下线会被握手阶段拒绝