在 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 Manager
5. 开始收发消息

这种设计将连接管理与业务逻辑解耦，新增消息类型只需注册对应路由，无需改动基础设施。

二、聊天业务：从会话到推送的全流程

即时通讯的核心业务逻辑在 `internal/logic/chat/chat.go` 中，核心 API 覆盖了 IM 的完整生命周期：

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

发送消息时，`SendMessage` 一次性完成三件事：写入数据库、更新未读计数、通过 WebSocket 实时推送——消息落库与推送是原子的，不会出现「推送成功但数据丢失」的问题。

三、扩展机制：自定义 WebSocket 事件

对于需要实时推送的业务扩展（如订单通知、库存预警），可以在扩展的 `module.go` 中注册自定义 WebSocket 事件：

```go
import (
"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 保持长连接
- 指数退避重连：断线后自动重连，间隔递增
- 消息队列：连接断开时缓存消息，恢复后自动发送
- 连接超时：超时自动断开并重试

使用方式极简：

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

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

五、Nginx 反向代理配置

WebSocket 需要特殊的 Nginx 配置来支持协议升级：

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

注意 `proxy_read_timeout` 需要设置足够长（如 86400 秒），否则长时间无消息会导致连接被 Nginx 断开。

六、实战建议

1. JWT 鉴权放在中间件层：连接握手阶段完成身份校验，后续消息直接路由到业务处理器，避免每条消息都重新验证
2. 消息先落库再推送：保证数据可靠性，`SendMessage` 的设计可以作为参考模板
3. 心跳间隔不要过短：建议 30 秒一次，既能保活又不会造成服务器压力
4. 重连策略加退避：避免大量客户端同时断线后「惊群」冲击服务器
5. 扩展事件用命名空间隔离：`{扩展名}.{事件名}` 的规范可以有效防止事件名冲突

XYGo Admin 的 WebSocket 体系从底层连接管理到上层业务 API 再到前端客户端封装，形成了一条完整的即时通讯链路。作为基于 GoFrame 的敏捷后台开发框架，它把 WebSocket 的复杂性封装成了简洁的 API，开发者只需关注业务逻辑。更多细节可查阅 XYGo Admin 官方文档 中的 WebSocket 章节。