修改

2026-05-16 13:24:02 +08:00
parent eae60714b4
commit 6c13817527
42 changed files with 15921 additions and 0 deletions
--- a/.qoder/repowiki/zh/content/开发指南/代码规范与质量.md
+++ b/.qoder/repowiki/zh/content/开发指南/代码规范与质量.md
@@ -0,0 +1,379 @@
+# 代码规范与质量
+
+<cite>
+**本文引用的文件**
+- [.eslintrc.cjs](file://.eslintrc.cjs)
+- [.eslintrc.json（客户端）](file://client/.eslintrc.json)
+- [.editorconfig](file://.editorconfig)
+- [package.json（服务端）](file://package.json)
+- [package.json（客户端）](file://client/package.json)
+- [tsconfig.json](file://tsconfig.json)
+- [tsconfig.lint.json](file://tsconfig.lint.json)
+- [jest.config.js](file://jest.config.js)
+- [src/index.ts](file://src/index.ts)
+- [src/server.ts](file://src/server.ts)
+- [client/src/peer.js](file://client/src/peer.js)
+- [client/src/sender.js](file://client/src/sender.js)
+- [test/websockethandler.test.ts](file://test/websockethandler.test.ts)
+- [client/test/inputremoting.test.js](file://client/test/inputremoting.test.js)
+</cite>
+
+## 目录
+1. 引言
+2. 项目结构
+3. 核心组件
+4. 架构总览
+5. 详细组件分析
+6. 依赖分析
+7. 性能考虑
+8. 故障排查指南
+9. 结论
+10. 附录
+
+## 引言
+本指南面向视频服务器项目的开发者与维护者，系统性阐述代码规范与质量控制策略，覆盖以下方面：
+- ESLint 规则与 TypeScript/JavaScript 的差异化配置
+- 代码格式化工具与自动格式化设置（EditorConfig）
+- 命名约定与变量命名最佳实践
+- 注释规范与文档编写标准
+- 代码审查流程与质量检查要点
+- 常见问题识别与修复方法
+- 自动化质量检查工具的配置与使用
+
+## 项目结构
+该项目采用前后端分离的多包结构：
+- 服务端（TypeScript）：src、test、配置文件（tsconfig、eslint、jest）
+- 客户端（前端 JS/TS）：client 目录下包含公共资源、源码与测试
+- 全局脚本与工具：根目录 package.json 提供 lint、test、build 等命令
+
+```mermaid
+graph TB
+subgraph "服务端"
+TS["TypeScript 源码<br/>src/*.ts"]
+TSTest["测试<br/>test/*.test.ts"]
+ESLintCJS[".eslintrc.cjs<br/>TypeScript 规则"]
+JestCfg["jest.config.js<br/>测试配置"]
+TSConf["tsconfig.json<br/>编译配置"]
+LintTSConf["tsconfig.lint.json<br/>ESLint 专用"]
+end
+subgraph "客户端"
+JS["前端源码<br/>client/src/*.js"]
+JSTest["前端测试<br/>client/test/*.test.js"]
+ESLintJSON[".eslintrc.json<br/>浏览器环境规则"]
+end
+RootPkg["根 package.json<br/>脚本与依赖"]
+RootPkg --> ESLintCJS
+RootPkg --> JestCfg
+RootPkg --> TSConf
+RootPkg --> LintTSConf
+TS --> ESLintCJS
+TSTest --> JestCfg
+JS --> ESLintJSON
+JSTest --> JestCfg
+```
+
+图表来源
+- [.eslintrc.cjs](file://.eslintrc.cjs)
+- [.eslintrc.json（客户端）](file://client/.eslintrc.json)
+- [jest.config.js](file://jest.config.js)
+- [tsconfig.json](file://tsconfig.json)
+- [tsconfig.lint.json](file://tsconfig.lint.json)
+- [package.json（服务端）](file://package.json)
+- [package.json（客户端）](file://client/package.json)
+
+章节来源
+- [package.json（服务端）:1-60](file://package.json#L1-L60)
+- [package.json（客户端）:1-19](file://client/package.json#L1-L19)
+
+## 核心组件
+- 代码检查（ESLint）
+  - 服务端：基于 TypeScript ESLint 插件，启用推荐规则集，解析器为 TypeScript，使用独立的 tsconfig.lint.json 以避免 sourceMap 影响性能。
+  - 客户端：基于 eslint:recommended 与 jest 插件，针对浏览器与 ES6 环境，强制分号与禁止多余分号。
+- 测试框架（Jest）
+  - 收集覆盖率、使用 ts-jest 转换 TS/TSX，测试环境为 node；客户端测试使用 jsdom 环境。
+- 编辑器配置（EditorConfig）
+  - 统一缩进风格、换行符、结尾换行与尾随空白处理。
+
+章节来源
+- [.eslintrc.cjs:1-25](file://.eslintrc.cjs#L1-L25)
+- [.eslintrc.json（客户端）:1-23](file://client/.eslintrc.json#L1-L23)
+- [tsconfig.lint.json:1-12](file://tsconfig.lint.json#L1-L12)
+- [jest.config.js:1-196](file://jest.config.js#L1-L196)
+- [.editorconfig:1-20](file://.editorconfig#L1-L20)
+
+## 架构总览
+整体质量控制链路如下：
+- 开发阶段：编辑器读取 EditorConfig 进行基础格式化；保存时由 IDE 或插件执行 ESLint 校验。
+- CI/本地：通过 npm/yarn scripts 执行 lint 与 test；ESLint 针对 src 与 test；Jest 覆盖服务端与客户端测试。
+- 发布前：构建产物生成于 build 目录，确保 TypeScript 编译无误。
+
+```mermaid
+sequenceDiagram
+participant Dev as "开发者"
+participant IDE as "编辑器/IDE"
+participant ESL as "ESLint"
+participant Jest as "Jest"
+participant TS as "TypeScript 编译器"
+Dev->>IDE : 保存文件
+IDE->>ESL : 触发语法与风格检查
+ESL-->>Dev : 报告规则违规
+Dev->>Jest : 运行测试
+Jest-->>Dev : 输出测试结果与覆盖率
+Dev->>TS : 执行构建
+TS-->>Dev : 生成构建产物
+```
+
+图表来源
+- [package.json（服务端）:5-12](file://package.json#L5-L12)
+- [jest.config.js:174-176](file://jest.config.js#L174-L176)
+- [tsconfig.json:1-13](file://tsconfig.json#L1-L13)
+
+## 详细组件分析
+
+### ESLint 配置与规则
+- 服务端（TypeScript）
+  - 环境：node、jest
+  - 继承：eslint:recommended、@typescript-eslint/eslint-recommended、@typescript-eslint/recommended、jest/recommended
+  - 解析器：@typescript-eslint/parser
+  - 解析选项：module、project 指向 tsconfig.lint.json
+  - 关键规则：
+    - 禁止 var 的 require 使用
+    - any 类型放宽
+    - 分号：强制；多余分号：报错
+- 客户端（JavaScript）
+  - 环境：browser、es6、jest
+  - 继承：eslint:recommended、jest/recommended
+  - 规则：强制分号、禁止多余分号
+
+章节来源
+- [.eslintrc.cjs:1-25](file://.eslintrc.cjs#L1-L25)
+- [.eslintrc.json（客户端）:1-23](file://client/.eslintrc.json#L1-L23)
+
+### 代码格式化与 EditorConfig
+- 统一规则：
+  - 缩进：空格
+  - 行结束符：LF
+  - 缩进大小：2
+  - 文件末尾插入换行
+  - 字符集：UTF-8
+  - 去除行尾空白
+- 适用范围：ts、js、json、html
+
+章节来源
+- [.editorconfig:10-20](file://.editorconfig#L10-L20)
+
+### TypeScript 与 JavaScript 的差异化规则
+- TypeScript
+  - 使用 @typescript-eslint 推荐规则，强调类型安全与结构一致性
+  - 通过 tsconfig.lint.json 优化 ESLint 性能（关闭 sourceMap）
+- JavaScript（客户端）
+  - 面向浏览器与 ES6，强调语义正确性与简洁性
+  - 保留分号一致性，避免多余分号
+
+章节来源
+- [.eslintrc.cjs:6-16](file://.eslintrc.cjs#L6-L16)
+- [.eslintrc.json（客户端）:3-22](file://client/.eslintrc.json#L3-L22)
+- [tsconfig.lint.json:4-11](file://tsconfig.lint.json#L4-L11)
+
+### 命名约定与变量命名最佳实践
+- 类型与模块
+  - 类名：帕斯卡命名（如 RenderStreaming）
+  - 接口/类型：帕斯卡命名（如 Options）
+  - 模块导出：默认导出或具名导出保持一致，避免混用
+- 变量与函数
+  - 变量：小驼峰命名（如 connectionId、options）
+  - 函数：动词短语或小驼峰（如 getIPAddress、createServer）
+  - 常量：全大写蛇形（如 MAX_RETRIES）
+- 文件与路径
+  - 源文件：按功能分层组织（如 src/class、src/signaling）
+  - 测试文件：与被测模块同名或以 .test 后缀
+- 前端输入设备类
+  - 类名：帕斯卡命名（如 Sender、Observer）
+  - 属性与方法：小驼峰（如 devices、onEvent）
+
+章节来源
+- [src/index.ts:13-106](file://src/index.ts#L13-L106)
+- [src/server.ts:14-89](file://src/server.ts#L14-L89)
+- [client/src/peer.js:3-188](file://client/src/peer.js#L3-L188)
+- [client/src/sender.js:14-209](file://client/src/sender.js#L14-L209)
+
+### 注释规范与文档编写标准
+- 文件级注释
+  - 说明模块职责、入口点与关键行为
+- 函数/方法注释
+  - 参数与返回值：使用 JSDoc 风格（如 @param、@returns）
+  - 复杂逻辑：简述目的与边界条件
+- 类注释
+  - 类的用途、构造参数、事件与生命周期
+- 前端类示例
+  - 类定义处与关键方法处提供注释，描述事件派发与状态变化
+
+章节来源
+- [client/src/sender.js:107-112](file://client/src/sender.js#L107-L112)
+- [client/src/sender.js:191-201](file://client/src/sender.js#L191-L201)
+
+### 代码审查流程与质量检查要点
+- 代码检查
+  - 本地：npm run lint（服务端）与 npm run lint（客户端）
+  - CI：集成 lint 与 test 步骤，确保通过后再合并
+- 测试覆盖率
+  - Jest 启用覆盖率收集，建议设定最小阈值
+- 审查清单
+  - 类型安全：TS 是否启用严格模式相关规则
+  - 命名一致性：是否遵循命名约定
+  - 注释完整性：关键函数/类是否具备必要注释
+  - 错误处理：异常分支与日志记录
+  - 性能与资源：定时任务、事件监听与清理
+
+章节来源
+- [package.json（服务端）:5-12](file://package.json#L5-L12)
+- [package.json（客户端）:5-8](file://client/package.json#L5-L8)
+- [jest.config.js:20-34](file://jest.config.js#L20-L34)
+
+### 常见代码问题与修复方法
+- TypeScript
+  - any 类型滥用：优先使用具体类型或泛型
+  - 导入路径不一致：统一相对路径或别名
+  - 未使用的变量/私有成员：删除或标记为私有
+- JavaScript（客户端）
+  - 事件监听未移除：在组件销毁时解绑
+  - 分号缺失：遵循 EditorConfig 与 ESLint 规则
+  - 重复逻辑：抽取为函数或工具模块
+- 通用
+  - 日志与错误：使用统一的日志模块，避免直接 console
+  - 资源清理：WebSocket、HTTP 请求、文件句柄等及时释放
+
+章节来源
+- [.eslintrc.cjs:18-23](file://.eslintrc.cjs#L18-L23)
+- [.eslintrc.json（客户端）:19-22](file://client/.eslintrc.json#L19-L22)
+- [src/server.ts:44-57](file://src/server.ts#L44-L57)
+
+### 自动化质量检查工具配置与使用
+- ESLint
+  - 服务端：npm run lint 检查 src 与 test 下的 TypeScript 文件
+  - 客户端：npm run lint 检查 public 与 src、test 下的 JS 文件
+- Jest
+  - 服务端：npm test 运行所有测试
+  - 客户端：npm test 运行前端测试（需 jsdom 环境）
+- TypeScript
+  - 构建：npm run build 使用 tsconfig.build.json
+  - ESLint 专用：tsconfig.lint.json 关闭 sourceMap，提升性能
+
+章节来源
+- [package.json（服务端）:5-12](file://package.json#L5-L12)
+- [package.json（客户端）:5-8](file://client/package.json#L5-L8)
+- [tsconfig.json:1-13](file://tsconfig.json#L1-L13)
+- [tsconfig.lint.json:1-12](file://tsconfig.lint.json#L1-L12)
+- [jest.config.js:174-176](file://jest.config.js#L174-L176)
+
+## 依赖分析
+- 工具链耦合
+  - ESLint 与 TypeScript 解析器耦合，解析选项指向 tsconfig.lint.json
+  - Jest 与 ts-jest 耦合，支持 TS/TSX 测试文件
+- 环境差异
+  - 服务端：Node 环境，Jest 测试环境为 node
+  - 客户端：浏览器环境，Jest 使用 jsdom 与自定义环境配置
+
+```mermaid
+graph LR
+ESLintTS["@typescript-eslint/parser<br/>解析 TS/TSX"]
+ESLintCfg[".eslintrc.cjs<br/>规则与插件"]
+JestTS["ts-jest<br/>转换 TS/TSX"]
+JestCfg["jest.config.js<br/>测试环境与扩展"]
+TSConf["tsconfig.json<br/>编译配置"]
+LintTSConf["tsconfig.lint.json<br/>ESLint 专用"]
+ESLintCfg --> ESLintTS
+ESLintCfg --> LintTSConf
+JestCfg --> JestTS
+JestCfg --> TSConf
+```
+
+图表来源
+- [.eslintrc.cjs:12-16](file://.eslintrc.cjs#L12-L16)
+- [tsconfig.lint.json:4-11](file://tsconfig.lint.json#L4-L11)
+- [jest.config.js:174-176](file://jest.config.js#L174-L176)
+- [tsconfig.json:4-11](file://tsconfig.json#L4-L11)
+
+章节来源
+- [.eslintrc.cjs:12-16](file://.eslintrc.cjs#L12-L16)
+- [tsconfig.lint.json:4-11](file://tsconfig.lint.json#L4-L11)
+- [jest.config.js:174-176](file://jest.config.js#L174-L176)
+- [tsconfig.json:4-11](file://tsconfig.json#L4-L11)
+
+## 性能考虑
+- ESLint 性能
+  - 使用 tsconfig.lint.json 关闭 sourceMap，减少解析开销
+  - 仅对 src 与 test 目标进行检查，避免 node_modules
+- 构建与测试
+  - 构建输出至 build 目录，便于缓存与增量编译
+  - Jest 使用 v8 覆盖率提供器，平衡速度与准确性
+
+章节来源
+- [tsconfig.lint.json:8](file://tsconfig.lint.json#L8)
+- [jest.config.js:34](file://jest.config.js#L34)
+- [package.json（服务端）:6](file://package.json#L6)
+
+## 故障排查指南
+- ESLint 报错
+  - 规则冲突：调整 .eslintrc.cjs 或 .eslintrc.json 中的 rules
+  - 解析失败：确认 tsconfig.lint.json 与 tsconfig.json 的 include/exclude 一致
+- Jest 测试失败
+  - 环境问题：检查 jest.config.js 的 testEnvironment 与 jsdom 配置
+  - 转换问题：确认 ts-jest 版本与 tsconfig.json 设置匹配
+- EditorConfig 不生效
+  - 检查文件扩展名是否在 [*.{ts,js,json,html}] 范围内
+  - 确认编辑器已加载 EditorConfig 插件
+
+章节来源
+- [.eslintrc.cjs:18-23](file://.eslintrc.cjs#L18-L23)
+- [.eslintrc.json（客户端）:19-22](file://client/.eslintrc.json#L19-L22)
+- [jest.config.js:140-145](file://jest.config.js#L140-L145)
+- [.editorconfig:15-18](file://.editorconfig#L15-L18)
+
+## 结论
+本指南提供了从工具配置到编码实践的完整质量保障体系。建议团队在开发流程中坚持：
+- 保存即检查：利用 EditorConfig 与 ESLint 在本地即时反馈
+- 测试驱动：以 Jest 覆盖核心逻辑，持续改进覆盖率
+- 文档与注释：关键模块与复杂函数必须具备清晰注释
+- 审查与迭代：结合审查清单与自动化检查，逐步完善规则与流程
+
+## 附录
+
+### 示例：WebSocket 信令处理测试流程
+```mermaid
+sequenceDiagram
+participant Test as "测试用例"
+participant WSHandler as "WebSocket 处理器"
+participant MockWS as "WebSocket 模拟"
+participant Signaling as "信令服务"
+Test->>MockWS : 建立连接
+Test->>WSHandler : add(客户端)
+WSHandler->>Signaling : 广播 connect 消息
+Test->>WSHandler : onOffer(发送 offer)
+WSHandler->>Signaling : 广播 offer 消息
+Test->>WSHandler : onAnswer(发送 answer)
+WSHandler->>Signaling : 广播 answer 消息
+Test->>WSHandler : remove(断开)
+WSHandler->>Signaling : 广播 disconnect 消息
+```
+
+图表来源
+- [test/websockethandler.test.ts:30-99](file://test/websockethandler.test.ts#L30-L99)
+
+### 示例：输入远程控制测试流程
+```mermaid
+sequenceDiagram
+participant Test as "测试用例"
+participant Sender as "Sender"
+participant Remoting as "InputRemoting"
+participant Observer as "Observer"
+Test->>Sender : 创建实例
+Test->>Remoting : 创建实例并绑定 Sender
+Test->>Observer : 创建观察者
+Test->>Remoting : subscribe(Observer)
+Test->>Remoting : startSending()
+Test->>Remoting : stopSending()
+```
+
+图表来源
+- [client/test/inputremoting.test.js:24-48](file://client/test/inputremoting.test.js#L24-L48)