# 信令消息对象

<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)