Skip to content

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

新增一个业务消息类型的典型步骤如下:

  1. 在业务 schema.py 中定义继承 WebSocketMessage 的消息体
  2. 在 service.py 中实现 WebSocketMessageListener 子类
  3. 在 controller.py 导入处 register_listener(...) 注册
  4. 通过 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 过期或已下线会被握手阶段拒绝