在 Devin 中试用 DeepWiki 处理私有仓库
DeepWiki

nestjs/nest

菜单

WebSockets

相关源文件

NestJS 中的 WebSockets 提供了一个框架，用于构建具有客户端和服务器之间双向通信的实时应用程序。本文档解释了 WebSockets 在 NestJS 中的实现和使用方式，包括网关、消息处理、适配器以及与 NestJS 其他功能的集成。

有关服务器发送事件（一种不同的实时通信方法）的信息，请参阅 服务器发送事件 (SSE)。

架构概述

NestJS 通过 @nestjs/websockets 包提供 WebSocket 支持，该包与核心框架集成。它同时为 Socket.IO 和原生 WebSockets 提供了适配器。

  • @nestjs/platform-socket.io：与 Socket.IO 集成
  • @nestjs/platform-ws：与原生 WebSockets 集成（通过 ws 包）

WebSockets 模块是 NestJS 中的一个可选组件，正如核心 package.json 中所指出的，其中 @nestjs/websockets 被列为一个可选的对等依赖。

NestJS WebSockets 架构

来源

网关和消息处理程序

WebSocket 网关是使用 @WebSocketGateway() 装饰器注解的类。它们的工作方式与控制器类似，但专为 WebSocket 通信而设计。消息处理程序是网关内使用 @SubscribeMessage() 装饰的方法，用于响应特定事件。

网关结构和消息处理

消息处理程序可以返回不同类型的响应

  1. void - 不向客户端发送任何内容
  2. 一个对象 - 作为消息返回，具有相同的事件名称
  3. Observable<WsResponse> - 允许发送具有不同事件名称的多个响应

来源

WebSocket 消息处理管道

当收到 WebSocket 事件时，它会经历一个与 HTTP 请求类似的 Pipelined 处理流程。 WsContextCreator 类负责为消息处理程序创建执行上下文，包括设置守卫 (guards)、管道 (pipes) 和拦截器 (interceptors)。

WebSocket 消息处理管道

WebSocket 消息的上下文创建过程由 WsContextCreator 类处理，它遵循以下关键步骤：

  1. 创建守卫上下文：设置可以根据条件阻止消息处理的守卫。
  2. 创建管道上下文：设置用于转换输入数据的管道。
  3. 创建拦截器上下文：设置用于消息处理前/后的拦截器。
  4. 创建异常过滤器：设置用于处理异常的过滤器。

此 Pipelined 流程确保 WebSocket 消息处理遵循与 NestJS 中的 HTTP 请求处理相同的模式，并具有适当的上下文类型和元数据。

来源

Socket 适配器

NestJS 提供了两种主要的 WebSocket 适配器：

  1. IoAdapter (Socket.IO)：提供功能丰富的实现，并为不支持 WebSockets 的浏览器提供回退机制。
  2. WsAdapter (Native WS)：一个轻量级的实现，使用原生 WebSockets 协议。

WebSocket 适配器架构

适配器负责：

  • 创建 WebSocket 服务器
  • 绑定客户端连接事件
  • 将消息处理程序绑定到特定事件
  • 在需要时关闭服务器

来源

异常处理

WebSocket 异常使用 WsException 类进行处理，并通过专用的异常处理机制进行处理。 WsProxy 类包装消息处理程序的执行，以捕获和处理异常。

WebSocket 异常处理流程

错误处理机制在 WsProxy 类中实现，该类：

  1. 在目标回调周围创建一个代理函数
  2. 捕获执行期间抛出的异常
  3. 将异常传递给 WebSocket 异常处理程序
  4. 处理同步错误和 Observable 中的错误

来源

与 NestJS 核心功能的集成

NestJS 中的 WebSockets 通过上下文创建器与核心框架功能集成，这些上下文创建器为 WebSocket 事件建立执行 Pipelined。

上下文创建和 Pipelined

与 RouterExecutionContext 为 HTTP 请求和 RpcContextCreator 为微服务设置执行上下文类似，WsContextCreator 类为 WebSocket 消息设置执行上下文。这些上下文创建器共享相似的模式，但针对其特定的通信协议进行了调整。

WebSockets 与 NestJS 核心的集成

WebSocket 上下文创建遵循以下步骤：

  1. 元数据提取：从装饰器中提取参数的元数据。
  2. 管道设置：为参数转换创建 Pipelined。
  3. 守卫设置：为访问控制创建守卫。
  4. 拦截器设置：为请求/响应转换创建拦截器。
  5. 代理创建：创建一个代理函数来处理消息并管理 Pipelined。

这些步骤确保 WebSocket 消息处理与 HTTP 请求处理具有相同的功能。

来源

参数绑定和转换

WebSockets 支持参数提取和转换，这与 HTTP 控制器类似。 WsParamsFactory 负责根据参数装饰器从 WebSocket 事件中提取值。

参数处理包括：

  1. 参数元数据提取：使用装饰器定义要提取的数据。
  2. 参数值提取：从 WebSocket 事件中提取值。
  3. 管道应用：使用管道转换参数值。

参数提取遵循与 HTTP 请求和微服务相同的模式，并具有适当的上下文类型和元数据。

来源

总结

NestJS 中的 WebSockets 提供了一个全面的实时通信框架，该框架与 NestJS 生态系统的其余部分无缝集成。其实现遵循 NestJS 其余部分相同的架构模式，使其使用起来一致且直观。

主要组成部分包括：

  1. WebSocket 网关：处理 WebSocket 连接和事件的类。
  2. 消息处理程序：响应特定事件类型的​​方法。
  3. WebSocket 适配器：与 Socket.IO 和原生 WebSockets 的集成。
  4. 执行 Pipelined：用于 WebSocket 消息的守卫、拦截器、管道和异常过滤器。

该架构旨在模块化和可扩展，允许开发人员在 Socket.IO 或原生 WebSockets 等不同的 WebSocket 实现之间进行选择，同时保持一致的编程模型。

相关主题