更新记录

1.0.5（2026-05-13）

优化代码逻辑，清理无用文件

1.0.3（2026-05-13）

相关文档更新

1.0.2（2026-05-13）

文件清理，无用代码清理

平台兼容性

uni-app(5.07)

uni-app x(5.07)

itmiao-sse

插件说明

itmiao-sse 是一个跨平台的 Server-Sent Events (SSE) 插件，支持 Android、iOS 和 HarmonyOS 平台。该插件提供了稳定的 SSE 连接管理和流式数据接收功能。

功能特性

• ✅ 支持 SSE 长连接建立
• ✅ 实时流式数据接收（基于 URLSessionDataDelegate / OkHttp EventSource / @ohos.net.http）
• ✅ 多连接管理（支持同时建立多个 SSE 连接）
• ✅ 跨平台兼容（Android、iOS、HarmonyOS）
• ✅ 支持 GET 和 POST 请求方法
• ✅ 支持自定义请求头和请求体
• ✅ 完整的 SSE 协议解析（data、event、id 字段）
• ✅ 连接状态管理和资源清理
• ✅ 防止回调函数被 GC 回收（使用 @UTSJS.keepAlive）

使用方法

导入插件

import { sseConnect, sseOnMessage, sseDisconnect } from '@/uni_modules/itmiao-uts-sse'

建立SSE连接（GET 请求）

sseConnect({
  url: 'https://your-sse-server.com/events',
  headers: new Map([
    ['Authorization', 'Bearer your-token']
  ]),
  timeout: 30000,
  success: (res) => {
    console.log('SSE连接成功, connectionId:', res.connectionId)
    // 保存 connectionId 用于后续操作
    this.connectionId = res.connectionId
  },
  fail: (err) => {
    console.error('SSE连接失败:', err)
  }
})

建立SSE连接（POST 请求 - AI聊天场景）

sseConnect({
  url: 'https://your-ai-server.com/chat',
  method: 'POST',  // 指定 HTTP 方法
  body: JSON.stringify({  // 请求体
    message: '你好',
    userId: '123'
  }),
  headers: new Map([
    ['Content-Type', 'application/json'],
    ['Authorization', 'Bearer your-token']
  ]),
  timeout: 30000,
  success: (res) => {
    console.log('SSE连接成功, connectionId:', res.connectionId)
    this.connectionId = res.connectionId
  },
  fail: (err) => {
    console.error('SSE连接失败:', err)
  }
})

监听SSE消息

// 在连接成功后调用
sseOnMessage({
  connectionId: this.connectionId,  // 使用 sseConnect 返回的 connectionId
  onMessage: (message) => {
    console.log('收到SSE消息:')
    console.log('  data:', message.data)    // 消息内容（必需）
    console.log('  event:', message.event)  // 事件类型（可选）
    console.log('  id:', message.id)        // 消息ID（可选）

    // 如果数据是 JSON 格式，可以解析
    try {
      const jsonData = JSON.parse(message.data)
      console.log('解析后的数据:', jsonData)
    } catch (e) {
      console.log('原始数据:', message.data)
    }
  },
  onError: (error) => {
    console.error('SSE错误:', error.code, error.message)
  },
  onOpen: () => {
    console.log('SSE连接已打开，开始接收消息')
  },
  onClose: () => {
    console.log('SSE连接已关闭')
  }
})

注意：sseOnMessage 必须在 sseConnect 成功后调用，并且需要使用返回的 connectionId。

完整示例（Vue 组件）

<template>
  <view>
    <button @click="connectSSE">连接SSE</button>
    <button @click="disconnectSSE">断开连接</button>
    <view v-for="msg in messages" :key="msg.id">
      <text>{{ msg.data }}</text>
    </view>
  </view>
</template>

<script>
import { sseConnect, sseOnMessage, sseDisconnect } from '@/uni_modules/itmiao-uts-sse'

export default {
  data() {
    return {
      connectionId: '',
      messages: []
    }
  },
  methods: {
    connectSSE() {
      sseConnect({
        url: 'https://your-sse-server.com/events',
        timeout: 30000,
        success: (res) => {
          this.connectionId = res.connectionId
          this.registerMessageListener(res.connectionId)
        },
        fail: (err) => {
          console.error('连接失败:', err)
        }
      })
    },
    registerMessageListener(connectionId) {
      sseOnMessage({
        connectionId: connectionId,
        onMessage: (message) => {
          this.messages.push({
            id: Date.now(),
            data: message.data,
            event: message.event
          })
        },
        onError: (error) => {
          console.error('消息错误:', error)
        }
      })
    },
    disconnectSSE() {
      if (this.connectionId) {
        sseDisconnect({
          connectionId: this.connectionId,
          success: (res) => {
            console.log('断开成功')
            this.connectionId = ''
            this.messages = []
          }
        })
      }
    }
  }
}
</script>

