SSE 接口

SSE（Server-Sent Events）是 HTML5 提供的服务器推送技术，用于实现实时通信。

连接端点

GET /api/v1/sse/connect?accessToken={token}

连接建立

原生 EventSource

const eventSource = new EventSource(
  `/api/v1/sse/connect?accessToken=${accessToken}`
)

eventSource.onopen = () => {
  console.log('SSE 连接已建立')
}

eventSource.onerror = (error) => {
  console.error('SSE 连接错误:', error)
}

eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data)
  console.log('收到消息:', data)
}

使用 useSse

import { useSse } from '@/composables'

const { connect, disconnect, isConnected } = useSse()

// 建立连接
connect()

// 断开连接
disconnect()

事件类型

系统定义了以下标准事件类型：

事件类型	说明	数据格式
heartbeat	心跳	{ time: timestamp }
dict_change	字典变更	{ typeCode, action }
online_count	在线人数	{ count }
notice	通知公告	{ id, title, type }
message	普通消息	{ from, content }

事件监听

import { useSse } from '@/composables'

const { on, off } = useSse()

// 监听字典变更
on('dict_change', (data) => {
  console.log('字典变更:', data.typeCode)
})

// 监听在线人数
on('online_count', (data) => {
  console.log('当前在线:', data.count)
})

// 移除监听
off('dict_change')

心跳机制

• 客户端每 30 秒发送一次心跳
• 服务端超时时间：60 秒
• 超时后自动断开连接

重连策略

系统内置指数退避重连：

const reconnectConfig = {
  maxAttempts: 5,        // 最大重连次数
  baseDelay: 1000,       // 初始延迟（毫秒）
  maxDelay: 30000,       // 最大延迟（毫秒）
  multiplier: 2          // 延迟倍数
}

重连延迟计算：delay = min(baseDelay * 2^attempt, maxDelay)

示例：

• 第 1 次重连：1 秒
• 第 2 次重连：2 秒
• 第 3 次重连：4 秒
• 第 4 次重连：8 秒
• 第 5 次重连：16 秒

连接状态

interface SseState {
  isConnected: boolean       // 是否已连接
  reconnectAttempts: number  // 当前重连次数
  lastHeartbeat: number     // 最后心跳时间
}

前端集成

详见 useSse Composable。

与 WebSocket 对比

特性	SSE	WebSocket
通信方式	单向（服务器推送）	双向
协议	HTTP	WS/WSS
断线重连	浏览器自动重连	需手动实现
数据格式	文本（UTF-8）	文本/二进制
适用场景	消息推送、通知	聊天、游戏

环境变量

# .env
VITE_APP_SSE_ENDPOINT=http://localhost:8080/api/v1/sse/connect

如果未配置，SSE 功能将自动跳过初始化。

注意事项

1. SSE 只支持 UTF-8 文本，不支持二进制数据
2. 跨域需要服务端配置 CORS
3. IE 浏览器不支持，需要使用 polyfill
4. 建议在用户登录后再建立连接