---
name: websocket-service
version: 1.0.0
description: "在 Hyperf 中搭建 Swoole WebSocket 服务器。当需要实时通信、消息推送或通知功能时使用。含心跳检测和前端集成。"
---

# Swoole WebSocket Service

## 触发条件

用户需要实时通信功能：通知推送、在线状态、实时数据更新、聊天功能。

## 执行流程

### Phase 0: 加载规范

读取 `.cursor/rules/016-swoole.mdc`、`013-backend.mdc`，提取 WebSocket 配置、协程安全、fd 存储、心跳、认证鉴权。

### Phase 1: 服务端配置

`config/autoload/server.php` 添加 ws 服务，type SERVER_WEBSOCKET，port 环境变量，callbacks ON_HAND_SHAKE/ON_MESSAGE/ON_CLOSE。

### Phase 2: 连接管理器

WebSocketConnectionManager：Redis 存储 fd→userId/serverId，userId→{serverId:fd} 集合。addConnection、removeConnection、getUserConnections、getUserIdByFd、isOnline。支持多服务器。

### Phase 3: WebSocket Controller

OnOpen：query token 验证 JWT，无效 close，addConnection，push connected。OnMessage：ping→pong。OnClose：removeConnection。

### Phase 4: 消息推送服务

WebSocketPushService：pushToUser、pushToUsers、broadcast（Redis publish 跨服）。Inject Sender、ConnectionManager。

### Phase 5: 前端客户端

WebSocketClient：connect(url?token=)、on(type, callback)、心跳 30s、断线指数退避重连。完整实现见 **Tier 3**。

## 验证

1. [ ] WebSocket 在配置端口启动
2. [ ] Token 认证成功才连接
3. [ ] 无效 Token 立即断开
4. [ ] 心跳 30s 正常
5. [ ] 断线自动重连
6. [ ] 连接信息存 Redis
7. [ ] 推送正确到达目标用户

## Tier 3 深度参考

| 文件 | 内容 |
|------|------|
| `references/ws-implementation.md` | 配置、ConnectionManager、Controller、PushService、前端 Client 完整代码 |