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

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

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

前言

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

环境要求变更

Node.js 版本支持变化：

• 不再支持 Node.js 6
• 最低要求升级到 Node.js 8 或更高版本

从旧版 API 迁移到检查 API

Express 应用配置变更

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

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

在 v6 版本中，不再需要这样的全局中间件设置。你需要：

1. 完全移除 app.use(expressValidator()) 这行代码
2. 直接在路由处理程序中使用验证链

路由处理程序改造

验证/清理链语法变更

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

1. 所有验证方法现在需要从主模块导入
2. 方法调用方式从 req.checkXxx() 变为 await body()/query()/param() 等
3. 每条链必须以 .run(req) 结束

常用方法对照表：

| v5 方法 | v6 等效方法 | |----------------------------|-----------------------------| | req.check(field) | await check(field) | | req.checkBody(field) | await body(field) | | req.checkQuery(field) | await query(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 版本中，自定义验证器/清理器是通过中间件选项全局注册的：

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

v6 版本中，必须在每个验证链中单独指定：

// 自定义验证器
await body('email').custom(isEmailNotInUse).run(req);

// 自定义清理器
await sanitize('message').customSanitizer(muteOffensiveWords).run(req);

验证错误处理

错误处理方式也有显著变化：

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

如果需要自定义错误格式，可以这样处理：

const { validationResult } = require('express-validator');
const myValidationResult = validationResult.withDefaults({
  formatter: (param, msg, value) => {
    // 自定义错误格式
    return `${param}: ${msg}`;
  }
});

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

废弃的功能

v6 版本废弃了从特定子路径导入的方式：

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

// 现在应该直接从主模块导入
const { check, sanitize } = require('express-validator');

其他重大变更

除了上述主要变化外，v6 版本还包括：

1. 内部验证引擎重构，提高了性能和可靠性
2. 更清晰的错误消息格式
3. 改进的类型定义（对 TypeScript 用户更友好）
4. 一些验证方法的细微行为调整

迁移建议

1. 逐步迁移：可以逐个路由进行改造，不必一次性完成
2. 测试覆盖：确保有充分的测试用例覆盖验证逻辑
3. 错误处理：特别注意错误处理代码的兼容性
4. 性能监控：升级后监控应用性能，v6 在某些场景下可能有不同的性能表现

结语

Express-Validator v6 带来了更现代、更一致的 API 设计，虽然迁移需要一些工作量，但长远来看将提高代码的可维护性和可读性。本文涵盖了从 v5 到 v6 迁移的主要方面，按照这些指导进行升级，应该能够顺利完成过渡。

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