# 扩展开发

<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/signaling.ts](file://src/signaling.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)
- [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)
- [package.json](file://package.json)
- [client/package.json](file://client/package.json)
</cite>

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

## 简介
本指南面向希望扩展视频信令服务器的开发者，系统讲解如何：
- 添加新的信令消息类型（如 Offer、Answer、Candidate 的扩展）
- 扩展 WebSocketHandler 与 HttpHandler 的消息处理机制
- 开发自定义信令处理器，实现消息路由与处理流程
- 扩展客户端功能（新增 WebRTC 能力与 UI 组件）
- 使用插件化扩展点设计原则与最佳实践
- 考虑版本兼容性与向后兼容性

## 项目结构
项目采用前后端分离的模块化组织：
- 服务端（Node.js + Express + WebSocket）：负责信令路由、消息持久化与广播
- 客户端（浏览器端 JS）：封装 HTTP 与 WebSocket 两类信令通道，驱动 WebRTC PeerConnection

```mermaid
graph TB
subgraph "服务端"
IDX["入口: src/index.ts"]
SRV["HTTP 服务器: src/server.ts"]
WS["WebSocket 信令: src/websocket.ts"]
WSH["WebSocket 处理器: src/class/websockethandler.ts"]
HTH["HTTP 处理器: src/class/httphandler.ts"]
SIG["HTTP 路由: src/signaling.ts"]
end
subgraph "客户端"
CL_SIG["信令封装: client/src/signaling.js"]
CL_PEER["WebRTC 对端: client/src/peer.js"]
end
IDX --> SRV
SRV --> SIG
SRV --> WS
WS --> WSH
SIG --> HTH
CL_SIG --> WS
CL_SIG --> SIG
CL_PEER --> CL_SIG
```

图表来源
- [src/index.ts:13-109](file://src/index.ts#L13-L109)
- [src/server.ts:14-90](file://src/server.ts#L14-L90)
- [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-800](file://src/class/httphandler.ts#L1-L800)
- [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)

章节来源
- [src/index.ts:13-109](file://src/index.ts#L13-L109)
- [src/server.ts:14-90](file://src/server.ts#L14-L90)
- [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-800](file://src/class/httphandler.ts#L1-L800)
- [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)

## 核心组件
- 信令模型类：Offer、Answer、Candidate，承载 SDP 与 ICE 候选等数据
- WebSocket 信令：WSSignaling 负责连接生命周期与消息分发
- WebSocket 处理器：websockethandler 提供连接组管理、广播、消息路由
- HTTP 信令：httphandler 提供会话、连接、offer/answer/candidate 的持久化与轮询接口
- HTTP 路由：signaling 路由器挂载在 /signaling 下，统一暴露 REST API
- 客户端封装：signaling.js 提供 HTTP 与 WebSocket 两种信令通道；peer.js 驱动 WebRTC

章节来源
- [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/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-800](file://src/class/httphandler.ts#L1-L800)
- [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 两条信令通道并行工作：
- WebSocket：低延迟、实时广播、支持 ping/pong 心跳
- HTTP：轮询获取历史信令，适合弱网或受限环境

```mermaid
sequenceDiagram
participant C as "客户端"
participant WS as "WSSignaling"
participant WH as "WebSocket 处理器"
participant HS as "HTTP 服务器"
participant HH as "HTTP 处理器"
C->>WS : "connect/disconnect/offer/answer/candidate"
WS->>WH : "分发消息类型"
WH-->>C : "广播/单播回执"
C->>HS : "PUT/GET/POST /signaling/*"
HS->>HH : "路由到处理器"
HH-->>C : "返回历史信令/状态"
```

图表来源
- [src/websocket.ts:44-115](file://src/websocket.ts#L44-L115)
- [src/class/websockethandler.ts:76-338](file://src/class/websockethandler.ts#L76-L338)
- [src/server.ts:25-42](file://src/server.ts#L25-L42)
- [src/signaling.ts:6-24](file://src/signaling.ts#L6-L24)
- [src/class/httphandler.ts:398-641](file://src/class/httphandler.ts#L398-L641)

章节来源
- [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/server.ts:14-90](file://src/server.ts#L14-L90)
- [src/signaling.ts:1-25](file://src/signaling.ts#L1-L25)
- [src/class/httphandler.ts:1-800](file://src/class/httphandler.ts#L1-L800)

## 详细组件分析

### 1) 新增信令消息类型（以 Offer/Answer/Candidate 为例）
- 数据模型
  - Offer：包含 sdp、datetime、polite 字段
  - Answer：包含 sdp、datetime
  - Candidate：包含 candidate、sdpMLineIndex、sdpMid、datetime
- 服务端处理
  - WebSocket：在 WSSignaling 中解析消息类型并调用 websockethandler 的 onOffer/onAnswer/onCandidate
  - HTTP：在 httphandler 中维护会话级的 offers/answers/candidates 映射，提供 GET/POST 接口
- 客户端封装
  - HTTP 与 WebSocket 两端均提供发送与接收事件，便于上层业务订阅

```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
}
class WebSocket_Handler {
+onOffer(ws,msg)
+onAnswer(ws,msg)
+onCandidate(ws,msg)
}
class HTTP_Handler {
+postOffer(req,res)
+postAnswer(req,res)
+postCandidate(req,res)
+getOffer(req,res)
+getAnswer(req,res)
+getCandidate(req,res)
}
WebSocket_Handler --> Offer : "构造/转发"
WebSocket_Handler --> Answer : "构造/转发"
WebSocket_Handler --> Candidate : "构造/转发"
HTTP_Handler --> Offer : "持久化/查询"
HTTP_Handler --> Answer : "持久化/查询"
HTTP_Handler --> Candidate : "持久化/查询"
```

图表来源
- [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/websockethandler.ts:214-338](file://src/class/websockethandler.ts#L214-L338)
- [src/class/httphandler.ts:398-641](file://src/class/httphandler.ts#L398-L641)

章节来源
- [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/websockethandler.ts:214-338](file://src/class/websockethandler.ts#L214-L338)
- [src/class/httphandler.ts:398-641](file://src/class/httphandler.ts#L398-L641)

### 2) WebSocketHandler 扩展机制
- 连接组管理：host 与 participants 的角色区分，支持私有模式下的多对一/一对一路由
- 广播与单播：根据消息类型与角色进行目标选择
- 心跳与断线：定时心跳检测，超时自动断开并广播离线事件
- 新消息类型接入步骤
  1) 在 WSSignaling 的消息分发处增加 case 分支
  2) 在 websockethandler 中实现对应处理函数（如 onXxx），完成路由与广播
  3) 在客户端 signaling.js 中订阅并派发自定义事件

```mermaid
sequenceDiagram
participant WS as "WebSocket"
participant WSH as "websockethandler"
participant P as "参与者"
WS->>WSH : "type='xxx'"
WSH->>WSH : "匹配处理函数"
WSH->>P : "广播/单播消息"
P-->>WSH : "回执/确认"
```

图表来源
- [src/websocket.ts:76-113](file://src/websocket.ts#L76-L113)
- [src/class/websockethandler.ts:97-137](file://src/class/websockethandler.ts#L97-L137)
- [src/class/websockethandler.ts:214-338](file://src/class/websockethandler.ts#L214-L338)

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

### 3) HttpHandler 扩展机制
- 会话与连接：通过 session-id 维持会话上下文，支持连接对（connectionPair）在私有模式下建立双向关系
- 消息持久化：offers/answers/candidates 以会话+连接维度缓存，支持 fromtime 过滤
- 轮询接口：提供 /signaling、/signaling/offer、/signaling/answer、/signaling/candidate 的 GET/POST
- 新消息类型接入步骤
  1) 在 httphandler 中新增 postXxx 与 getXxx 方法，维护内部映射
  2) 在 signaling 路由中注册对应路由
  3) 在客户端 signaling.js 中补充发送与接收逻辑

```mermaid
flowchart TD
Start(["HTTP 请求进入"]) --> CheckSession["校验 session-id"]
CheckSession --> Route{"路由到哪？"}
Route --> |GET /signaling| GetAll["合并并排序历史消息"]
Route --> |GET /signaling/offer| GetOffer["按会话/时间过滤 offer"]
Route --> |GET /signaling/answer| GetAnswer["按会话/时间过滤 answer"]
Route --> |GET /signaling/candidate| GetCandidate["按会话/时间过滤 candidate"]
Route --> |POST /signaling/offer| PostOffer["写入 offer 映射"]
Route --> |POST /signaling/answer| PostAnswer["写入 answer 映射"]
Route --> |POST /signaling/candidate| PostCandidate["写入 candidate 映射"]
GetAll --> End(["返回 JSON"])
GetOffer --> End
GetAnswer --> End
GetCandidate --> End
PostOffer --> End
PostAnswer --> End
PostCandidate --> End
```

图表来源
- [src/class/httphandler.ts:128-145](file://src/class/httphandler.ts#L128-L145)
- [src/class/httphandler.ts:398-641](file://src/class/httphandler.ts#L398-L641)
- [src/signaling.ts:6-24](file://src/signaling.ts#L6-L24)

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

### 4) 自定义信令处理器开发指南
- 设计原则
  - 单一职责：每个处理器只负责一类消息或一类资源
  - 可组合：通过中间件/装饰器模式复用鉴权、日志、限流
  - 可替换：对外暴露一致的 API，内部可替换实现
- 消息路由与处理流程
  - WebSocket：在 WSSignaling 的 switch 分支中新增 case，调用处理器对应方法
  - HTTP：在 signaling 路由中注册新路由，处理器中实现鉴权与数据持久化
- 客户端集成
  - 在 signaling.js 中新增发送与接收事件，确保与服务端消息结构一致
  - 在 peer.js 或业务层订阅事件并驱动 WebRTC

```mermaid
sequenceDiagram
participant App as "应用层"
participant WS as "WSSignaling"
participant WH as "自定义处理器"
participant HH as "自定义 HTTP 处理器"
participant CL as "客户端"
App->>WS : "发送自定义消息"
WS->>WH : "分发到自定义处理器"
WH-->>CL : "广播/回执"
App->>HH : "HTTP 请求"
HH-->>CL : "返回处理结果"
CL-->>App : "事件回调"
```

图表来源
- [src/websocket.ts:76-113](file://src/websocket.ts#L76-L113)
- [src/signaling.ts:6-24](file://src/signaling.ts#L6-L24)
- [client/src/signaling.js:152-292](file://client/src/signaling.js#L152-L292)

章节来源
- [src/websocket.ts:6-118](file://src/websocket.ts#L6-L118)
- [src/signaling.ts:1-25](file://src/signaling.ts#L1-L25)
- [client/src/signaling.js:1-292](file://client/src/signaling.js#L1-L292)

### 5) 扩展客户端功能（WebRTC 与 UI 组件）
- 新增 WebRTC 能力
  - 在 peer.js 中扩展事件（如 onCustomMessage），并在 signaling.js 中订阅
  - 如需数据通道，参考 createDataChannel 与 ondatachannel 的使用模式
- UI 组件
  - 基于现有 signaling.js 的事件模型，新增 DOM 事件监听与渲染逻辑
  - 保持与现有连接/断开/offer/answer/candidate 事件的兼容

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

### 6) 插件系统与扩展点设计原则
- 扩展点
  - WebSocket 消息分发：在 WSSignaling 的 switch 中新增 case
  - HTTP 路由：在 signaling 路由中新增子路由
  - 处理器内部：在 websockethandler/httphandler 中新增处理函数
- 设计原则
  - 向后兼容：新增字段建议可选，避免破坏既有消息结构
  - 版本化：通过消息中的 version 字段或路由版本号区分
  - 强约束：严格校验必填字段，失败时返回明确错误码
  - 可观测：为新消息类型增加日志与指标埋点

章节来源
- [src/websocket.ts:76-113](file://src/websocket.ts#L76-L113)
- [src/signaling.ts:6-24](file://src/signaling.ts#L6-L24)
- [src/class/websockethandler.ts:76-338](file://src/class/websockethandler.ts#L76-L338)
- [src/class/httphandler.ts:398-641](file://src/class/httphandler.ts#L398-L641)

### 7) 实际扩展示例与最佳实践
- 示例：新增“自定义消息”类型
  - 服务端
    - 在 WSSignaling 的 switch 中新增 case："custom"
    - 在 websockethandler 中实现 onCustom，完成路由与广播
    - 在 httphandler 中新增 postCustom/getCustom，维护映射
    - 在 signaling 路由中注册 /signaling/custom
  - 客户端
    - 在 signaling.js 中新增 sendCustom 与订阅 "custom" 事件
- 最佳实践
  - 消息结构最小化：仅包含必要字段
  - 错误处理：对缺失字段与非法值返回 4xx/5xx 并记录日志
  - 幂等性：对重复消息进行去重（基于时间戳或唯一 ID）
  - 性能：批量消息合并、异步处理、限流与背压

章节来源
- [src/websocket.ts:76-113](file://src/websocket.ts#L76-L113)
- [src/class/websockethandler.ts:214-338](file://src/class/websockethandler.ts#L214-L338)
- [src/class/httphandler.ts:398-641](file://src/class/httphandler.ts#L398-L641)
- [src/signaling.ts:6-24](file://src/signaling.ts#L6-L24)
- [client/src/signaling.js:1-292](file://client/src/signaling.js#L1-L292)

## 依赖分析
- 服务端依赖
  - Express：HTTP 服务器与路由
  - ws：WebSocket 服务器
  - morgan：HTTP 日志
  - uuid：会话 ID 生成
- 客户端依赖
  - 浏览器原生 fetch/WebSocket
  - Jest（测试）

```mermaid
graph LR
PKG["服务端 package.json"] --> EXP["express"]
PKG --> WS["ws"]
PKG --> MORGAN["morgan"]
PKG --> UUID["uuid"]
CLPKG["客户端 package.json"] --> JEST["jest"]
CLPKG --> ESLINT["eslint"]
```

图表来源
- [package.json:14-27](file://package.json#L14-L27)
- [client/package.json:9-18](file://client/package.json#L9-L18)

章节来源
- [package.json:1-60](file://package.json#L1-L60)
- [client/package.json:1-19](file://client/package.json#L1-L19)

## 性能考量
- WebSocket
  - 心跳间隔与超时阈值可调，避免频繁断线
  - 大消息拆分与压缩，减少带宽占用
- HTTP
  - fromtime 参数配合增量拉取，降低响应体积
  - 合理设置轮询间隔，平衡实时性与资源消耗
- 通用
  - 缓存热点数据（如最近 N 条 candidate）
  - 异步处理耗时操作（如持久化）

## 故障排查指南
- WebSocket 无法连接
  - 检查 WSSignaling 的连接事件与日志
  - 确认客户端 URL 与协议（ws/wss）
- 消息未到达
  - 核对 websockethandler 的广播逻辑与角色判断
  - 确认客户端事件监听是否正确
- HTTP 会话异常
  - 检查 session-id 请求头与会话超时清理
  - 使用 getAll 接口核对历史消息
- 单元测试参考
  - 使用 websockethandler.test.ts 验证消息路由与广播行为

章节来源
- [src/websocket.ts:27-38](file://src/websocket.ts#L27-L38)
- [src/class/websockethandler.ts:97-137](file://src/class/websockethandler.ts#L97-L137)
- [src/class/httphandler.ts:218-232](file://src/class/httphandler.ts#L218-L232)
- [test/websockethandler.test.ts:1-191](file://test/websockethandler.test.ts#L1-L191)

## 结论
通过明确的扩展点与清晰的处理流程，项目允许以最小改动安全地引入新的信令消息类型与客户端能力。遵循向后兼容、可观测与可测试的原则，可确保扩展的稳定性与演进速度。

## 附录
- 版本与兼容性
  - 服务端与客户端版本号：3.1.0
  - 建议在新增字段时保留默认值，避免破坏旧客户端解析
  - 对于重大变更，建议引入版本字段或路由版本号

章节来源
- [package.json:1-60](file://package.json#L1-L60)
- [client/package.json:1-19](file://client/package.json#L1-L19)