root/video_socket-server
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
d74a0c812155f981c5ac60217dbe7ac0de0cf6b6
video_socket-server/.qoder/repowiki/zh/content/开发指南/代码规范与质量.md
stary 6c13817527 修改
2026-05-16 13:24:02 +08:00

14 KiB
Raw Blame History

代码规范与质量

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

目录

  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 等命令
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

图表来源

章节来源

核心组件

  • 代码检查（ESLint）
    • 服务端：基于 TypeScript ESLint 插件，启用推荐规则集，解析器为 TypeScript，使用独立的 tsconfig.lint.json 以避免 sourceMap 影响性能。
    • 客户端：基于 eslint:recommended 与 jest 插件，针对浏览器与 ES6 环境，强制分号与禁止多余分号。
  • 测试框架（Jest）
    • 收集覆盖率、使用 ts-jest 转换 TS/TSX，测试环境为 node；客户端测试使用 jsdom 环境。
  • 编辑器配置（EditorConfig）
    • 统一缩进风格、换行符、结尾换行与尾随空白处理。

章节来源

架构总览

整体质量控制链路如下：

  • 开发阶段：编辑器读取 EditorConfig 进行基础格式化；保存时由 IDE 或插件执行 ESLint 校验。
  • CI/本地：通过 npm/yarn scripts 执行 lint 与 test；ESLint 针对 src 与 test；Jest 覆盖服务端与客户端测试。
  • 发布前：构建产物生成于 build 目录，确保 TypeScript 编译无误。
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 : 生成构建产物

图表来源

详细组件分析

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
    • 规则：强制分号、禁止多余分号

章节来源

代码格式化与 EditorConfig

  • 统一规则：
    • 缩进：空格
    • 行结束符：LF
    • 缩进大小：2
    • 文件末尾插入换行
    • 字符集：UTF-8
    • 去除行尾空白
  • 适用范围：ts、js、json、html

章节来源

TypeScript 与 JavaScript 的差异化规则

  • TypeScript
    • 使用 @typescript-eslint 推荐规则，强调类型安全与结构一致性
    • 通过 tsconfig.lint.json 优化 ESLint 性能（关闭 sourceMap）
  • JavaScript（客户端）
    • 面向浏览器与 ES6，强调语义正确性与简洁性
    • 保留分号一致性，避免多余分号

章节来源

命名约定与变量命名最佳实践

  • 类型与模块
    • 类名：帕斯卡命名（如 RenderStreaming）
    • 接口/类型：帕斯卡命名（如 Options）
    • 模块导出：默认导出或具名导出保持一致，避免混用
  • 变量与函数
    • 变量：小驼峰命名（如 connectionId、options）
    • 函数：动词短语或小驼峰（如 getIPAddress、createServer）
    • 常量：全大写蛇形（如 MAX_RETRIES）
  • 文件与路径
    • 源文件：按功能分层组织（如 src/class、src/signaling）
    • 测试文件：与被测模块同名或以 .test 后缀
  • 前端输入设备类
    • 类名：帕斯卡命名（如 Sender、Observer）
    • 属性与方法：小驼峰（如 devices、onEvent）

章节来源

注释规范与文档编写标准

  • 文件级注释
    • 说明模块职责、入口点与关键行为
  • 函数/方法注释
    • 参数与返回值：使用 JSDoc 风格（如 @param、@returns）
    • 复杂逻辑：简述目的与边界条件
  • 类注释
    • 类的用途、构造参数、事件与生命周期
  • 前端类示例
    • 类定义处与关键方法处提供注释，描述事件派发与状态变化

章节来源

代码审查流程与质量检查要点

  • 代码检查
    • 本地：npm run lint（服务端）与 npm run lint（客户端）
    • CI：集成 lint 与 test 步骤，确保通过后再合并
  • 测试覆盖率
    • Jest 启用覆盖率收集，建议设定最小阈值
  • 审查清单
    • 类型安全：TS 是否启用严格模式相关规则
    • 命名一致性：是否遵循命名约定
    • 注释完整性：关键函数/类是否具备必要注释
    • 错误处理：异常分支与日志记录
    • 性能与资源：定时任务、事件监听与清理

章节来源

常见代码问题与修复方法

  • TypeScript
    • any 类型滥用：优先使用具体类型或泛型
    • 导入路径不一致：统一相对路径或别名
    • 未使用的变量/私有成员：删除或标记为私有
  • JavaScript（客户端）
    • 事件监听未移除：在组件销毁时解绑
    • 分号缺失：遵循 EditorConfig 与 ESLint 规则
    • 重复逻辑：抽取为函数或工具模块
  • 通用
    • 日志与错误：使用统一的日志模块，避免直接 console
    • 资源清理：WebSocket、HTTP 请求、文件句柄等及时释放

章节来源

自动化质量检查工具配置与使用

  • 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，提升性能

章节来源

依赖分析

  • 工具链耦合
    • ESLint 与 TypeScript 解析器耦合，解析选项指向 tsconfig.lint.json
    • Jest 与 ts-jest 耦合，支持 TS/TSX 测试文件
  • 环境差异
    • 服务端：Node 环境，Jest 测试环境为 node
    • 客户端：浏览器环境，Jest 使用 jsdom 与自定义环境配置
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

图表来源

章节来源

性能考虑

  • ESLint 性能
    • 使用 tsconfig.lint.json 关闭 sourceMap，减少解析开销
    • 仅对 src 与 test 目标进行检查，避免 node_modules
  • 构建与测试
    • 构建输出至 build 目录，便于缓存与增量编译
    • Jest 使用 v8 覆盖率提供器，平衡速度与准确性

章节来源

故障排查指南

  • 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 插件

章节来源

结论

本指南提供了从工具配置到编码实践的完整质量保障体系。建议团队在开发流程中坚持：

  • 保存即检查：利用 EditorConfig 与 ESLint 在本地即时反馈
  • 测试驱动：以 Jest 覆盖核心逻辑，持续改进覆盖率
  • 文档与注释：关键模块与复杂函数必须具备清晰注释
  • 审查与迭代：结合审查清单与自动化检查，逐步完善规则与流程

附录

示例：WebSocket 信令处理测试流程

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 消息

图表来源

示例：输入远程控制测试流程

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

图表来源

Reference in New Issue View Git Blame Copy Permalink