express-validator v5 到 v6 迁移完全指南：从 legacy 中间件到 check API 的实战升级

后端【免费下载链接】express-validatorAn express.js middleware for validator.js.项目地址https://gitcode.com/gh_mirrors/ex/express-validator点击查看免费下载express-validator v6 是一次架构级的重构它放弃了挂在app上的单体中间件legacy API转向以check()系列函数为核心的声明式 check API。本文完整覆盖迁移文档中的每一步操作——移除全局中间件、替换全部 13 组 API 映射、改造自定义校验器/净化器、重写错误获取方式并结合当前仓库源码解释.run(req)、validationResult()与withDefaults()背后的实现机制帮助你在升级包之后手动完成一次干净、无遗漏的迁移。迁移前提升级运行环境迁移文档开篇就明确了支持范围的变化Node 6 不再受支持你必须升级到 Node 8 或更新版本。从当前仓库的 package.json 可以确认这一要求还在不断提高——现版本7.3.2的engines字段已声明node: 14.0.0依赖为lodash ^4.18.1与validator ~13.15.35。也就是说如果你是从 v5 一路迁上来请确保你的 CI 与生产环境 Node 版本同时满足历史文档Node 8与当前仓库Node 14的底线。迁移过程是纯手动的升级 npm 包之后必须按下文步骤逐一改造代码没有自动化工具可以代劳。第一步移除 legacy 全局中间件v5 中express-validator 是一个添加一次即可作用于所有请求的单体中间件// v5 legacy 写法需要删除 const expressValidator require(express-validator); app.use(expressValidator());v6 起express-validator 不再是这样一个全局中间件。你需要从 Express 应用配置中删除所有app.use(expressValidator())语句校验逻辑将下沉到每一个路由处理器内部。如果 v5 时代你曾给expressValidator()传入过选项customValidators、customSanitizers、errorFormatter等它们并不会随中间件一起消失——请继续阅读下面「自定义校验器/净化器」与「获取校验错误」两节v6 为每一类选项提供了新的等价写法。第二步把校验链从 req 方法改为 check 函数这是迁移的主体工作。v5 的校验/净化全部以req上的方法发起v6 则改为一组独立的工厂函数。你需要在整个代码库中完成如下替换Fromv5 legacyTov6 check APIreq.check(field)、req.assert(field)、req.validate(field)await check(field)req.checkBody(field)await body(field)req.checkCookies(field)await cookie(field)req.checkHeaders(field)await header(field)req.checkParams(field)await param(field)req.checkQuery(field)await query(field)req.sanitize(field)、req.filter(field)await sanitize(field)req.sanitizeBody(field)await sanitizeBody(field)req.sanitizeCookies(field)await sanitizeCookie(field)req.sanitizeHeaders(field)await sanitizeHeader(field)req.sanitizeParams(field)await sanitizeParam(field)req.sanitizeQuery(field)await sanitizeQuery(field)另外你还必须在这些链的末尾追加.run(req)来真正执行它。迁移文档给出的完整示例diff 形式 const { body, sanitizeBody } require(express-validator); app.post(/contact-us, (req, res) { - req.checkBody(email).isEmail(); await body(email).isEmail().run(req); - req.sanitizeBody(message) await sanitizeBody(message) .escape() - .trim(); .trim() .run(req); });这段示例背后有两个容易踩坑的点结合源码可以看得更清楚body()、query()等并不是“自由函数”而是由统一工厂生成的变体。在 validation-chain-builders.ts 中buildCheckFunction(locations)接收一个请求位置数组返回一个绑定该位置的check变体check同时扫描[body, cookies, headers, params, query]而body只扫描[body]cookie/header/param/query同理。因此 v6 里check(field)会跨所有位置找字段而body(field)则严格限定在req.body这正是对 v5req.check与req.checkBody语义区分的准确复刻。.run(req)是异步的返回 Promise。在 context-runner.ts 中ContextRunner接口定义run(req: Request, options?): PromiseResultWithContext所以链上必须await。它还提供了一个dryRun选项默认false置为true时错误与净化结果不会持久化到req上——这对“试算”场景例如只想看看校验结果而不污染请求很有用。值得说明的是body、check等返回的既是校验链也是 Express 中间件——从 validation-chain.ts 的ValidationChain接口可以看到它除了继承Validators、Sanitizers、ContextHandler、ContextRunner外还实现了(req, res, next) void签名因此你既可以在处理器内await显式执行也可以把链直接挂到路由上作为中间件使用。第三步改造自定义校验器与净化器v5 中自定义校验器/净化器定义在基础中间件的选项里随app.use(expressValidator(...))对所有链生效// v5 写法需要删除 app.use(expressValidator({ customValidators: { isEmailNotInUse }, customSanitizers: { muteOffensiveWords } }));v6 取消了这种“全局注入”。你需要把每个自定义校验器/净化器就地包裹到对应链上的.custom()或.customSanitizer()中- const expressValidator require(express-validator); const { body, sanitize } require(express-validator); const isEmailNotInUse async value { /* check if email is not taken by other user */ }; const muteOffensiveWords value { /* replace offensive words with *** */ }; - app.use(expressValidator({ - customValidators: { isEmailNotInUse }, - customSanitizers: { muteOffensiveWords } - })); app.use(/sign-up, (req, res) { - req.checkBody(email).isEmailNotInUse(); await body(email).custom(isEmailNotInUse).run(req); }); app.use(/contact-us, (req, res) { - req.sanitize(message).muteOffensiveWords(); await sanitize(message).customSanitizer(muteOffensiveWords).run(req); });注意两个细节自定义校验器允许是异步函数如isEmailNotInUse要查库判断邮箱是否占用写成async即可而链上的方法调用顺序不再受中间件影响因为每条链都是独立的执行单元。第四步重写获取校验错误的方式v5 通过req上的方法获取错误v6 统一改为显式调用validationResult(req)。完整替换对照表Fromv5 legacyTov6req.validationErrors()、await req.asyncValidationErrors()validationResult(req).array()req.validationErrors(true)、await req.asyncValidationErrors(true)validationResult(req).mapped()req.getValidationResult()validationResult(req)自定义 errorFormatter 的等价迁移如果 v5 中间件里定义过errorFormatter选项v6 的对应做法是用validationResult.withDefaults()创建一个带默认格式器的自定义validationResult函数- const expressValidator require(express-validator); const { body, validationResult } require(express-validator); const errorFormatter (param, msg, value) { /* return something */ }; - app.use(expressValidator({ - errorFormatter - })); const myValidationResult validationResult.withDefaults({ formatter: errorFormatter }); app.use(/sign-up, (req, res) { - req.checkBody(email).isEmailNotInUse(); await body(email).custom(isEmailNotInUse).run(req); - const errors req.validationErrors(); const errors myValidationResult(req).array(); });这段 API 在 validation-result.ts 中有完整实现值得对照阅读validationResult本身是一个withDefaultsValidationError()的调用结果默认格式器原样返回错误对象并通过Object.assign把withDefaults静态方法挂了上去所以validationResult.withDefaults({ formatter })返回的myValidationResult就是一个可替换格式的工厂函数工厂函数内部从req[contextsKey]取出所有已执行的校验上下文用flatMap汇总各上下文的errors构造Result实例Result类提供四个核心方法array()返回错误数组、mapped()按字段名映射为对象同一字段只保留第一个错误、isEmpty()判断是否有错、formatWith()换用另一格式器并返回新Result。也就是说上表中的array()/mapped()语义差异并非约定俗成而是由Result.array()与Result.mapped()的实现直接保证的——mapped()里对field类型错误以path为键、其他类型以_${type}为键且已存在的键不会被覆盖。统一入口的导出结构validationResult与全部 check 构建函数都从包根入口导出。查看 index.ts 可以看到express-validator的公共 API 包括./middlewares/validation-chain-builders即check/body/query等、./validation-result、./matched-data、./middlewares/schema等——这正是下文“弃用”一节所承诺的“一切皆可从express-validator直接导入”的源码依据。弃用项子路径导入从 v6 起从express-validator/check和express-validator/filter导入已被弃用运行时会在你的应用控制台打印警告信息。所有导出现在应直接从express-validator主入口导入。如果你的代码中存在这些子路径require请在本轮迁移中顺手改掉以免警告日志污染生产环境。其他破坏性变更与版本适用说明迁移文档建议参考 v6.0.0 的 release notes 了解其余破坏性变更原文以 GitHub 外链给出此处不重复外部链接仓库内另有 migration-v6-to-v7.md 可继续查阅 v6 到 v7 的变化。适用前提本文依据的是 v7.3.0 版的存档迁移文档migration-v5-to-v6.md其内容与docs/migration-v5-to-v6.md一致。如果你直接从 v5 跳到当前 v7请先完成本指南再叠加 v6→v7 的迁移步骤如果你已在 v5 时期采用过 check APIexpress-validator/check则第二步大部分工作可跳过只需处理子路径导入弃用与错误获取方式。校验链的每个环节都可独立测试与复用链本身是纯数据加方法集合.run(req)才触发执行这使 v6 的代码更容易编写单元测试。迁移检查清单升级完成后可以用这份清单做一次全库自查搜索并删除所有app.use(expressValidator(...))及其选项对象customValidators/customSanitizers/errorFormatter搜索req.check、req.assert、req.validate、req.sanitize、req.filter按上表逐一替换为check/body/query/sanitize*函数确认每条校验/净化链末尾都有.run(req)且调用处有await或作为中间件挂载将所有req.validationErrors()/req.getValidationResult()替换为validationResult(req)的.array()/.mapped()把 v5 的errorFormatter选项迁移到validationResult.withDefaults({ formatter })搜索express-validator/check、express-validator/filter子路径导入改为主入口导入确认 Node 运行时 ≥ 8若使用 v7则 ≥ 14见 package.json 的engines。完成以上七步你的应用就完成了从 legacy 单体中间件到 v6 声明式 check API 的迁移。赞分享后端【免费下载链接】express-validatorAn express.js middleware for validator.js.项目地址https://gitcode.com/gh_mirrors/ex/express-validator点击查看免费下载相关推荐express-validator 从 v5 升级到 v6 迁移指南express validator 从 v5 升级到 v6 迁移指南 前言 还在为 express validator v5 到 v6 的迁移而头疼吗面对大量后端Buzz 教程十分钟完成第一次本地语音转录Buzz 教程十分钟完成第一次本地语音转录 Buzz 是一款在你个人电脑上离线完成语音转录和翻译的工具底层引擎是 OpenAI 的开源语音识别模型 Whis人工智能语音音频本地部署桌面应用Express-Validator 从 v5 迁移到 v6 完全指南Express Validator 从 v5 迁移到 v6 完全指南 前言 Express Validator 是 Express 框架中用于数据验证和清理的重后端上一篇文件格式伪装工具Apate3种模式快速绕过系统限制下一篇全面战争模组制作神器RPFM让你告别复杂代码轻松打造专属游戏世界创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考