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

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

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

express-validator 是一个流行的 Express 中间件，用于验证和清理请求数据。本文将详细介绍从 v6 升级到 v7 版本需要进行的更改，帮助开发者顺利完成迁移。

环境要求变更

首先需要注意的是，v7 版本不再支持 Node.js 12。如果你的项目还在使用 Node.js 12，需要先升级到 Node.js 14 或更高版本。

已移除的废弃 API

导入路径变更

v6.0.0 开始废弃的从 express-validator/check 和 express-validator/filter 导入的方式，在 v7 中已被完全移除。现在所有功能都应该直接从 express-validator 导入。

清理专用 API 移除

v7 移除了所有 sanitize 开头的函数，因为这些功能已经完全被 check 系列函数覆盖。以下是替换对照表：

| 旧函数 | 新函数 | |-----------------------|---------------| | sanitize(field) | check(field) | | sanitizeBody(field) | body(field) | | ... | ... |

TypeScript 类型变更

一些 TypeScript 类型名称也进行了简化：

| 旧类型 | 新类型 | |-----------------------|------------| | ValidationParamSchema | ParamSchema | | Validationchema | Schema |

验证器变更

isObject() 行为变化

isObject() 验证器的 strict 选项默认值从 false 改为 true。这意味着默认情况下不再允许数组和 null 值通过验证。

如果需要保持 v6 的行为，需要显式设置：

check('object').isObject({ strict: false })

验证错误格式变更

v7 对验证错误的格式做了较大调整，以支持更多错误类型。

属性名变更

param 属性已更名为 path，以避免与请求参数混淆：

const errors = validationResult(req).array();
console.log(`字段错误: ${errors[0].path}`);  // 以前是 param

错误类型区分

现在错误对象是一个可区分的联合类型，处理时需要根据类型进行不同处理：

const result = validationResult(req).formatWith(error => {
  switch (error.type) {
    case 'field':
      // 字段验证错误
      return `${error.path} 字段验证失败`;
    case 'alternative':
      // 替代验证错误
      return "提供的选项都不符合要求";
    // 其他类型处理...
  }
});

oneOf() 验证器变更

函数签名变化

oneOf() 的第二个参数从直接传递消息改为传递选项对象：

oneOf(
  [check('email'), check('phone')],
  { message: '至少提供一种联系方式' }
)

如果使用函数返回消息，现在会接收到嵌套错误信息：

oneOf([...], {
  message: (nestedErrors, req) => {
    // 可以访问嵌套错误
    return req.translate('one_of_error');
  }
})

错误类型配置

v7 为 oneOf() 添加了 errorType 选项来控制错误返回格式。要保持 v6 行为，需要：

oneOf([...], { errorType: 'flat' })

升级建议

1. 首先确保 Node.js 版本符合要求
2. 使用查找替换工具批量修改导入路径和函数名
3. 特别注意 isObject() 的默认行为变化
4. 检查所有错误处理逻辑，适应新的错误格式
5. 测试 oneOf() 验证器的行为是否符合预期

升级完成后，建议全面测试应用的验证逻辑，确保所有边界情况都被正确处理。express-validator v7 的这些改进使 API 更加一致和灵活，虽然需要一些迁移工作，但长期来看会提高代码的可维护性。

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