断开SSE连接

sseDisconnect({
  connectionId: 'your-connection-id',
  success: (res) => {
    console.log('SSE断开连接成功:', res)
  },
  fail: (err) => {
    console.error('SSE断开连接失败:', err)
  }
})

API说明

API说明

sseConnect(options: SSEConnectOptions)

建立SSE连接

参数:

返回值: 无（通过 success/fail 回调获取结果）

示例:

sseConnect({
  url: 'https://example.com/sse',
  method: 'POST',
  body: JSON.stringify({ query: 'test' }),
  headers: new Map([['Authorization', 'Bearer token']]),
  success: (res) => {
    console.log('Connection ID:', res.connectionId)
  }
})

sseOnMessage(options: SSEMessageOptions)

注册SSE消息监听器

参数:

注意:

• 必须在 sseConnect 成功后调用
• 使用返回的 connectionId 作为参数
• 该函数使用 @UTSJS.keepAlive 装饰，确保回调不会被 GC 回收

示例:

sseOnMessage({
  connectionId: 'sse_1234567890_1234',
  onMessage: (message) => {
    console.log('Data:', message.data)
    if (message.event) {
      console.log('Event:', message.event)
    }
  }
})

sseDisconnect(options: SSEDisonnectOptions)

断开SSE连接

参数:

示例:

sseDisconnect({
  connectionId: 'sse_1234567890_1234',
  success: (res) => {
    console.log('断开成功:', res.status)
  }
})

注意事项

1. 连接管理

• ✅ 请确保SSE服务器正确配置了CORS策略
• ✅ 在生产环境中请妥善处理连接异常和重连逻辑
• ✅ 及时断开不需要的SSE连接以节省资源
• ✅ Android平台需要网络权限，请在manifest.json中声明

3. 使用流程

1. 调用 sseConnect 建立连接
2. 在 success 回调中获取 connectionId
3. 使用 connectionId 调用 sseOnMessage 注册监听器
4. 在 onMessage 回调中处理接收到的消息
5. 不需要时调用 sseDisconnect 断开连接

4. SSE 协议支持

• ✅ data: 字段 - 消息内容（必需）
• ✅ event: 字段 - 事件类型（可选）
• ✅ id: 字段 - 消息ID（可选）
• ❌ retry: 字段 - 重连时间（暂未实现）

5. 性能优化

• 避免频繁创建和销毁SSE连接
• 及时处理消息，避免阻塞主线程

版本历史

• v1.1.0 (2026-05-13):

  • ✨ 支持 GET 和 POST 请求方法
  • ✨ 支持自定义请求体（body参数）
  • 🐛 修复 SSE 消息无法接收的问题
  • 📝 完善文档和示例代码

• v1.0.0:

  • 🎉 初始版本，支持基本的SSE连接和消息接收功能

技术实现

iOS 平台

• 使用 URLSessionDataDelegate 实现流式数据接收
• 三层引用保持机制防止 GC 回收

Android 平台

• 使用 OkHttp EventSource 实现 SSE 支持
• 与 iOS 端保持一致的 API 和行为

常见问题

Q: 为什么收不到消息？

A: 请检查：

1. 是否在 sseConnect 成功后调用了 sseOnMessage
2. 是否使用了正确的 connectionId
3. 服务端是否正确发送了 SSE 格式的数据（以 \n\n 结尾）

Q: 如何发送 POST 请求？

A: 在 sseConnect 中设置 method: 'POST' 和 body 参数：

sseConnect({
  url: 'https://example.com/chat',
  method: 'POST',
  body: JSON.stringify({ message: 'hello' })
})

Q: 如何处理 JSON 数据？

A: 在 onMessage 回调中解析：

onMessage: (message) => {
  try {
    const data = JSON.parse(message.data)
    // 处理解析后的数据
  } catch (e) {
    console.error('JSON解析失败', e)
  }
}

平台差异说明

HarmonyOS 平台

鸿蒙端使用 @ohos.net.http 模块实现 SSE 功能，具有以下特点：

1. Headers 兼容性：同时支持 Map 类型和普通对象类型的 headers

   // Map 类型（推荐）
   const headers = new Map<string, string>()
   headers.set('Authorization', 'Bearer token')
   
   // 普通对象类型
   const headers = {
    'Authorization': 'Bearer token'
   }

2. 权限配置：插件已自动配置网络权限，无需手动添加

3. 流式数据处理：使用 HttpResponse 回调机制处理流式数据

更多详细信息请查看 HARMONY_README.md

许可证

MIT License