vibe_coding/.cursor/skills/websocket-service/SKILL.md

name, version, description

name	version	description
websocket-service	1.0.0	在 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 完整代码