Express-Validator 从 v5 迁移到 v6 完全指南

Express-Validator 从 v5 迁移到 v6 完全指南

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

前言

Express-Validator 是一个流行的 Express 中间件，用于验证和清理用户输入数据。从 v5 升级到 v6 版本带来了一些重大变化，本文将详细介绍迁移过程中需要注意的关键点，帮助开发者顺利完成升级。

环境要求变更

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

从旧版 API 迁移到检查 API

应用设置变更

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

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

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

路由处理程序变更

验证/清理链的重构

v6 对验证和清理的语法做了重大调整。以下是新旧 API 的对比：

| 旧版方法 | 新版方法 | |---------|---------| | req.check(field) | await check(field) | | req.checkBody(field) | await body(field) | | req.sanitize(field) | await sanitize(field) |

重要变化：

1. 所有验证/清理链现在需要添加 .run(req) 调用
2. 需要使用 await 关键字（确保你的路由是异步的）

示例改造：

// 旧版 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 中，自定义验证器和清理器是通过中间件选项全局注册的。v6 改为在每个链中单独定义：

// 旧版 v5
app.use(expressValidator({
  customValidators: { isEmailNotInUse },
  customSanitizers: { muteOffensiveWords }
}));

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

验证错误处理

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

| 旧版方法 | 新版方法 | |---------|---------| | req.validationErrors() | validationResult(req).array() | | req.validationErrors(true) | validationResult(req).mapped() |

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

// 创建自定义验证结果处理器
const myValidationResult = validationResult.withDefaults({
  formatter: errorFormatter
});

// 使用方式
const errors = myValidationResult(req).array();

废弃的导入方式

v6 废弃了从 express-validator/check 和 express-validator/filter 导入的方式。现在所有功能都可以直接从主模块导入：

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

// 推荐方式
const { check, sanitize } = require('express-validator');

其他重大变更

除了上述主要变化外，v6 还包含一些其他破坏性变更，建议开发者仔细阅读 v6.0.0 的发布说明，了解完整的变更列表。

迁移建议

1. 逐步迁移：大型项目可以逐个路由进行迁移，而不是一次性全部修改
2. 测试覆盖：确保有充分的测试覆盖，特别是在验证逻辑复杂的部分
3. 错误处理：特别注意错误处理逻辑的变化，这是常见的迁移痛点
4. 异步支持：由于新 API 大量使用 Promise，确保你的路由正确处理异步操作

总结

Express-Validator v6 通过现代化的 API 设计提供了更清晰、更灵活的验证方式。虽然迁移过程需要一些工作，但新版本带来的改进值得投入。本文涵盖了从 v5 迁移到 v6 的主要方面，按照这些指导进行迁移，应该能够顺利完成升级。

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