396 lines
15 KiB
Markdown
396 lines
15 KiB
Markdown
# 信令消息对象
|
||
|
||
<cite>
|
||
**本文引用的文件**
|
||
- [offer.ts](file://src/class/offer.ts)
|
||
- [answer.ts](file://src/class/answer.ts)
|
||
- [candidate.ts](file://src/class/candidate.ts)
|
||
- [httphandler.ts](file://src/class/httphandler.ts)
|
||
- [websockethandler.ts](file://src/class/websockethandler.ts)
|
||
- [signaling.ts](file://src/signaling.ts)
|
||
- [websocket.ts](file://src/websocket.ts)
|
||
- [signaling.js](file://client/src/signaling.js)
|
||
- [signaling.test.js](file://client/test/signaling.test.js)
|
||
- [服务端接口与WebSocket消息类型.md](file://src/服务端接口与WebSocket消息类型.md)
|
||
- [package.json](file://package.json)
|
||
</cite>
|
||
|
||
## 目录
|
||
1. [简介](#简介)
|
||
2. [项目结构](#项目结构)
|
||
3. [核心组件](#核心组件)
|
||
4. [架构总览](#架构总览)
|
||
5. [详细组件分析](#详细组件分析)
|
||
6. [依赖关系分析](#依赖关系分析)
|
||
7. [性能考虑](#性能考虑)
|
||
8. [故障排查指南](#故障排查指南)
|
||
9. [结论](#结论)
|
||
10. [附录](#附录)
|
||
|
||
## 简介
|
||
本文件系统性地文档化了 WebRTC 信令消息对象 Offer、Answer 和 Candidate 的数据结构、字段定义与实现细节。重点覆盖：
|
||
- Offer 类的 SDP 描述封装、时间戳管理与礼貌协商标志（polite）语义
|
||
- Answer 类的应答消息构建与 SDP 交换流程
|
||
- Candidate 类的 ICE 候选者序列化与传输机制
|
||
- 消息对象的创建、验证与序列化方法
|
||
- JSON 结构规范与字段含义
|
||
- 实际消息交换示例与调试技巧
|
||
- 不同通信模式（公共/私有）下的使用差异
|
||
|
||
## 项目结构
|
||
该项目采用前后端分离的 TypeScript/JavaScript 架构，核心信令逻辑位于服务端的 HTTP 与 WebSocket 处理器中，前端提供基于 HTTP 轮询与 WebSocket 的信令客户端。
|
||
|
||
```mermaid
|
||
graph TB
|
||
subgraph "客户端"
|
||
FE_HTTP["HTTP 客户端<br/>signaling.js"]
|
||
FE_WS["WebSocket 客户端<br/>signaling.js"]
|
||
end
|
||
subgraph "服务端"
|
||
HTTP["HTTP 路由<br/>signaling.ts"]
|
||
WS["WebSocket 服务器<br/>websocket.ts"]
|
||
HHTTP["HTTP 处理器<br/>httphandler.ts"]
|
||
HWS["WebSocket 处理器<br/>websockethandler.ts"]
|
||
MODELS["消息模型<br/>offer.ts / answer.ts / candidate.ts"]
|
||
end
|
||
FE_HTTP --> HTTP
|
||
FE_WS --> WS
|
||
HTTP --> HHTTP
|
||
WS --> HWS
|
||
HHTTP --> MODELS
|
||
HWS --> MODELS
|
||
```
|
||
|
||
图表来源
|
||
- [signaling.ts:1-25](file://src/signaling.ts#L1-L25)
|
||
- [websocket.ts:1-118](file://src/websocket.ts#L1-L118)
|
||
- [httphandler.ts:1-120](file://src/class/httphandler.ts#L1-L120)
|
||
- [websockethandler.ts:1-120](file://src/class/websockethandler.ts#L1-L120)
|
||
- [offer.ts:1-11](file://src/class/offer.ts#L1-L11)
|
||
- [answer.ts:1-8](file://src/class/answer.ts#L1-L8)
|
||
- [candidate.ts:1-12](file://src/class/candidate.ts#L1-L12)
|
||
|
||
章节来源
|
||
- [signaling.ts:1-25](file://src/signaling.ts#L1-L25)
|
||
- [websocket.ts:1-118](file://src/websocket.ts#L1-L118)
|
||
- [httphandler.ts:1-120](file://src/class/httphandler.ts#L1-L120)
|
||
- [websockethandler.ts:1-120](file://src/class/websockethandler.ts#L1-L120)
|
||
- [offer.ts:1-11](file://src/class/offer.ts#L1-L11)
|
||
- [answer.ts:1-8](file://src/class/answer.ts#L1-L8)
|
||
- [candidate.ts:1-12](file://src/class/candidate.ts#L1-L12)
|
||
|
||
## 核心组件
|
||
- Offer：封装 SDP 描述、时间戳与礼貌协商标志
|
||
- Answer：封装 SDP 描述与时间戳
|
||
- Candidate：封装 ICE 候选者、SDP 媒体行索引与媒体 ID、时间戳
|
||
|
||
这些类作为纯数据载体，被 HTTP 与 WebSocket 处理器在消息收发时构造与使用。
|
||
|
||
章节来源
|
||
- [offer.ts:1-11](file://src/class/offer.ts#L1-L11)
|
||
- [answer.ts:1-8](file://src/class/answer.ts#L1-L8)
|
||
- [candidate.ts:1-12](file://src/class/candidate.ts#L1-L12)
|
||
|
||
## 架构总览
|
||
HTTP 与 WebSocket 两条路径共同承载信令消息的收发与存储，处理器负责：
|
||
- 会话与连接管理
|
||
- 消息持久化与检索
|
||
- 消息路由与广播
|
||
- 通信模式（公共/私有）下的差异化行为
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant C as "客户端(HTTP)"
|
||
participant R as "HTTP 路由(signaling.ts)"
|
||
participant H as "HTTP 处理器(httphandler.ts)"
|
||
participant S as "存储(Maps)"
|
||
participant WS as "WebSocket 服务器(websocket.ts)"
|
||
C->>R : POST /signaling/offer
|
||
R->>H : postOffer(...)
|
||
H->>S : 存储 Offer 对象
|
||
H-->>C : 200 OK
|
||
C->>R : GET /signaling/offer?fromtime=...
|
||
R->>H : getOffer(...)
|
||
H->>S : 查询并过滤
|
||
H-->>C : {offers : [{connectionId,sdp,polite,type,datetime}]}
|
||
Note over WS,H : WebSocket 路由与处理器同样处理 offer/answer/candidate
|
||
```
|
||
|
||
图表来源
|
||
- [signaling.ts:20-22](file://src/signaling.ts#L20-L22)
|
||
- [httphandler.ts:268-318](file://src/class/httphandler.ts#L268-L318)
|
||
- [websocket.ts:44-114](file://src/websocket.ts#L44-L114)
|
||
- [websockethandler.ts:214-260](file://src/class/websockethandler.ts#L214-L260)
|
||
|
||
## 详细组件分析
|
||
|
||
### Offer 类分析
|
||
Offer 类用于封装 WebRTC Offer 信令消息的核心数据，包含 SDP 描述、时间戳与礼貌协商标志。
|
||
|
||
- 字段定义
|
||
- sdp: string —— SDP 描述字符串
|
||
- datetime: number —— 消息创建时间戳（毫秒）
|
||
- polite: boolean —— 礼貌协商标志，用于避免并发 offer 冲突
|
||
|
||
- 构造与使用
|
||
- HTTP 处理器在收到 offer 后，使用 sdp、当前时间与默认 polite 构造 Offer 对象并持久化
|
||
- WebSocket 处理器在收到 offer 后，同样构造 Offer 对象并进行路由
|
||
|
||
- 礼貌协商（Polite）语义
|
||
- 在私有模式下，host 的 polite=false，participant 的 polite=true
|
||
- 在公共模式下，polite 字段通常为 false，由服务端统一构造
|
||
|
||
```mermaid
|
||
classDiagram
|
||
class Offer {
|
||
+string sdp
|
||
+number datetime
|
||
+boolean polite
|
||
+constructor(sdp, datetime, polite)
|
||
}
|
||
```
|
||
|
||
图表来源
|
||
- [offer.ts:1-11](file://src/class/offer.ts#L1-L11)
|
||
- [websockethandler.ts:214-247](file://src/class/websockethandler.ts#L214-L247)
|
||
- [httphandler.ts:268-318](file://src/class/httphandler.ts#L268-L318)
|
||
|
||
章节来源
|
||
- [offer.ts:1-11](file://src/class/offer.ts#L1-L11)
|
||
- [websockethandler.ts:214-247](file://src/class/websockethandler.ts#L214-L247)
|
||
- [httphandler.ts:268-318](file://src/class/httphandler.ts#L268-L318)
|
||
|
||
### Answer 类分析
|
||
Answer 类用于封装 WebRTC Answer 信令消息的核心数据，包含 SDP 描述与时间戳。
|
||
|
||
- 字段定义
|
||
- sdp: string —— SDP 描述字符串
|
||
- datetime: number —— 消息创建时间戳（毫秒）
|
||
|
||
- 构造与使用
|
||
- HTTP 处理器在收到 answer 后，使用 sdp、当前时间构造 Answer 对象并持久化
|
||
- WebSocket 处理器在收到 answer 后，同样构造 Answer 对象并进行路由
|
||
|
||
```mermaid
|
||
classDiagram
|
||
class Answer {
|
||
+string sdp
|
||
+number datetime
|
||
+constructor(sdp, datetime)
|
||
}
|
||
```
|
||
|
||
图表来源
|
||
- [answer.ts:1-8](file://src/class/answer.ts#L1-L8)
|
||
- [websockethandler.ts:268-301](file://src/class/websockethandler.ts#L268-L301)
|
||
- [httphandler.ts:300-318](file://src/class/httphandler.ts#L300-L318)
|
||
|
||
章节来源
|
||
- [answer.ts:1-8](file://src/class/answer.ts#L1-L8)
|
||
- [websockethandler.ts:268-301](file://src/class/websockethandler.ts#L268-L301)
|
||
- [httphandler.ts:300-318](file://src/class/httphandler.ts#L300-L318)
|
||
|
||
### Candidate 类分析
|
||
Candidate 类用于封装 ICE 候选者消息，包含候选者字符串、SDP 媒体行索引与媒体 ID、时间戳。
|
||
|
||
- 字段定义
|
||
- candidate: string —— ICE 候选者描述
|
||
- sdpMLineIndex: number —— SDP 媒体行索引
|
||
- sdpMid: string —— SDP 媒体 ID
|
||
- datetime: number —— 消息创建时间戳（毫秒）
|
||
|
||
- 构造与使用
|
||
- HTTP 处理器在收到 candidate 后，使用 candidate、sdpMLineIndex、sdpMid、当前时间构造 Candidate 对象并持久化
|
||
- WebSocket 处理器在收到 candidate 后，同样构造 Candidate 对象并进行路由
|
||
|
||
```mermaid
|
||
classDiagram
|
||
class Candidate {
|
||
+string candidate
|
||
+number sdpMLineIndex
|
||
+string sdpMid
|
||
+number datetime
|
||
+constructor(candidate, sdpMLineIndex, sdpMid, datetime)
|
||
}
|
||
```
|
||
|
||
图表来源
|
||
- [candidate.ts:1-12](file://src/class/candidate.ts#L1-L12)
|
||
- [websockethandler.ts:309-338](file://src/class/websockethandler.ts#L309-L338)
|
||
- [httphandler.ts:320-356](file://src/class/httphandler.ts#L320-L356)
|
||
|
||
章节来源
|
||
- [candidate.ts:1-12](file://src/class/candidate.ts#L1-L12)
|
||
- [websockethandler.ts:309-338](file://src/class/websockethandler.ts#L309-L338)
|
||
- [httphandler.ts:320-356](file://src/class/httphandler.ts#L320-L356)
|
||
|
||
### 消息对象的创建、验证与序列化
|
||
|
||
- 创建
|
||
- HTTP：客户端通过 POST /signaling/offer、/answer、/candidate 发送 JSON，服务端在处理器中解析并构造对应消息对象
|
||
- WebSocket：客户端通过发送包含 type 与 data 的 JSON，服务端在 WebSocket 处理器中解析并构造对应消息对象
|
||
|
||
- 验证
|
||
- HTTP：处理器对必要字段进行校验（如 connectionId、sdp、candidate 等），并在缺失时返回错误
|
||
- WebSocket：处理器对消息结构进行校验，确保 from、to、data 字段存在
|
||
|
||
- 序列化
|
||
- HTTP：消息对象被转换为 JSON 并返回给客户端
|
||
- WebSocket：消息对象被包装为 { type, from, to, data, participantId } 形式发送
|
||
|
||
章节来源
|
||
- [httphandler.ts:398-558](file://src/class/httphandler.ts#L398-L558)
|
||
- [websockethandler.ts:192-200](file://src/class/websockethandler.ts#L192-L200)
|
||
- [signaling.js:117-138](file://client/src/signaling.js#L117-L138)
|
||
- [signaling.js:255-279](file://client/src/signaling.js#L255-L279)
|
||
|
||
### JSON 结构规范与字段含义
|
||
|
||
- Offer
|
||
- 字段：connectionId, sdp, polite, type="offer", datetime
|
||
- 含义：连接标识、SDP 描述、礼貌协商标志、消息类型、时间戳
|
||
|
||
- Answer
|
||
- 字段：connectionId, sdp, type="answer", datetime
|
||
- 含义：连接标识、SDP 描述、消息类型、时间戳
|
||
|
||
- Candidate
|
||
- 字段：connectionId, candidate, sdpMLineIndex, sdpMid, type="candidate", datetime
|
||
- 含义：连接标识、ICE 候选者、SDP 媒体行索引、SDP 媒体 ID、消息类型、时间戳
|
||
|
||
- 通用字段
|
||
- type：消息类型（connect/disconnect/offer/answer/candidate/on-message）
|
||
- datetime：消息创建时间戳（毫秒）
|
||
|
||
章节来源
|
||
- [服务端接口与WebSocket消息类型.md:141-234](file://src/服务端接口与WebSocket消息类型.md#L141-L234)
|
||
- [httphandler.ts:398-558](file://src/class/httphandler.ts#L398-L558)
|
||
|
||
### 实际消息交换示例与调试技巧
|
||
|
||
- HTTP 模式
|
||
- 客户端通过 PUT /signaling 创建会话，随后通过 PUT /signaling/connection 建立连接
|
||
- 使用 GET /signaling 获取所有消息，或分别 GET /signaling/offer、/answer、/candidate 拉取增量
|
||
- 使用 fromtime 参数实现增量拉取，避免重复处理
|
||
|
||
- WebSocket 模式
|
||
- 客户端发送 { type: "connect", connectionId } 建立连接
|
||
- 发送 { type: "offer"/"answer"/"candidate", from, data } 进行 SDP 交换
|
||
- 监听服务端推送的 offer/answer/candidate 消息并更新本地 PeerConnection
|
||
|
||
- 调试技巧
|
||
- 使用浏览器开发者工具查看网络面板中的 HTTP 请求与响应
|
||
- 在 WebSocket 面板观察消息收发，注意 participantId 与 from 字段
|
||
- 关注服务端日志输出，定位消息路由问题
|
||
- 使用测试用例参考消息格式与预期行为
|
||
|
||
章节来源
|
||
- [signaling.js:30-150](file://client/src/signaling.js#L30-L150)
|
||
- [websocket.ts:44-114](file://src/websocket.ts#L44-L114)
|
||
- [websockethandler.ts:192-200](file://src/class/websockethandler.ts#L192-L200)
|
||
- [signaling.test.js:89-208](file://client/test/signaling.test.js#L89-L208)
|
||
|
||
### 不同通信模式下的使用差异
|
||
|
||
- 公共模式（Public）
|
||
- 所有连接的客户端均可相互通信
|
||
- offer/answer/candidate 向所有其他客户端广播
|
||
- 适合点对点直连场景
|
||
|
||
- 私有模式（Private）
|
||
- 一个 connectionId 对应一个房间，包含 1 个 host 与多个 participants
|
||
- host 为第一个加入者（polite=false），participants 为后续加入者（polite=true）
|
||
- host 可单播给特定 participant 或广播给所有 participants；participant 仅能发送给 host
|
||
- host 离开时房间关闭，participants 被断开；participant 离开房间仍保留
|
||
|
||
章节来源
|
||
- [服务端接口与WebSocket消息类型.md:489-505](file://src/服务端接口与WebSocket消息类型.md#L489-L505)
|
||
- [websockethandler.ts:150-167](file://src/class/websockethandler.ts#L150-L167)
|
||
- [httphandler.ts:280-289](file://src/class/httphandler.ts#L280-L289)
|
||
|
||
## 依赖关系分析
|
||
|
||
```mermaid
|
||
graph LR
|
||
O["Offer 类<br/>offer.ts"] --> HH["HTTP 处理器<br/>httphandler.ts"]
|
||
A["Answer 类<br/>answer.ts"] --> HH
|
||
C["Candidate 类<br/>candidate.ts"] --> HH
|
||
HH --> S["会话/连接映射(Maps)"]
|
||
HH --> WS["WebSocket 服务器<br/>websocket.ts"]
|
||
HH --> HWS["WebSocket 处理器<br/>websockethandler.ts"]
|
||
HWS --> O
|
||
HWS --> A
|
||
HWS --> C
|
||
```
|
||
|
||
图表来源
|
||
- [offer.ts:1-11](file://src/class/offer.ts#L1-L11)
|
||
- [answer.ts:1-8](file://src/class/answer.ts#L1-L8)
|
||
- [candidate.ts:1-12](file://src/class/candidate.ts#L1-L12)
|
||
- [httphandler.ts:63-77](file://src/class/httphandler.ts#L63-L77)
|
||
- [websockethandler.ts:5-8](file://src/class/websockethandler.ts#L5-L8)
|
||
- [websocket.ts:1-118](file://src/websocket.ts#L1-L118)
|
||
|
||
章节来源
|
||
- [offer.ts:1-11](file://src/class/offer.ts#L1-L11)
|
||
- [answer.ts:1-8](file://src/class/answer.ts#L1-L8)
|
||
- [candidate.ts:1-12](file://src/class/candidate.ts#L1-L12)
|
||
- [httphandler.ts:63-77](file://src/class/httphandler.ts#L63-L77)
|
||
- [websockethandler.ts:5-8](file://src/class/websockethandler.ts#L5-L8)
|
||
- [websocket.ts:1-118](file://src/websocket.ts#L1-L118)
|
||
|
||
## 性能考虑
|
||
- 增量拉取：HTTP GET 支持 fromtime 参数，减少重复消息传输与解析开销
|
||
- 会话超时：10 秒无请求自动清理会话，避免内存泄漏
|
||
- 广播策略：公共模式下广播所有消息，私有模式下按需单播/广播，降低网络负载
|
||
- 心跳检测：可选的心跳机制（ping/pong）用于保持连接活跃，避免被中间设备断开
|
||
|
||
[本节为通用建议，不直接分析具体文件]
|
||
|
||
## 故障排查指南
|
||
- HTTP 404：检查会话 ID 是否正确传入请求头 Session-Id
|
||
- 消息未到达：确认通信模式（公共/私有）与连接配对是否正确
|
||
- polite 标志异常：检查连接顺序与私有模式下 host/participant 的角色分配
|
||
- Candidate 缺失：确认 ICE 候选者是否正确序列化，sdpMLineIndex 与 sdpMid 是否匹配
|
||
- WebSocket 断开：检查心跳机制与网络稳定性，关注服务端日志
|
||
|
||
章节来源
|
||
- [httphandler.ts:128-145](file://src/class/httphandler.ts#L128-L145)
|
||
- [websockethandler.ts:404-430](file://src/class/websockethandler.ts#L404-L430)
|
||
- [websocket.ts:95-100](file://src/websocket.ts#L95-L100)
|
||
|
||
## 结论
|
||
Offer、Answer 与 Candidate 三类消息对象构成了 WebRTC 信令的核心载体。通过 HTTP 与 WebSocket 双通道，结合公共/私有两种通信模式，系统实现了灵活高效的信令交换能力。理解各字段的语义与消息流转过程，有助于在实际开发中快速定位问题并优化性能。
|
||
|
||
[本节为总结性内容，不直接分析具体文件]
|
||
|
||
## 附录
|
||
|
||
### API 一览（HTTP）
|
||
- GET /signaling/connection-ids
|
||
- PUT /signaling
|
||
- GET /signaling
|
||
- DELETE /signaling
|
||
- GET /signaling/connection
|
||
- PUT /signaling/connection
|
||
- DELETE /signaling/connection
|
||
- GET /signaling/offer
|
||
- POST /signaling/offer
|
||
- GET /signaling/answer
|
||
- POST /signaling/answer
|
||
- GET /signaling/candidate
|
||
- POST /signaling/candidate
|
||
|
||
章节来源
|
||
- [服务端接口与WebSocket消息类型.md:37-234](file://src/服务端接口与WebSocket消息类型.md#L37-L234)
|
||
|
||
### WebSocket 消息类型
|
||
- connect/disconnect：连接生命周期
|
||
- offer/answer/candidate：SDP 交换
|
||
- on-message：通用消息
|
||
- broadcast：广播消息
|
||
- call-request：呼叫请求
|
||
- participant-joined/participant-left：私有模式参与者变更
|
||
|
||
章节来源
|
||
- [服务端接口与WebSocket消息类型.md:262-486](file://src/服务端接口与WebSocket消息类型.md#L262-L486) |