XYGo Admin 扩展开发：WebSocket 事件注册与实时推送实战
在实际的企业级后台中，实时推送功能几乎是标配------订单状态变更、库存预警、消息通知，都需要服务端主动推送而不是前端轮询。XYGo Admin 内置了完整的 WebSocket 事件注册机制，让扩展能够以极少的代码接入实时通信能力。
WebSocket 事件注册机制
XYGo Admin 的 WebSocket 模块采用事件驱动设计。每个扩展通过 `websocket.RegisterEvent` 注册自己关心的事件处理器，当客户端（浏览器）发送对应消息时，系统自动路由到注册好的处理函数。
注册时机选在扩展的 `module.go` 的 `init()` 函数中。这与路由挂载是同一层级，确保系统启动时所有事件处理器就位：
```go
package shop
import (
"xygo/internal/addon"
"xygo/internal/websocket"
)
func init() {
addon.Register(addon.Module{
Name: "shop",
Mount: func(s *ghttp.Server) { /* 路由注册 */ },
})
// 注册 WebSocket 事件
websocket.RegisterEvent("shop.orderNotify", handleOrderNotify)
websocket.RegisterEvent("shop.stockAlert", handleStockAlert)
}
```
事件处理函数实现
每个事件处理器接收当前连接的 `websocket.Client` 和请求数据 `websocket.WsRequest`。你可以选择回复当前客户端、广播给所有人、或推送给特定用户：
```go
// 回复当前客户端
func handleOrderNotify(client *websocket.Client, req *websocket.WsRequest) {
client.SendMsg(websocket.NewResponse("shop.orderNotify", mapstringinterface{}{
"orderId": 12345,
"status": "paid",
}))
}
// 广播给所有在线用户
func handleStockAlert(client *websocket.Client, req *websocket.WsRequest) {
websocket.Manager.Broadcast(websocket.NewResponse("shop.stockAlert", mapstringinterface{}{
"message": "部分商品库存不足，请及时补货",
}))
}
// 向指定用户推送
func init() {
// 在业务逻辑中调用
websocket.SendToUser(userType, userId, response)
}
```
核心 API 速查
| 函数 | 说明 |
|------|------|
| `websocket.RegisterEvent(event, handler)` | 注册事件处理器 |
| `client.SendMsg(response)` | 向当前客户端发消息 |
| `websocket.Manager.Broadcast(response)` | 广播给所有在线客户端 |
| `websocket.SendToUser(userType, userId, response)` | 向指定用户发消息 |
| `websocket.NewResponse(event, data)` | 构造成功响应 |
| `websocket.NewErrorResponse(event, code, msg)` | 构造错误响应 |
事件命名规范
事件名使用 `{扩展名}.{事件名}` 格式，避免不同扩展之间冲突：
-
`shop.orderNotify` ✅ 正确
-
`shop.stockAlert` ✅ 正确
-
`orderNotify` ❌ 避免（可能与其他扩展冲突）
如果扩展名为 `crm`，则事件名以 `crm.` 开头；如果扩展名为 `cms`，则事件名以 `cms.` 开头。
适用场景
订单实时通知 ：当用户在后台处理订单时，前端通过 WebSocket 实时接收订单状态变更，无需手动刷新页面。库存预警推送 ：当某个 SKU 库存低于阈值时，系统自动广播给所有运营人员。多终端消息同步：用户在一端操作后，其他已登录设备立即收到同步消息，保证数据一致性。
总结
XYGo Admin 的 WebSocket 事件注册机制让扩展开发者在保持模块独立的前提下，轻松实现实时推送功能。只需三步：在 `module.go` 中注册事件、编写处理函数、前端连接 WebSocket 并发送事件，一套完整的实时通信能力就完成了。
如果需要了解更详细的使用示例，可以参考 XYGo Admin 官方文档 中的 WebSocket 章节。