XYGo Admin WebSocket 即时通讯：从连接到推送全链路解析

用户12575852436
5 阅读3分钟

XYGo Admin WebSocket 即时通讯实战：从连接到推送全链路解析

在 XYGo Admin 这条基于 GoFrame + Vue3 + Element Plus 的技术栈上，即时通讯是一个绕不开的需求——无论是后台管理中的站内信通知，还是业务模块里的实时聊天。本文拆解 XYGo Admin 的 WebSocket 实现，覆盖前后端全链路。

后端：Hub 模式架构

XYGo Admin 的 WebSocket 基础设施基于 gorilla/websocket，采用业界成熟的 Hub 管理模式：

WebSocket 基础设施（internal/websocket/）
├── init.go       # Start() 启动 Hub、WsHandler 处理连接
├── client.go     # 客户端连接封装
├── manager.go    # Hub 管理器（SendToUser / IsUserOnline）
├── router.go     # 消息路由分发
└── model.go      # WsResponse 等数据结构

连接生命周期

前端发起 WebSocket 连接到 /socket/ 端点后，会先经过 JWT 鉴权中间件（WsAuth），验证通过才创建 Client 实例并注册到全局 Hub Manager，完成 "认证 → 注册 → 收发" 三步走。

这种设计将连接管理从业务逻辑中解耦出来，Hub 负责维护所有在线客户端的映射表，业务层只需调用 SendToUser 就能精准推送。

聊天业务实现

聊天逻辑集中在 internal/logic/chat/chat.go，核心能力包括：

功能方法说明
会话列表Sessions单聊/群聊会话
创建会话CreateSession单聊去重 + 群聊系统消息
消息列表Messages游标分页 + 发送者信息
发送消息SendMessage写入 DB + 更新未读 + WS 推送
标记已读MarkRead标记已读 + 已读回执推送
联系人Contacts含部门/岗位/在线状态

消息发送是写扩散模式：先落库保证持久化，再通过 WebSocket 实时推送到目标用户。已读回执同样走 WS 通道，不额外引入轮询。

前端：可靠的客户端封装

前端 WebSocket 客户端在 web/src/utils/socket/index.ts 中实现，关键设计点：

  • 单例模式：全局只维护一个 WebSocket 连接，避免重复握手
  • 心跳检测：定时发送 ping 保持长连接存活
  • 指数退避重连：断线后自动重连，间隔逐步递增，避免雪崩
  • 消息队列：断开期间缓存待发送消息，恢复后自动 flush
  • 连接超时：超时自动断开并重建

使用方式也非常简洁：

import { useWebSocket } from '@/utils/socket'

const ws = useWebSocket()
ws.connect()
ws.send({ type: 'chat', data: { ... } })
ws.onMessage((msg) => { ... })

封装层屏蔽了重连、心跳、队列等底层细节，业务开发只需关注 send 和 onMessage。

扩展机制：自定义事件注册

XYGo Admin 支持在扩展的 module.go 中注册自定义 WebSocket 事件处理器：

package shop

import (
    "xygo/internal/addon"
    "xygo/internal/websocket"
)

func init() {
    websocket.RegisterEvent("shop.orderNotify", handleOrderNotify)
    websocket.RegisterEvent("shop.stockAlert", handleStockAlert)
}

事件命名采用 {扩展名}.{事件名} 格式，避免跨扩展冲突。核心 API 有：

  • RegisterEvent(event, handler) — 注册事件
  • client.SendMsg(response) — 回复当前客户端
  • Manager.Broadcast(response) — 广播给所有在线客户端
  • SendToUser(userType, userId, response) — 精准推送给指定用户

这层扩展机制让 WebSocket 不再只是聊天专用，任何扩展都可以利用它实现自己的实时通信场景——订单通知、库存告警、审批流转……

部署注意事项

如果前面套了 Nginx，记得 WebSocket 需要代理升级配置：

location /socket/ {
    proxy_pass http://127.0.0.1:8000;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_read_timeout 86400;
}

关键是把 HTTP 协议升级为 1.1，并设置 Upgrade 和 Connection 头，否则 Nginx 会按普通 HTTP 处理，WebSocket 握手失败。

小结

XYGo Admin 的 WebSocket 体系从底层 gorilla/websocket 到上层业务逻辑，再到前端客户端的可靠性封装，形成了一套完整的实时通信解决方案。事件注册机制又为扩展提供了可插拔的实时能力，无论是即时聊天还是业务推送，都能在同一套基础设施上运转。

更多技术细节参见 XYGo Admin 开发文档

avatar
文章
阅读
粉丝