XYGo Admin 即时通讯与异步任务实战：WebSocket 长连接 + 消息队列驱动后台处理

XYGo Admin 作为基于 GoFrame + Vue3 的开源中后台方案，不仅提供了 CRUD 代码生成、RBAC 权限模型等基础能力，还内置了 WebSocket 即时通讯 和 消息队列异步任务 两套生产级基础设施。本文结合官方文档拆解其架构设计与集成方式。

WebSocket 即时通讯架构

XYGo Admin 基于 gorilla/websocket 实现即时通讯，整体采用经典的 Hub 模式管理连接：

csharp 复制代码

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

连接流程

前端发起 WebSocket 连接后，经过 /socket/ 端点 → WsAuth 中间件完成 JWT 鉴权 → WsHandler 创建 Client 并注册到 Hub Manager → 开始双向收发消息。整条链路清晰，鉴权与业务分离。

前端 WebSocket 客户端

前端客户端位于 web/src/utils/socket/index.ts，具备以下工程化特性：

单例模式：全局只维护一个连接，避免重复建连
心跳检测：定时发送 ping 保持长连接存活
指数退避重连：断线后自动重连，间隔递增，平滑恢复
消息队列：连接断开时缓存消息，恢复后自动发送
连接超时：超时自动断开并重试

调用方式非常简洁：

typescript 复制代码

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

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

聊天业务核心 API

聊天业务逻辑集中在 internal/logic/chat/chat.go，覆盖了完整的 IM 场景：

功能	方法	说明
会话列表	`Sessions`	获取单聊/群聊会话列表
创建会话	`CreateSession`	单聊去重 + 群聊系统消息
删除会话	`DeleteSession`	软删除（仅对当前用户）
消息列表	`Messages`	游标分页 + 发送者信息
发送消息	`SendMessage`	写入 DB + 更新未读 + WS 推送
标记已读	`MarkRead`	标记已读 + 推送已读回执
联系人	`Contacts`	含部门/岗位/在线状态
未读总数	`UnreadTotal`	所有会话未读消息总数

消息队列：异步任务驱动

对于发送邮件、生成报表等耗时操作，XYGo Admin 提供了统一的消息队列基础设施。扩展与主包共用同一套 xygo/internal/library/queue，消费者注册方式、Consumer 接口、投递 API 完全一致。

Consumer 接口

go 复制代码

type Consumer interface {
    GetTopic() string
    Handle(ctx context.Context, msg *Message) error
}

定义消费者与生产消息

在 queues/ 子目录下注册消费者后，投递消息只需一行：

go 复制代码

import "xygo/internal/library/queue"

err := queue.Push("login_log", []byte(`{"userId": 1001}`))
// 延迟消息（驱动支持时）
err := queue.PushDelay("order.timeout", []byte(`{"orderId": 12345}`), 30*60)

Topic 命名规范

扩展的 Topic 必须以扩展名为前缀，保证命名空间隔离：

vbnet 复制代码

shop.order.payment     ✓ 正确（扩展名.模块.动作）
shop.stock.sync        ✓ 正确
order.payment          ✗ 避免（缺少扩展名前缀）

扩展不修改主包的任何消费者，只通过同一套 API 注册自身消费者，所有消费者在同一进程内运行、共享同一队列驱动。

Nginx 反向代理 WebSocket

生产环境通过 Nginx 反代时，需要对 /socket/ 路径做专门配置以支持协议升级：

nginx 复制代码

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;
}

关键点：Upgrade 和 Connection 头必须透传，proxy_read_timeout 需设足够大以避免长连接被 Nginx 主动断开。

小结

XYGo Admin 的 WebSocket 方案从 Hub 管理到前端重连策略都考虑到了生产环境的实际需求，消息队列则为扩展开发提供了标准的异步解耦能力。对于需要即时通讯、异步任务处理的中后台项目，这两套基础设施可以显著降低从零搭建的成本。

查阅 XYGo Admin 官方开发文档