Express-Validator 项目中的旧版API详解

Express-Validator 项目中的旧版API详解

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

概述

Express-Validator 是一个用于 Express 应用的强大数据验证和清理库。在版本5.2.0中，项目仍然保留了旧版API（Legacy API），这是为了向后兼容版本3及更早的应用。本文将详细介绍这个旧版API的功能和使用方法。

为什么需要了解旧版API

虽然官方建议新应用不要使用旧版API，但了解它仍然很有价值：

1. 维护旧项目时需要理解原有代码
2. 理解验证机制的发展历程
3. 在某些特定场景下可能仍有使用价值

核心概念

旧版API的核心思想是通过中间件向Express的请求对象(req)添加验证和清理方法。这种方式与新版API有显著不同，新版采用了更现代的链式调用方式。

安装与配置

要使用旧版API，首先需要设置全局中间件：

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

中间件选项

配置对象middlewareOptions支持以下属性：

1. errorFormatter：自定义错误信息格式的函数

   • 参数：param(参数名), msg(错误信息), value(参数值), location(参数位置)
   • 返回：格式化后的错误对象

2. customValidators：自定义验证器对象

   • 键为验证器名称
   • 值为验证函数，接收参数值和可选的配置项

3. customSanitizers：自定义清理器对象

   • 键为清理器名称
   • 值为清理函数，接收参数值和可选的配置项

验证功能详解

基本验证方法

req.check(field[, message])是最基础的验证方法：

• field：要验证的字段名
• message：可选的自定义错误信息

该方法会检查以下请求对象中的字段（按优先级顺序）：

1. req.params
2. req.query
3. req.body
4. req.headers
5. req.cookies

特定位置验证

针对不同位置的参数，有专门的验证方法：

• req.checkBody()：仅验证req.body
• req.checkCookies()：仅验证req.cookies
• req.checkHeaders()：仅验证req.headers
• req.checkParams()：仅验证req.params
• req.checkQuery()：仅验证req.query

验证链扩展

旧版验证链提供了额外的验证方法：

1. .notEmpty()：检查值长度至少为1
2. .len()：检查值长度（可指定最小、最大或精确长度）

数据清理功能

基本清理方法

req.sanitize(field)创建清理链：

• 清理后的值会直接修改原始请求对象中的值
• 如果字段存在于多个位置，所有位置的值都会被清理

特定位置清理

与验证类似，清理也有针对特定位置的方法：

• req.sanitizeBody()
• req.sanitizeCookies()
• req.sanitizeHeaders()
• req.sanitizeParams()
• req.sanitizeQuery()

验证结果处理

获取验证结果

req.getValidationResult()返回一个Promise，解析为包含所有验证错误的对象。这是处理验证结果的推荐方式。

错误处理快捷方法

1. req.asyncValidationErrors([mapped])：

   • 返回Promise，验证通过时resolve，失败时reject
   • mapped参数控制错误返回格式（数组或对象）

2. req.validationErrors([mapped])：

   • 同步返回验证结果
   • 不等待异步验证器完成

模式验证

旧版API支持基于模式的验证，可以一次性验证多个字段及其规则。语法与新版的模式验证相同。

最佳实践与注意事项

1. 新项目应避免使用旧版API，因为它可能不会获得新功能更新，甚至在未来版本中被移除

2. 如果必须使用旧版API，建议：

   • 明确记录使用原因
   • 保持一致的验证风格
   • 考虑逐步迁移到新版API

3. 在性能敏感场景下，同步验证方法(validationErrors)可能比异步方法更快，但会牺牲部分功能

总结

Express-Validator的旧版API提供了一套完整的请求数据验证和清理方案。虽然它已经被更现代的新版API所取代，但理解它的工作原理对于维护旧代码库和深入理解数据验证机制仍然很有帮助。对于新项目，建议使用新版API以获得更好的功能支持和长期维护。

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