root/video_socket-server
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
2c6a7af31bc0f1488cc3e0f1ec28c753fe73468a
video_socket-server/.qoder/repowiki/zh/content/开发指南/贡献指南.md
stary 6c13817527 修改
2026-05-16 13:24:02 +08:00

12 KiB
Raw Blame History

贡献指南

**本文引用的文件** - [package.json](file://package.json) - [tsconfig.json](file://tsconfig.json) - [.eslintrc.cjs](file://.eslintrc.cjs) - [jest.config.js](file://jest.config.js) - [src/index.ts](file://src/index.ts) - [src/server.ts](file://src/server.ts) - [src/class/websockethandler.ts](file://src/class/websockethandler.ts) - [src/class/httphandler.ts](file://src/class/httphandler.ts) - [.gitignore](file://.gitignore)

目录

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

简介

本贡献指南面向希望参与“视频流服务器”项目的开发者，提供从 Fork、Clone、分支与提交、Pull Request 到代码审查、Issue 提交、版本发布与变更日志维护、社区行为准则与协作规范的全流程说明。同时给出新贡献者的入门建议与资源链接，帮助快速上手。

项目结构

该项目采用前后端一体化的 Node/Express + TypeScript 后端，内置静态前端资源与测试框架，支持 WebSocket 与 HTTP 两种信令模式，具备会话管理、WebRTC 信令转发、文件上传与 Swagger 文档能力。

graph TB
subgraph "后端"
IDX["入口: src/index.ts"]
SRV["服务器: src/server.ts"]
WS["WebSocket处理器: src/class/websockethandler.ts"]
HTTP["HTTP处理器: src/class/httphandler.ts"]
end
subgraph "前端"
PUB["静态资源: client/public/**/*"]
SRC["前端模块: client/src/**/*"]
end
subgraph "工具与配置"
PKG["包脚本: package.json"]
TSC["编译配置: tsconfig.json"]
ESL["代码规范: .eslintrc.cjs"]
JST["测试配置: jest.config.js"]
GIT["忽略规则: .gitignore"]
end
IDX --> SRV
SRV --> WS
SRV --> HTTP
SRV --> PUB
SRV --> SRC
PKG --> TSC
PKG --> ESL
PKG --> JST
PKG --> GIT

图表来源

章节来源

核心组件

  • 入口与启动
    • 通过命令行参数解析与 HTTPS/HTTP 服务启动，支持 WebSocket 或 HTTP 信令模式，以及公共/私有通信模式。
  • 服务器与路由
    • Express 应用挂载 CORS、日志中间件、静态资源、Swagger 文档、上传接口与信令路由。
  • WebSocket 信令
    • 实现 1 对多（主持人/参与者）模式下的 offer/answer/candidate 转发、广播、心跳检测与断线清理。
  • HTTP 信令
    • 基于轮询的信令 API，提供会话创建、连接管理、offer/answer/candidate 获取与断线记录。
  • 测试与规范
    • Jest 测试配置与覆盖率收集；ESLint TypeScript 规则；TypeScript 编译配置。

章节来源

架构总览

后端以 Express 为核心，根据信令类型选择 WebSocket 或 HTTP 处理器；静态资源与前端模块通过 Express 提供；测试与规范工具贯穿开发流程。

graph TB
Client["浏览器/客户端"] --> Mode{"信令模式"}
Mode --> |WebSocket| WS["WebSocket处理器<br/>websockethandler.ts"]
Mode --> |HTTP| HTTP["HTTP处理器<br/>httphandler.ts"]
WS --> Server["Express服务器<br/>server.ts"]
HTTP --> Server
Server --> Static["静态资源<br/>client/public/**/*"]
Server --> Front["前端模块<br/>client/src/**/*"]
Server --> Swagger["Swagger文档"]
Server --> Upload["头像上传API"]

图表来源

详细组件分析

WebSocket 信令处理流程

WebSocket 处理器支持公共/私有模式，实现连接、断开、offer/answer/candidate 转发与广播、心跳检测与断线清理。

sequenceDiagram
participant C as "客户端"
participant S as "WebSocket处理器"
participant G as "连接组"
participant H as "主持人"
participant P as "参与者"
C->>S : "connect(connectionId)"
S->>G : "创建/加入连接组"
S-->>C : "connect(角色, participantId)"
C->>S : "offer/answer/candidate"
alt 私有模式
S->>H : "主持人接收转发"
S->>P : "参与者接收转发"
else 公共模式
S->>G : "广播到其他客户端"
end
C->>S : "disconnect"
S->>G : "清理连接组并通知"
S-->>C : "disconnect"

图表来源

章节来源

HTTP 信令处理流程

HTTP 处理器提供会话与连接管理、offer/answer/candidate 获取、断线记录与全量信令拉取。

sequenceDiagram
participant Client as "客户端"
participant Handler as "HTTP处理器"
participant Store as "内存存储"
participant Other as "其他会话/连接"
Client->>Handler : "PUT /signaling (创建会话)"
Handler->>Store : "初始化会话映射"
Handler-->>Client : "{ sessionId }"
Client->>Handler : "PUT /signaling/connection (创建连接)"
Handler->>Store : "登记连接ID与配对"
Handler-->>Client : "{ connectionId, polite }"
Client->>Handler : "GET /signaling/offer?fromtime"
Handler->>Store : "按模式过滤并返回offer列表"
Client->>Handler : "GET /signaling (全量信令)"
Handler->>Store : "聚合连接/断线/offer/answer/candidate"
Handler-->>Client : "{ messages, datetime }"
Client->>Handler : "DELETE /signaling/connection"
Handler->>Store : "清理连接与配对"

图表来源

章节来源

代码规范与测试

  • ESLint 规则启用 TypeScript 推荐规则与 Jest 推荐规则，强制分号与多余分号检查。
  • Jest 配置启用覆盖率收集、TS 转换、Node 环境与测试匹配规则。
  • TypeScript 编译配置输出至 build 目录，源码位于 src，测试位于 test。

章节来源

依赖关系分析

  • 后端运行时依赖：Express、WS、CORS、Morgan、Multer、Swagger。
  • 开发依赖：Jest、TS-Jest、ESLint、TypeScript、pkg 等。
  • 构建与打包：通过 TypeScript 编译与 pkg 配置，打包静态资源与前端模块。
graph LR
PKG["package.json"] --> DEPS["运行时依赖"]
PKG --> DEVDEPS["开发依赖"]
PKG --> BIN["构建与打包配置"]
BIN --> TSC["tsconfig.json"]
BIN --> ESL["eslint配置"]
BIN --> JST["jest配置"]

图表来源

章节来源

性能考量

  • WebSocket 心跳与超时：处理器内置心跳检测与超时断开逻辑，避免僵尸连接占用资源。
  • HTTP 轮询：提供 fromtime 参数过滤增量消息，降低带宽与计算压力。
  • 日志与中间件：morgan 日志级别可配置，建议在生产环境调整为合适级别。
  • 静态资源：静态目录与前端模块统一托管，确保缓存与压缩策略一致。

章节来源

故障排查指南

  • 启动失败
    • 检查证书文件路径与权限（HTTPS 模式），确认端口占用与网络接口。
  • 信令异常
    • 确认信令模式（WebSocket/HTTP）与通信模式（public/private）配置一致。
    • 查看日志输出定位连接组状态与消息转发问题。
  • 测试失败
    • 使用 Jest 覆盖率报告定位未覆盖路径，修正测试用例与模拟。
  • 规范检查
    • 运行 ESLint 并修复规则冲突，确保提交前通过静态检查。

章节来源

结论

本指南提供了从开发环境准备到贡献流程、代码审查、Issue 规范、版本发布与变更日志维护、社区协作的完整实践路径。建议贡献者在提交前完成本地测试与规范检查，并遵循分支命名与提交信息格式，确保高质量交付。

附录

代码贡献流程

  • Fork 仓库
    • 在代码托管平台执行 Fork 操作，获得个人副本。
  • Clone 与安装
    • 克隆到本地，安装依赖并运行开发脚本。
  • 分支与提交
    • 基于主分支创建特性分支，遵循分支命名规范与提交信息格式。
  • Pull Request
    • 提交 PR，填写模板信息，等待审查与合并。

章节来源

分支命名规范与提交信息格式

  • 分支命名
    • feat/xxx：新增功能
    • fix/xxx：缺陷修复
    • docs/xxx：文档更新
    • refactor/xxx：重构
    • test/xxx：测试相关
  • 提交信息格式
    • 类型(scope): 描述
    • 例如：feat(server): 支持自定义日志级别

代码审查标准与流程

  • 审查清单
    • 功能正确性与边界条件
    • 性能影响与资源占用
    • 日志与错误处理
    • 单元测试覆盖率
    • 规范检查通过
  • 审查流程
    • 提交 PR → 指派审查者 → 评论与修改 → 合并

Issue 提交规范

  • Bug 报告
    • 环境信息、复现步骤、期望/实际结果、日志片段
  • 功能请求
    • 背景、需求描述、影响范围、优先级建议

版本发布与变更日志维护

  • 版本号
    • 遵循语义化版本：主版本.次版本.修订
  • 变更日志
    • 按版本记录新增、修复、变更与废弃项，标注影响与迁移指引

社区行为准则与协作规范

  • 尊重与包容：保持友善与专业
  • 明确沟通：使用清晰、简洁的语言
  • 合规贡献：遵守开源许可证与安全政策

新贡献者入门指导与资源链接

  • 环境准备
    • Node.js、TypeScript、Git 基础
  • 本地运行
    • 使用开发脚本启动服务，访问静态页面与 Swagger 文档
  • 学习资源
    • Express、WebSocket、WebRTC 信令基础
    • Jest 与 ESLint 使用指南
Reference in New Issue View Git Blame Copy Permalink