在 GoFrame Vue3 后台管理框架的开发中即时通讯IM是一个高频需求——从站内信到客服系统从通知推送到协作消息都离不开 WebSocket 长连接。XYGo Admin 基于 gorilla/websocket 实现了一套完整的即时通讯体系从连接管理、消息路由到前端客户端封装覆盖了 IM 场景的全链路。本文从架构到代码逐一拆解。一、WebSocket 基础设施Hub 模式管理连接XYGo Admin 的 WebSocket 层采用了经典的 Hub 模式核心目录结构如下internal/websocket/├── init.go # Start() 启动 Hub、WsHandler 处理连接├── client.go # 客户端连接封装├── manager.go # Hub 管理器SendToUser/IsUserOnline├── router.go # 消息路由分发└── model.go # WsResponse 等数据结构连接建立流程清晰1. 前端发起 WebSocket 连接到 /socket/ 端点2. WsAuth 中间件进行 JWT 鉴权3. WsHandler 创建 Client 实例4. Client 注册到 Hub Manager5. 开始收发消息这种设计将连接管理与业务逻辑解耦新增消息类型只需注册对应路由无需改动基础设施。二、聊天业务从会话到推送的全流程即时通讯的核心业务逻辑在 internal/logic/chat/chat.go 中核心 API 覆盖了 IM 的完整生命周期| 功能 | 方法 | 说明 ||------|------|------|| 会话列表 | Sessions | 获取单聊/群聊会话列表 || 创建会话 | CreateSession | 单聊去重 群聊系统消息 || 删除会话 | DeleteSession | 软删除仅对当前用户 || 消息列表 | Messages | 游标分页 发送者信息 || 发送消息 | SendMessage | 写入 DB 更新未读 WS 推送 || 标记已读 | MarkRead | 标记已读 推送已读回执 || 联系人 | Contacts | 含部门/岗位/在线状态 || 群聊管理 | GroupUpdate | 改名/加人/踢人 || 未读总数 | UnreadTotal | 所有会话未读消息总数 |发送消息时SendMessage 一次性完成三件事写入数据库、更新未读计数、通过 WebSocket 实时推送——消息落库与推送是原子的不会出现「推送成功但数据丢失」的问题。三、扩展机制自定义 WebSocket 事件对于需要实时推送的业务扩展如订单通知、库存预警可以在扩展的 module.go 中注册自定义 WebSocket 事件goimport (xygo/internal/websocket)func init() {// 注册自定义事件处理器websocket.RegisterEvent(shop.orderNotify, handleOrderNotify)websocket.RegisterEvent(shop.stockAlert, handleStockAlert)}func handleOrderNotify(client *websocket.Client, req *websocket.WsRequest) {client.SendMsg(websocket.NewResponse(shop.orderNotify, map[string]interface{}{orderId: 12345,status: paid,}))}核心 API 一览- websocket.RegisterEvent(event, handler) — 注册事件处理器- client.SendMsg(response) — 向当前客户端发消息- websocket.Manager.Broadcast(response) — 全量广播- websocket.SendToUser(userType, userId, response) — 精准推送到指定用户事件名采用 {扩展名}.{事件名} 格式如 shop.orderNotify避免不同扩展间冲突。四、前端 WebSocket 客户端生产级封装前端客户端位于 web/src/utils/socket/index.ts具备生产环境需要的完整特性-单例模式全局只维护一个 WebSocket 连接-心跳检测定时发送 ping 保持长连接-指数退避重连断线后自动重连间隔递增-消息队列连接断开时缓存消息恢复后自动发送-连接超时超时自动断开并重试使用方式极简typescriptimport { useWebSocket } from /utils/socketconst ws useWebSocket()ws.connect()ws.send({ type: chat, data: { ... } })ws.onMessage((msg) { ... })五、Nginx 反向代理配置WebSocket 需要特殊的 Nginx 配置来支持协议升级nginxlocation /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;}注意 proxy_read_timeout 需要设置足够长如 86400 秒否则长时间无消息会导致连接被 Nginx 断开。六、实战建议1.JWT 鉴权放在中间件层连接握手阶段完成身份校验后续消息直接路由到业务处理器避免每条消息都重新验证2.消息先落库再推送保证数据可靠性SendMessage 的设计可以作为参考模板3.心跳间隔不要过短建议 30 秒一次既能保活又不会造成服务器压力4.重连策略加退避避免大量客户端同时断线后「惊群」冲击服务器5. 扩展事件用命名空间隔离{扩展名}.{事件名} 的规范可以有效防止事件名冲突XYGo Admin 的 WebSocket 体系从底层连接管理到上层业务 API 再到前端客户端封装形成了一条完整的即时通讯链路。作为基于 GoFrame 的敏捷后台开发框架它把 WebSocket 的复杂性封装成了简洁的 API开发者只需关注业务逻辑。更多细节可查阅 XYGo Admin 官方文档 中的 WebSocket 章节。