Files

stary 6c13817527 修改

2026-05-16 13:24:02 +08:00

17 KiB

Raw Permalink Blame History

扩展开发

**本文引用的文件** - [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)

简介

本指南面向希望扩展视频信令服务器的开发者，系统讲解如何：

添加新的信令消息类型（如 Offer、Answer、Candidate 的扩展）
扩展 WebSocketHandler 与 HttpHandler 的消息处理机制
开发自定义信令处理器，实现消息路由与处理流程
扩展客户端功能（新增 WebRTC 能力与 UI 组件）
使用插件化扩展点设计原则与最佳实践
考虑版本兼容性与向后兼容性

项目结构

项目采用前后端分离的模块化组织：

服务端（Node.js + Express + WebSocket）：负责信令路由、消息持久化与广播
客户端（浏览器端 JS）：封装 HTTP 与 WebSocket 两类信令通道，驱动 WebRTC PeerConnection

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

图表来源

章节来源

核心组件

信令模型类：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

章节来源

架构总览

WebSocket 与 HTTP 两条信令通道并行工作：

WebSocket：低延迟、实时广播、支持 ping/pong 心跳
HTTP：轮询获取历史信令，适合弱网或受限环境

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 : "返回历史信令/状态"

图表来源

章节来源

详细组件分析

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 两端均提供发送与接收事件，便于上层业务订阅

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 : "持久化/查询"

图表来源

章节来源

2) WebSocketHandler 扩展机制

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

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

图表来源

章节来源

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 中补充发送与接收逻辑

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

图表来源

章节来源

4) 自定义信令处理器开发指南

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

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 : "事件回调"

图表来源

章节来源

5) 扩展客户端功能（WebRTC 与 UI 组件）

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

章节来源

6) 插件系统与扩展点设计原则

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

章节来源

7) 实际扩展示例与最佳实践

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

章节来源

依赖分析

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

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

图表来源

章节来源

性能考量

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

故障排查指南

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

章节来源

结论

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

附录

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

章节来源

17 KiB Raw Permalink Blame History Unescape Escape

扩展开发

目录

简介

项目结构

核心组件

架构总览

详细组件分析

1) 新增信令消息类型（以 Offer/Answer/Candidate 为例）

2) WebSocketHandler 扩展机制

3) HttpHandler 扩展机制

4) 自定义信令处理器开发指南

5) 扩展客户端功能（WebRTC 与 UI 组件）

6) 插件系统与扩展点设计原则

7) 实际扩展示例与最佳实践

依赖分析

性能考量

故障排查指南

结论

附录

17 KiB

Raw Permalink Blame History