EchoChat/docs/api/frontend/websocket.md

前端 WebSocket 事件协议

完整的 WebSocket 协议文档见 websocket.md 本文档补充前端联系人模块使用的 WebSocket 事件及对接说明

---

连接管理

连接地址

环境	地址
开发环境	ws://localhost:8085/ws?token=<access_token>
生产环境	wss://api.echochat.com/ws?token=<access_token>

前端实现

• 连接服务： frontend/src/services/websocket.js（WebSocketService 单例）
• 状态管理： frontend/src/store/websocket.js（Pinia Store）
• 联系人监听： frontend/src/store/contact.js（initWsListeners）

心跳与重连

• 心跳间隔：30 秒
• 重连策略：指数退避 1s → 2s → 4s → 8s → 16s → 最大 30s
• 连接时自动发送 heartbeat 事件

---

联系人相关事件

heartbeat

方向： 客户端 → 服务端

说明： 心跳消息，服务端收到后续期在线状态 TTL

发送格式：

{
    "event": "heartbeat",
    "data": {}
}

---

notify.friend.request

方向： 服务端 → 客户端

说明： 收到新的好友申请推送

data 内容：

{
    "friendship_id": 5,
    "from_user_id": 2,
    "from_nickname": "李四",
    "from_avatar": "",
    "message": "我是你的同事"
}

前端处理： contactStore.initWsListeners 监听此事件，自动刷新待处理申请列表

---

contact.request.accepted

方向： 服务端 → 客户端

说明： 好友申请被对方接受的通知

data 内容：

{
    "friendship_id": 5,
    "user_id": 1,
    "username": "zhangsan",
    "nickname": "张三"
}

前端处理： contactStore.initWsListeners 监听此事件，自动刷新好友列表

---

user.status.online

方向： 服务端 → 客户端

说明： 好友上线通知

data 内容：

{
    "user_id": 2,
    "nickname": "李四"
}

前端处理： 更新 contactStore.onlineMap 和好友列表中对应用户的 is_online 状态

---

user.status.offline

方向： 服务端 → 客户端

说明： 好友离线通知

data 内容：

{
    "user_id": 2
}

前端处理： 更新 contactStore.onlineMap 和好友列表中对应用户的 is_online 状态

---

事件监听代码示例

import { useContactStore } from '@/store/contact'
import { useWebSocketStore } from '@/store/websocket'

const contactStore = useContactStore()
const wsStore = useWebSocketStore()

// 建立 WebSocket 连接
wsStore.connect()

// 初始化联系人事件监听
contactStore.initWsListeners()

以上代码会自动监听 notify.friend.request、contact.request.accepted、user.status.online、user.status.offline 四个事件。