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

nestjs/nest

菜单

请求处理管道

相关源文件

本文档详细解释了 NestJS 如何通过其管道架构处理传入的请求。请求处理管道定义了从请求到达直到响应发送回客户端的事件序列。理解此管道对于在请求处理的各个阶段实现自定义逻辑至关重要，例如验证、转换、授权和错误处理。

有关异常处理的更多信息，请参阅 异常处理。

管道阶段概述

NestJS 请求处理管道由按特定顺序执行的多个组件组成

来源

请求生命周期

1. 中间件 (Middleware)

中间件在路由处理程序之前执行。它用于发生在每个请求或基于路径匹配规则的请求组中的常见任务。

在 NestJS 中，中间件可以是

  • 函数中间件（简单的函数）
  • 类中间件（实现 NestMiddleware 接口）
  • Express 中间件（兼容 Express.js 中间件）

中间件执行遵循基于模块距离的拓扑顺序，全局中间件最先执行，最近模块中间件最后执行。

来源

2. 守卫 (Guards)

守卫决定是否处理或拒绝请求。它们主要用于授权目的。

守卫实现 CanActivate 接口并返回一个布尔值，指示请求是否应该继续。它们可以访问执行上下文，这允许它们检查请求和正在访问的路由。

来源

3. 拦截器（之前）(Interceptors (Before))

拦截器在路由处理程序之前和之后执行。“之前”阶段发生在守卫执行之后、管道执行之前。

拦截器可以

  • 在方法执行之前/之后绑定额外的逻辑
  • 转换函数返回的结果
  • 转换从函数抛出的异常
  • 扩展函数的基本行为
  • 根据特定条件完全覆盖函数

来源

4. 管道 (Pipes)

管道在路由处理程序处理之前转换或验证输入数据。

管道处理传递给路由处理程序的参数。它们作用于传递给处理程序方法的参数，就在调用处理程序之前。

来源

5. 路由处理程序 (Route Handler)

路由处理程序是控制器中处理请求并返回响应的方法。

处理程序接收来自管道阶段的已处理和已验证的参数，并执行业务逻辑。它可以返回不同类型的响应

  • 标准值（字符串、对象、数组）
  • 值的 Promise
  • Observable 流

来源

6. 拦截器（之后）(Interceptors (After))

在路由处理程序返回结果后，“之后”阶段的拦截器执行。

拦截器在“之后”阶段按反向顺序执行。这允许进行响应的嵌套处理，其中第一个看到请求的拦截器是最后一个看到响应的。

来源

7. 异常过滤器 (Exception Filters)

异常过滤器处理在请求处理管道的任何阶段抛出的异常。

当发生异常时，NestJS 会查找与抛出的异常类型匹配的异常过滤器。过滤器可以绑定到

  • 特定的路由处理程序
  • 控制器
  • 全局

来源

响应处理

在通过所有管道阶段后，NestJS 会在将响应发送给客户端之前处理它。

RouterResponseController 处理各种类型的响应

  • 标准的 JSON/文本响应
  • 重定向（带状态码）
  • 使用模板渲染视图
  • 服务器发送事件 (SSE) 用于实时更新

来源

实现细节

上下文创建和传播 (Context Creation and Propagation)

请求处理管道依赖于执行上下文在各个阶段之间传递信息。

当请求到达时，NestJS

  1. 为请求生成唯一的上下文 ID
  2. 将此 ID 附加到请求对象
  3. 确定是否涉及请求作用域处理程序
  4. 创建适当的执行上下文

来源

处理程序执行流程 (Handler Execution Flow)

路由处理程序的核心执行流程由 RouterExecutionContext 类管理。

RouterExecutionContext 中的 create() 方法通过以下方式准备执行过程

  1. 使用元数据设置上下文
  2. 创建守卫、管道和拦截器函数
  3. 构建主执行处理程序

来源

平台适配 (Platform Adaptation)

NestJS 通过适配器抽象底层 HTTP 平台（Express/Fastify）。

管道使用抽象适配器来

  • 注册路由
  • 处理响应
  • 处理中间件
  • 管理错误处理

来源

非 HTTP 请求处理 (Non-HTTP Request Processing)

虽然本文档主要关注 HTTP 请求，但 NestJS 也使用类似的管道来处理其他类型的请求

WebSockets 管道

来源

微服务管道 (Microservices Pipeline)

来源

配置管道

控制器和方法装饰器

控制器及其方法构成了请求管道的骨干。装饰器会按以下方式影响管道

来源

消息模式装饰器

对于微服务，消息模式定义了消息的路由方式

来源

管道实战：示例流程

以下是一个请求通过管道的详细示例，其中包含所有组件

来源

总结

NestJS 请求处理管道通过一系列明确定义的阶段，提供了一种结构化的请求处理方法。每个阶段都有特定的用途

  1. 中间件 (Middleware)：通用的请求处理逻辑
  2. 守卫 (Guards)：授权和请求验证
  3. 拦截器（前置）(Interceptors (Before))：预处理和转换
  4. 管道 (Pipes)：参数验证和转换
  5. 路由处理器 (Route Handler)：核心业务逻辑
  6. 拦截器（后置）(Interceptors (After))：后处理和响应转换
  7. 异常过滤器 (Exception Filters)：错误处理

理解此管道使开发人员能够

  • 在适当的阶段注入自定义逻辑
  • 根据职责分离关注点
  • 一致地应用横切关注点
  • 在不同级别上优雅地处理错误

这种架构创建了一个灵活、模块化的系统来处理请求，同时保持了清晰的关注点分离。