欢迎来到关于使用 NestJS、Prisma 和 PostgreSQL 构建 REST API 系列的第二篇教程!在本教程中,您将学习如何在 API 中执行输入验证和转换。
目录
简介
在本系列的第一部分中,您创建了一个新的 NestJS 项目,并将其与 Prisma、PostgreSQL 和 Swagger 集成。然后,您为博客应用程序的后端构建了一个基本的 REST API。
在本部分中,您将学习如何验证输入,使其符合您的 API 规范。执行输入验证是为了确保只有来自客户端的格式正确的数据才能通过您的 API。最佳实践是验证发送到 Web 应用程序的任何数据的正确性。这有助于防止格式错误的数据和对 API 的滥用。
您还将学习如何执行输入转换。输入转换是一种技术,允许您在数据被请求的路由处理程序处理之前拦截和转换来自客户端的数据。这对于将数据转换为适当的类型、对缺失字段应用默认值、清理输入等非常有用。
开发环境
要跟随本教程学习,您需要安装以下内容:
- 已安装 Node.js。
- 已安装 Docker 或 PostgreSQL。
- 已安装 Prisma VSCode 扩展。 (可选)
- 能够访问 Unix shell(例如 Linux 和 macOS 中的终端/shell)以运行本系列中提供的命令。 (可选)
注意:
可选的 Prisma VS Code 扩展为 Prisma 提供了不错的智能感知和语法高亮功能。
如果您没有 Unix shell(例如,您使用的是 Windows 机器),您仍然可以按照步骤操作,但 shell 命令可能需要根据您的机器进行修改。
克隆仓库
本教程的起点是本系列第一部分的结尾。它包含一个使用 NestJS 构建的基本 REST API。我建议您在开始本教程之前完成第一部分。
本教程的起点位于 GitHub 仓库的 begin-validation 分支。要开始,请克隆仓库并切换到 begin-validation
分支
现在,执行以下操作以开始
- 导航到克隆的目录
- 安装依赖
- 使用 docker 启动 PostgreSQL 数据库
- 应用数据库迁移
- 启动项目
注意:步骤 4 还会生成 Prisma Client 并填充数据库。
现在,您应该可以通过 http://localhost:3000/api/
访问 API 文档。
项目结构和文件
您克隆的仓库应该具有以下结构
该仓库中值得注意的文件和目录有
src
目录包含应用程序的源代码。共有三个模块app
模块位于src
目录的根目录下,是应用程序的入口点。它负责启动 Web 服务器。prisma
模块包含 Prisma Client,您的数据库查询构建器。articles
模块定义了/articles
路由的端点以及相应的业务逻辑。
prisma
模块包含以下内容schema.prisma
文件定义了数据库模式。migrations
目录包含数据库迁移历史记录。seed.ts
文件包含一个脚本,用于向您的开发数据库填充模拟数据。
docker-compose.yml
文件定义了您的 PostgreSQL 数据库的 Docker 镜像。.env
文件包含您的 PostgreSQL 数据库的连接字符串。
注意:有关这些组件的更多信息,请参阅本教程系列的第一部分。
执行输入验证
为了执行输入验证,您将使用NestJS Pipes。管道作用于路由处理程序正在处理的参数。Nest 在路由处理程序之前调用管道,管道接收传给路由处理程序的参数。管道可以执行许多操作,例如验证输入、向输入添加字段等。管道类似于中间件,但管道的作用范围仅限于处理输入参数。NestJS 提供了一些内置管道,但您也可以创建自己的自定义管道。
管道有两种典型的用例
- 验证:评估输入数据,如果有效则不变地传递;否则,在数据不正确时抛出异常。
- 转换:将输入数据转换为所需的格式(例如,从字符串转换为整数)。
NestJS 验证管道将检查传递给路由的参数。如果参数有效,管道将参数不变地传递给路由处理程序。但是,如果参数违反任何指定的验证规则,管道将抛出异常。
下面两张图展示了验证管道对于任意 /example
路由的工作原理。
在本节中,您将重点关注验证用例。
全局设置 ValidationPipe
为了执行输入验证,您将使用内置的 NestJS ValidationPipe
。 ValidationPipe
提供了一种方便的方法来强制执行所有传入客户端负载的验证规则,这些验证规则使用 class-validator
包中的装饰器进行声明。
要使用此功能,您需要向项目添加两个包
class-validator 包提供了用于验证输入数据的装饰器,class-transformer 包提供了用于将输入数据转换为所需格式的装饰器。这两个包都与 NestJS 管道很好地集成。
现在,在您的 main.ts
文件中导入 ValidationPipe
,并使用 app.useGlobalPipes
方法使其在您的应用程序中全局可用
为 CreateArticleDto
添加验证规则
现在,您将使用 class-validator
包为 CreateArticleDto
添加验证装饰器。您将对 CreateArticleDto
应用以下规则
title
不能为空或少于 5 个字符。description
最大长度不能超过 300。body
和description
不能为空。title
、description
和body
必须是string
类型,published
必须是boolean
类型。
打开 src/articles/dto/create-article.dto.ts
文件,并将其内容替换为以下代码
这些规则将被 ValidationPipe
捕获并自动应用于您的路由处理程序。使用装饰器进行验证的一个优点是 CreateArticleDto
仍然是 POST /articles
端点所有参数的唯一事实来源。因此,您无需定义单独的验证类。
测试您已设置的验证规则。尝试使用 POST /articles
端点创建一个具有非常短的占位符 title
的文章,如下所示
您应该会收到 HTTP 400 错误响应,以及响应正文中关于违反了哪个验证规则的详细信息。
此图解释了 ValidationPipe
在幕后对 /articles
路由的无效输入所做的工作
从客户端请求中剥离不必要的属性
CreateArticleDTO
定义了需要发送到 POST /articles
端点以创建新文章的属性。 UpdateArticleDTO
也做了同样的事情,但用于 PATCH /articles/{id}
端点。
当前,对于这两个端点,都可以发送 DTO 中未定义的额外属性。这可能导致无法预料的错误或安全问题。例如,您可以手动将无效的 createdAt
和 updatedAt
值传递给 POST /articles
端点。由于 TypeScript 类型信息在运行时不可用,您的应用程序将无法识别这些字段在 DTO 中不可用。
举个例子,尝试向 POST /articles
端点发送以下请求
通过这种方式,您可以注入无效值。这里您创建了一篇文章,其 updatedAt
值早于 createdAt
,这是没有意义的。
为了防止这种情况,您需要过滤客户端请求中任何不必要的字段/属性。幸运的是,NestJS 也提供了开箱即用的功能。您只需在应用程序内部初始化 ValidationPipe
时传递 whitelist: true
选项即可。
将此选项设置为 true 后,ValidationPipe
将自动移除所有 非白名单 属性,其中“非白名单”指没有任何验证装饰器的属性。需要注意的是,此选项将过滤掉 所有 没有验证装饰器的属性,即使它们在 DTO 中定义了。
现在,传递给请求的任何额外字段/属性都将被 NestJS 自动剥离,从而阻止了之前展示的攻击。
注意:NestJS
ValidationPipe
具有高度的可配置性。所有可用的配置选项都记录在NestJS 文档中。如有必要,您还可以为您的应用程序构建自定义验证管道。
使用 ParseIntPipe
转换动态 URL 路径
在您的 API 中,您当前将 GET /articles/{id}
、PATCH /articles/{id}
和 DELETE /articles/{id}
端点的 id 参数作为路径的一部分接受。NestJS 从 URL 路径中将 id
参数解析为字符串。然后,在将其传递给 ArticlesService 之前,在您的应用程序代码中将该字符串转换为数字。例如,看看 DELETE /articles/{id}
路由处理程序
由于 id
定义为字符串类型,Swagger API 也在生成的 API 文档中将此参数记录为字符串。这是不直观且不正确的。
您可以使用 NestJS 管道自动将 id
转换为数字,而无需在路由处理程序中手动进行此转换。将内置的 ParseIntPipe
添加到这三个端点的控制器路由处理程序中
ParseIntPipe
将拦截字符串类型的 id
参数,并在将其传递给相应的路由处理程序之前自动将其解析为数字。这样做还有一个优点,就是可以在 Swagger 中正确地将 id
参数记录为数字。
总结与最后说明
恭喜!在本教程中,您对现有的 REST API 进行了以下操作:
- 使用
ValidationPipe
集成了验证功能。 - 剥离了客户端请求中不必要的属性。
- 集成了
ParseIntPipe
,用于解析string
路径变量并将其转换为number
。
您可能已经注意到 NestJS 大量依赖于装饰器。这是一个非常刻意的设计选择。NestJS 旨在通过大量利用装饰器来处理各种横切关注点,从而提高代码的可读性和模块化。因此,控制器和服务方法无需为了处理验证、缓存、日志等事情而填充大量样板代码。
您可以在 GitHub 仓库的 end-validation 分支中找到本教程的完成代码。如果您发现问题,请随时在仓库中提出 issue 或提交 PR。您也可以直接在 Twitter 上联系我。
不要错过下一篇文章!
订阅 Prisma 时事通讯