# API 参考

<cite>
**本文引用的文件**
- [src/index.ts](file://src/index.ts)
- [src/server.ts](file://src/server.ts)
- [src/websocket.ts](file://src/websocket.ts)
- [src/class/websockethandler.ts](file://src/class/websockethandler.ts)
- [src/class/httphandler.ts](file://src/class/httphandler.ts)
- [src/class/offer.ts](file://src/class/offer.ts)
- [src/class/answer.ts](file://src/class/answer.ts)
- [src/class/candidate.ts](file://src/class/candidate.ts)
- [src/swagger.ts](file://src/swagger.ts)
- [src/signaling.ts](file://src/signaling.ts)
- [client/src/signaling.js](file://client/src/signaling.js)
- [client/src/peer.js](file://client/src/peer.js)
- [test/websockethandler.test.ts](file://test/websockethandler.test.ts)
- [test/httphandler.test.ts](file://test/httphandler.test.ts)
- [package.json](file://package.json)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考量](#性能考量)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)

## 简介
本文件为视频流服务器的完整 API 参考，覆盖以下内容：
- WebSocket 信令 API：连接建立、消息格式、事件类型与实时交互模式
- HTTP 轮询 API：端点规范、请求/响应格式、状态码与错误处理
- Swagger 自动化文档：生成与访问方式
- 信令消息数据结构：Offer、Answer、Candidate 等字段定义与使用场景
- 错误代码与处理指南
- API 使用示例与集成模板

## 项目结构
后端采用 Express 提供 HTTP 服务与静态资源，WebSocket 用于实时信令；HTTP 轮询模式通过 /signaling 路由提供信令存取能力。客户端提供基于 WebSocket 与 HTTP 轮询两种信令实现。

```mermaid
graph TB
subgraph "服务端"
A["Express 应用<br/>src/server.ts"]
B["WebSocket 信令<br/>src/websocket.ts"]
C["HTTP 轮询信令<br/>src/signaling.ts → src/class/httphandler.ts"]
D["数据模型<br/>src/class/offer.ts / answer.ts / candidate.ts"]
E["Swagger 文档<br/>src/swagger.ts"]
end
subgraph "客户端"
F["信令封装(HTTP)<br/>client/src/signaling.js"]
G["信令封装(WebSocket)<br/>client/src/signaling.js"]
H["Peer 连接控制<br/>client/src/peer.js"]
end
A --> B
A --> C
A --> E
B --> D
C --> D
F --> A
G --> B
H --> F
H --> G
```

图表来源
- [src/server.ts:14-89](file://src/server.ts#L14-L89)
- [src/websocket.ts:6-118](file://src/websocket.ts#L6-L118)
- [src/signaling.ts:1-25](file://src/signaling.ts#L1-L25)
- [src/class/httphandler.ts:1-1130](file://src/class/httphandler.ts#L1-L1130)
- [src/class/offer.ts:1-11](file://src/class/offer.ts#L1-L11)
- [src/class/answer.ts:1-8](file://src/class/answer.ts#L1-L8)
- [src/class/candidate.ts:1-12](file://src/class/candidate.ts#L1-L12)
- [src/swagger.ts:16-65](file://src/swagger.ts#L16-L65)
- [client/src/signaling.js:1-292](file://client/src/signaling.js#L1-L292)
- [client/src/peer.js:1-188](file://client/src/peer.js#L1-L188)

章节来源
- [src/server.ts:14-89](file://src/server.ts#L14-L89)
- [src/index.ts:13-109](file://src/index.ts#L13-L109)

## 核心组件
- 服务启动与配置：命令行参数解析、HTTPS/HTTP 选择、日志级别、信令协议类型与通信模式
- Express 服务：CORS、JSON/URL 编码、静态资源、/config、/signaling 路由挂载、Swagger 文档
- WebSocket 信令：连接生命周期、消息分发、广播、心跳与超时处理
- HTTP 轮询信令：会话管理、连接管理、Offer/Answer/Candidate 存取、房间与用户信息查询
- 数据模型：Offer、Answer、Candidate 结构体
- 客户端封装：HTTP 与 WebSocket 两类信令客户端，Peer 连接控制

章节来源
- [src/index.ts:13-109](file://src/index.ts#L13-L109)
- [src/server.ts:14-89](file://src/server.ts#L14-L89)
- [src/websocket.ts:6-118](file://src/websocket.ts#L6-L118)
- [src/class/websockethandler.ts:1-479](file://src/class/websockethandler.ts#L1-L479)
- [src/class/httphandler.ts:1-1130](file://src/class/httphandler.ts#L1-L1130)
- [src/class/offer.ts:1-11](file://src/class/offer.ts#L1-L11)
- [src/class/answer.ts:1-8](file://src/class/answer.ts#L1-L8)
- [src/class/candidate.ts:1-12](file://src/class/candidate.ts#L1-L12)
- [src/swagger.ts:16-65](file://src/swagger.ts#L16-L65)
- [src/signaling.ts:1-25](file://src/signaling.ts#L1-L25)
- [client/src/signaling.js:1-292](file://client/src/signaling.js#L1-L292)
- [client/src/peer.js:1-188](file://client/src/peer.js#L1-L188)

## 架构总览
系统支持两种信令模式：
- WebSocket：低延迟、全双工、事件驱动
- HTTP 轮询：兼容性好、部署简单、适合受限网络环境

```mermaid
sequenceDiagram
participant Client as "客户端"
participant Server as "Express 服务"
participant WS as "WebSocket 信令"
participant HTTP as "HTTP 轮询信令"
Client->>Server : GET /config
Server-->>Client : {useWebSocket, startupMode, logging}
alt WebSocket 模式
Client->>WS : 建立 ws/wss 连接
WS-->>Client : "connect"含 role/polite/participantId
Client->>WS : "offer"/"answer"/"candidate"
WS-->>Client : 广播/定向转发对应信令
else HTTP 模式
Client->>HTTP : PUT "" 创建会话返回 sessionId
Client->>HTTP : PUT "/connection" 创建连接
loop 轮询
Client->>HTTP : GET "" /offer /answer /candidate
HTTP-->>Client : 返回增量信令
end
Client->>HTTP : POST "/offer" /answer /candidate
Client->>HTTP : DELETE "" 关闭会话
end
```

图表来源
- [src/server.ts:25-41](file://src/server.ts#L25-L41)
- [src/websocket.ts:27-115](file://src/websocket.ts#L27-L115)
- [src/class/httphandler.ts:664-696](file://src/class/httphandler.ts#L664-L696)
- [src/class/httphandler.ts:698-828](file://src/class/httphandler.ts#L698-L828)
- [src/class/httphandler.ts:830-998](file://src/class/httphandler.ts#L830-L998)
- [src/signaling.ts:6-24](file://src/signaling.ts#L6-L24)

## 详细组件分析

### WebSocket 信令 API
- 连接建立
  - 客户端通过 ws/wss 连接到服务端
  - 服务端在连接事件中注册处理器，维护连接集合与连接组
- 消息格式与事件类型
  - connect/disconnect：建立/断开连接，包含 connectionId、polite、role、participantId
  - offer/answer/candidate：信令三元组，包含 from、to、data（含 sdp 或 candidate/sdpMid/sdpMLineIndex）、participantId
  - ping/pong：心跳机制
  - broadcast/on-message：广播消息与自定义消息
  - participant-joined/participant-left：多参与者的房间模式事件
- 实时交互模式
  - 公共模式：同一房间内广播
  - 私有模式：host 与特定 participant 或 host 与其他 participants 之间定向转发
- 心跳与超时
  - 服务端周期发送 ping，客户端回 pong；若长时间无活动则断开

```mermaid
sequenceDiagram
participant C as "客户端"
participant S as "WebSocket 信令"
participant H as "处理器(websockethandler)"
C->>S : "connect" {connectionId}
S->>H : onConnect(ws, connectionId)
H-->>C : "connect" {role, polite, participantId}
C->>S : "offer"/"answer"/"candidate"
S->>H : onOffer/onAnswer/onCandidate
H-->>C : 广播/定向转发对应信令
C->>S : "ping"
S-->>C : "pong"
S->>H : 更新 lastActivity
C->>S : "disconnect" {connectionId}
S->>H : onDisconnect
H-->>C : "disconnect"
```

图表来源
- [src/websocket.ts:44-115](file://src/websocket.ts#L44-L115)
- [src/class/websockethandler.ts:145-206](file://src/class/websockethandler.ts#L145-L206)
- [src/class/websockethandler.ts:214-338](file://src/class/websockethandler.ts#L214-L338)
- [src/class/websockethandler.ts:404-430](file://src/class/websockethandler.ts#L404-L430)

章节来源
- [src/websocket.ts:6-118](file://src/websocket.ts#L6-L118)
- [src/class/websockethandler.ts:1-479](file://src/class/websockethandler.ts#L1-L479)

### HTTP 轮询信令 API
- 会话与连接管理
  - PUT ""：创建会话，返回 sessionId
  - DELETE ""：删除会话
  - PUT "/connection"：创建连接，返回 connectionId、polite、type、datetime
  - DELETE "/connection"：删除连接
- 信令存取
  - GET ""：获取所有信令（connect/disconnect/offer/answer/candidate），按 datetime 排序
  - GET "/offer"：获取 offer 列表（可按 fromtime 过滤）
  - GET "/answer"：获取 answer 列表（可按 fromtime 过滤）
  - GET "/candidate"：获取 candidate 列表（可按 fromtime 过滤）
  - GET "/connection"：获取连接列表
  - GET "/connection-ids"：获取所有活跃连接 ID
  - POST "/offer"：提交 offer
  - POST "/answer"：提交 answer
  - POST "/candidate"：提交 candidate
- 认证与安全
  - 所有受保护路由需携带请求头 "session-id"
- 房间与用户信息
  - GET "/rooms"：获取房间与用户信息（含 sessionId、connected）

```mermaid
flowchart TD
Start(["开始"]) --> CreateSession["PUT '' 创建会话"]
CreateSession --> CreateConn["PUT '/connection' 创建连接"]
CreateConn --> PollLoop["轮询 GET ''/offer/answer/candidate"]
PollLoop --> PostOffer["POST '/offer' 提交 offer"]
PollLoop --> PostAnswer["POST '/answer' 提交 answer"]
PollLoop --> PostCandidate["POST '/candidate' 提交 candidate"]
PostOffer --> PollLoop
PostAnswer --> PollLoop
PostCandidate --> PollLoop
PollLoop --> DeleteConn["DELETE '/connection' 删除连接"]
DeleteConn --> DeleteSession["DELETE '' 删除会话"]
DeleteSession --> End(["结束"])
```

图表来源
- [src/signaling.ts:6-24](file://src/signaling.ts#L6-L24)
- [src/class/httphandler.ts:664-696](file://src/class/httphandler.ts#L664-L696)
- [src/class/httphandler.ts:698-828](file://src/class/httphandler.ts#L698-L828)
- [src/class/httphandler.ts:830-998](file://src/class/httphandler.ts#L830-L998)
- [src/class/httphandler.ts:1041-1076](file://src/class/httphandler.ts#L1041-L1076)

章节来源
- [src/signaling.ts:1-25](file://src/signaling.ts#L1-L25)
- [src/class/httphandler.ts:1-1130](file://src/class/httphandler.ts#L1-L1130)

### 信令消息数据结构
- Offer
  - 字段：sdp、datetime、polite
  - 场景：发起端创建本地 offer 并通过信令通道发送给对端
- Answer
  - 字段：sdp、datetime
  - 场景：应答端收到 offer 后创建 answer 并回传
- Candidate
  - 字段：candidate、sdpMLineIndex、sdpMid、datetime
  - 场景：ICE 候选者收集阶段持续发送，帮助建立 P2P 连接

```mermaid
classDiagram
class Offer {
+string sdp
+number datetime
+boolean polite
}
class Answer {
+string sdp
+number datetime
}
class Candidate {
+string candidate
+number sdpMLineIndex
+string sdpMid
+number datetime
}
```

图表来源
- [src/class/offer.ts:1-11](file://src/class/offer.ts#L1-L11)
- [src/class/answer.ts:1-8](file://src/class/answer.ts#L1-L8)
- [src/class/candidate.ts:1-12](file://src/class/candidate.ts#L1-L12)

章节来源
- [src/class/offer.ts:1-11](file://src/class/offer.ts#L1-L11)
- [src/class/answer.ts:1-8](file://src/class/answer.ts#L1-L8)
- [src/class/candidate.ts:1-12](file://src/class/candidate.ts#L1-L12)

### Swagger 自动生成的 API 文档
- 生成与访问
  - 初始化 Swagger，自动扫描 /src/class/httphandler.ts 与 /src/signaling.ts 中的注释
  - 访问地址：/api-docs（根据运行协议与端口动态生成）
- 安全方案
  - sessionAuth：通过请求头 "session-id" 进行认证

章节来源
- [src/swagger.ts:16-65](file://src/swagger.ts#L16-L65)

### API 使用示例与集成模板
- 客户端封装
  - HTTP 信令封装：Signaling 类，提供 start/stop、createConnection/deleteConnection、sendOffer/sendAnswer/sendCandidate、getAll 等方法
  - WebSocket 信令封装：WebSocketSignaling 类，提供 createConnection/sendOffer/sendAnswer/sendCandidate/sendMessage 等方法
  - Peer 连接控制：Peer 类，封装 RTCPeerConnection、ICE 候选者、状态变化等
- 示例流程
  - HTTP 模式：创建会话 → 创建连接 → 轮询获取信令 → 发送 offer/answer/candidate → 删除连接/会话
  - WebSocket 模式：建立连接 → 发送 connect → 发送 offer/answer/candidate → 接收对端信令 → 断开连接

章节来源
- [client/src/signaling.js:1-292](file://client/src/signaling.js#L1-L292)
- [client/src/peer.js:1-188](file://client/src/peer.js#L1-L188)

## 依赖关系分析
- 服务端依赖
  - Express、ws、swagger-jsdoc、swagger-ui-express、uuid、cors、morgan、multer
- 关键依赖链
  - src/index.ts → src/server.ts → src/signaling.ts → src/class/httphandler.ts
  - src/index.ts → src/websocket.ts → src/class/websockethandler.ts
  - src/swagger.ts → src/class/httphandler.ts 与 src/signaling.ts

```mermaid
graph LR
pkg["package.json 依赖声明"] --> exp["express"]
pkg --> wsdep["ws"]
pkg --> swagger["swagger-jsdoc / swagger-ui-express"]
pkg --> uuiddep["uuid"]
pkg --> corsdep["cors"]
pkg --> morgandep["morgan"]
pkg --> multerdep["multer"]
idx["src/index.ts"] --> srv["src/server.ts"]
idx --> wsc["src/websocket.ts"]
srv --> sig["src/signaling.ts"]
sig --> hth["src/class/httphandler.ts"]
wsc --> wsh["src/class/websockethandler.ts"]
srv --> swg["src/swagger.ts"]
swg --> hth
swg --> sig
```

图表来源
- [package.json:14-46](file://package.json#L14-L46)
- [src/index.ts:13-109](file://src/index.ts#L13-L109)
- [src/server.ts:14-89](file://src/server.ts#L14-L89)
- [src/websocket.ts:6-118](file://src/websocket.ts#L6-L118)
- [src/signaling.ts:1-25](file://src/signaling.ts#L1-L25)
- [src/class/httphandler.ts:1-1130](file://src/class/httphandler.ts#L1-L1130)
- [src/class/websockethandler.ts:1-479](file://src/class/websockethandler.ts#L1-L479)
- [src/swagger.ts:16-65](file://src/swagger.ts#L16-L65)

章节来源
- [package.json:14-46](file://package.json#L14-L46)
- [src/index.ts:13-109](file://src/index.ts#L13-L109)

## 性能考量
- WebSocket
  - 低延迟、高吞吐，适合高频信令与实时交互
  - 心跳检测与超时断开避免僵尸连接占用资源
- HTTP 轮询
  - 增量查询 fromtime 参数减少无效传输
  - 会话超时清理机制降低内存占用
- 服务器配置
  - 日志级别可调，生产环境建议调整以减少 I/O 开销
  - HTTPS 证书启用时建议使用强密码套件与现代 TLS 版本

## 故障排查指南
- 常见错误与处理
  - 404 会话不存在：检查 session-id 是否正确传递
  - 400 参数缺失：确保请求体包含 connectionId
  - 400 连接 ID 已被使用（私有模式）：更换唯一 connectionId
  - 会话超时：定期轮询或保持 WebSocket 连接活跃
- 测试参考
  - WebSocket 单测验证公共/私有模式下的消息转发与断开行为
  - HTTP 单测验证会话创建/删除、连接管理、信令存取与超时清理

章节来源
- [test/websockethandler.test.ts:1-191](file://test/websockethandler.test.ts#L1-L191)
- [test/httphandler.test.ts:1-510](file://test/httphandler.test.ts#L1-L510)

## 结论
本项目提供了完整的 WebRTC 信令解决方案，支持 WebSocket 与 HTTP 轮询两种模式，满足不同部署与网络环境需求。通过清晰的 API 规范、完善的 Swagger 文档与客户端封装，开发者可快速集成并稳定运行信令服务。

## 附录
- 端点一览（HTTP 轮询）
  - GET /signaling/connection-ids：获取所有活跃连接 ID
  - GET /signaling/connection：获取连接列表
  - GET /signaling/offer：获取 offer 列表（可选 fromtime）
  - GET /signaling/answer：获取 answer 列表（可选 fromtime）
  - GET /signaling/candidate：获取 candidate 列表（可选 fromtime）
  - GET /signaling：获取所有信令（可选 fromtime）
  - PUT /signaling：创建会话（返回 sessionId）
  - DELETE /signaling：删除会话
  - PUT /signaling/connection：创建连接
  - DELETE /signaling/connection：删除连接
  - POST /signaling/offer：提交 offer
  - POST /signaling/answer：提交 answer
  - POST /signaling/candidate：提交 candidate
  - GET /signaling/rooms：获取房间与用户信息
- 客户端集成要点
  - HTTP 模式：使用 Signaling 类管理会话与轮询
  - WebSocket 模式：使用 WebSocketSignaling 类进行实时信令
  - Peer 控制：使用 Peer 类处理 RTCPeerConnection 生命周期与 ICE 候选者