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

Express 应用配置变化

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

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

在 v6 中，这种全局中间件的方式已被移除。你需要：

1. 删除所有 app.use(expressValidator()) 的调用
2. 直接在路由处理程序中使用验证链

验证和清理链的变化

v6 引入了全新的 API 设计，主要变化包括：

1. 所有验证和清理方法现在都是异步的，需要使用 await
2. 每个链的末尾必须调用 .run(req)
3. 方法命名更加一致和直观

以下是新旧 API 对比表：

| v5 方法 | v6 等效方法 | |----------------------------|-----------------------------| | req.check(field) | await check(field) | | req.checkBody(field) | await body(field) | | req.sanitize(field) | await sanitize(field) | | req.sanitizeBody(field) | await sanitizeBody(field) |

示例迁移：

// 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 也有显著变化：

| v5 方法 | v6 等效方法 | |-------------------------------------|-----------------------------------| | req.validationErrors() | validationResult(req).array() | | req.validationErrors(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();

废弃的功能

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 还包含一些其他重要变更：

1. 验证链现在是不可变的，每次方法调用都会返回新实例
2. 某些验证方法的错误消息格式可能有所调整
3. 性能优化，特别是在处理大量验证规则时

迁移建议

1. 逐步迁移：大型项目可以逐个路由进行迁移
2. 全面测试：迁移后对所有表单和API端点进行充分测试
3. 错误处理：特别注意错误处理逻辑的变化
4. 性能监控：虽然v6性能更好，但仍建议监控关键路径

总结

Express-Validator v6 带来了更清晰、更一致的API设计，虽然迁移需要一些工作，但最终会带来更可维护和可靠的代码。本文涵盖了从v5到v6迁移的所有关键方面，按照这些指导进行升级，可以确保平稳过渡到新版本。

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