express-validator 从 v5 升级到 v6 迁移指南

express-validator 从 v5 升级到 v6 迁移指南

express-validator 项目地址: https://gitcode.com/gh_mirrors/exp/express-validator

前言

express-validator 是一个流行的 Express 中间件，用于验证和清理 HTTP 请求数据。在从 v5 升级到 v6 的过程中，开发者需要注意一些重大变更。本文将详细介绍这些变更以及如何进行迁移。

环境要求变更

首先需要注意的是，v6 版本不再支持 Node.js 6。如果你的项目还在使用 Node.js 6，必须升级到 Node.js 8 或更高版本才能使用 express-validator v6。

从旧版 API 迁移到检查 API

如果你之前使用的是 express-validator 的旧版 API，那么需要进行以下迁移步骤。

应用配置变更

在 v5 中，我们通常这样初始化 express-validator：

const expressValidator = require('express-validator');
app.use(expressValidator());

在 v6 中，这种全局中间件的方式已被移除。你需要删除这行代码，改为在路由处理程序中直接使用验证器。

路由处理程序变更

验证/清理链的语法变化

v6 引入了全新的 API 语法，主要变化如下：

1. 所有验证和清理方法现在需要从 express-validator 直接导入
2. 方法调用需要添加 await 关键字
3. 每个链式调用最后需要添加 .run(req)

具体方法名称变化对照表：

| v5 方法 | v6 方法 | |---------|---------| | req.check()/req.assert()/req.validate() | check() | | req.checkBody() | body() | | req.checkCookies() | cookie() | | req.checkHeaders() | header() | | req.checkParams() | param() | | req.checkQuery() | query() | | req.sanitize()/req.filter() | sanitize() | | req.sanitizeBody() | sanitizeBody() | | req.sanitizeCookies() | sanitizeCookie() | | req.sanitizeHeaders() | sanitizeHeader() | | req.sanitizeParams() | sanitizeParam() | | req.sanitizeQuery() | sanitizeQuery() |

示例代码对比：

// v5 写法
req.checkBody('email').isEmail();
req.sanitizeBody('message').escape().trim();

// v6 写法
await body('email').isEmail().run(req);
await sanitizeBody('message').escape().trim().run(req);

自定义验证器和清理器

在 v5 中，自定义验证器和清理器是通过中间件配置全局注册的：

app.use(expressValidator({
  customValidators: { isEmailNotInUse },
  customSanitizers: { muteOffensiveWords }
}));

在 v6 中，改为在验证链中直接使用：

await body('email').custom(isEmailNotInUse).run(req);
await sanitize('message').customSanitizer(muteOffensiveWords).run(req);

验证错误处理

错误处理 API 也发生了变化：

| v5 方法 | v6 方法 | |---------|---------| | req.validationErrors()/req.asyncValidationErrors() | validationResult(req).array() | | req.validationErrors(true)/req.asyncValidationErrors(true) | validationResult(req).mapped() | | req.getValidationResult() | validationResult(req) |

如果你在 v5 中使用了自定义错误格式化函数，可以这样迁移：

// v5
app.use(expressValidator({
  errorFormatter
}));

// v6
const myValidationResult = validationResult.withDefaults({ formatter: errorFormatter });
const errors = myValidationResult(req).array();

废弃的导入方式

在 v5 中，我们通常这样导入模块：

const { check } = require('express-validator/check');
const { sanitize } = require('express-validator/filter');

在 v6 中，这些导入方式已被废弃，改为直接从主模块导入：

const { check, sanitize } = require('express-validator');

其他重大变更

除了上述主要变更外，v6 还包含一些其他重要变化：

1. 移除了对旧版 API 的支持
2. 改进了异步验证的处理方式
3. 优化了错误处理机制
4. 增强了类型定义（对 TypeScript 用户更友好）

迁移建议

1. 逐步迁移：对于大型项目，建议逐步迁移，可以先从简单的路由开始
2. 测试覆盖：确保有足够的测试覆盖，特别是在验证逻辑复杂的部分
3. 团队沟通：如果项目是团队协作，确保所有成员都了解这些变更
4. 文档更新：更新项目文档中关于数据验证的部分

总结

express-validator v6 带来了更现代化、更一致的 API 设计。虽然迁移需要一些工作，但新的 API 更加直观和灵活，特别是对异步操作的支持更加完善。通过本文的指导，你应该能够顺利完成从 v5 到 v6 的迁移工作。

express-validator 项目地址: https://gitcode.com/gh_mirrors/exp/express-validator