HTTP API 与 WebSocket API 选型
GT-Streaming 提供两套语义相近的 API。v4 起推荐新应用使用 WebSocket API，HTTP API 仍可用于已有系统或极简集成场景。
架构对比
HTTP API 方式：
客户端 ──REST──► 媒体服务
客户端 ──STOMP WebSocket──► 订阅 /user/{token}/queue/strm 等通知
WebSocket API 方式（v4）：
客户端 ──二进制 WebSocket──► 媒体服务（API 调用 + 通知同一连接）
功能对比
| 维度 | HTTP API | WebSocket API |
|---|---|---|
| 调用协议 | REST（JSON） | 二进制 WebSocket 帧 |
| 事件通知 | 需额外建立 STOMP WebSocket | 同一连接推送 |
| token 管理 | HTTP token 与 STOMP 连接需保持一致 | strm-js 统一处理 |
| 保活 | 需自行实现 15 秒定时器 | StrmWsApi 可自动保活 |
| 重连 | HTTP 与 STOMP 分别处理 | StrmWsApi 集成自动重连 |
| 客户端库 | axios + stomp-websocket + 播放器 | strm-js |
| 适用版本 | 全版本 | v4.0+ |
| 推荐度 | 维护既有系统 | 新应用首选 |
何时选 HTTP API
- 已有基于 HTTP + STOMP 的客户端，迁移成本需最小化
- 只需 同步打开 + 单路播放，逻辑简单（见 example-1-live）
- 非浏览器环境且团队更熟悉 REST
注意： 使用 HTTP API 做 异步打开 时，必须订阅 STOMP 通知，并确保 token 与 WebSocket 会话一致。参见 会话与 token。
何时选 WebSocket API
- 新开发 的 Web / 移动端应用
- 需要 多路并发 播放、频繁打开/关闭
- 希望减少 token、WebSocket、保活等样板代码
- 使用 TypeScript / Vue / React 等现代前端栈
与打开模式的关系
两套 API 均支持同步/异步打开实时与回放，规则相同：
| 模式 | 适用 API | 说明 |
|---|---|---|
| 同步 | HTTP / WebSocket | 首次集成最简单；返回后通常可直接播放 |
| 异步 | HTTP / WebSocket | 多路并发更友好；必须处理「流已准备好」通知 |
详见 异步与同步模式。
strm-js 简介
strm-js 提供：
- 常量与 TypeScript 类型定义
StrmWsApi— WebSocket API 操作类（推荐）StrmHttpApi— HTTP API 操作类PlayerWrapper— FLV / HLS 播放器封装
安装：
npm install -S strm-js
API 参考：StrmWsApi、WebSocket API 概述。
迁移建议
| 现状 | 建议 |
|---|---|
| 新立项 | 直接使用 WebSocket API + strm-js |
| HTTP 同步单路播放 | 可继续使用，或逐步迁移 |
| HTTP 异步 + STOMP | 优先评估迁移到 WebSocket API，减少双连接维护 |
| v3 → v4 服务端升级 | 见 迁移到 v4.0 |
示例对照
| 场景 | HTTP API 示例 | WebSocket API 示例 |
|---|---|---|
| 实时播放（同步） | example-1-live | — |
| 实时播放（异步） | example-2-live | ws-example-1-live |
| 远程回放 | example-4-replay | API 文档 ws-replay-open |