---
name: websocket-realtime
when: 'WebSocket, 实时推送, 实时通知, 在线状态, 即时通讯, SSE, Server-Sent Events, 消息推送, 长连接'
scope:
  - backend
  - frontend
products:
  - '*'
id: ka-pattern-websocket-realtime
asset_kind: pattern
lifecycle_status: active
authority: supporting
routes:
  - '*'
primary_triggers:
  - WebSocket
  - 实时推送
  - 实时通知
  - 在线状态
  - 即时通讯
  - SSE
  - Server-Sent Events
  - 消息推送
  - 长连接
priority: P2
specificity: 3
version: 1.0.0
last_reviewed: '2026-05-22'
consumes: []
emits: []
secondary_triggers: []
negative_triggers: []
type: pattern
status: active
---

## 决策规则
- WebSocket 连接必须有心跳机制（建议 30s），检测断线并自动重连
- 重连必须使用指数退避策略（1s/2s/4s/8s/max 30s），禁止无限重试
- 消息必须有序号或时间戳，消费端处理乱序和去重
- 连接异常断开时，未确认消息必须有补偿机制（重新拉取 / 离线消息队列）
- 后端推送频率必须有熔断保护，防止消息风暴压垮客户端
- 单向推送优先使用 SSE（更简单），双向通信才使用 WebSocket
- 生产环境 WebSocket 必须通过 Nginx 反向代理，配置超时和连接数限制
- 前端组件卸载时必须关闭 WebSocket 连接，防止内存泄漏
- WebSocket 连接必须有自动重连机制（指数退避策略），断线后自动恢复
- 推送消息必须携带消息 ID 和时间戳，支持客户端去重和排序
- 服务端必须实现消息缓冲，用户短暂离线后重连可获取未读消息
- 推送消息体必须精简（≤ 4KB），大数据通过接口拉取，不通过推送传输
- 必须支持优雅降级（WebSocket → SSE → 轮询），兼容不同网络环境

## 验收项
- [AC-01] 有心跳和自动重连机制
- [AC-02] 重连使用指数退避
- [AC-03] 消息有去重处理
- [AC-04] 组件卸载关闭连接
- [AC-05] 未确认消息有补偿机制
- [AC-06] 自动重连机制
- [AC-07] 消息去重和排序
- [AC-08] 离线消息缓冲
- [AC-09] 降级策略（WS→SSE→轮询）
