express-validator matchedData() 完全指南：提取已校验与清洗请求数据的核心 API

后端【免费下载链接】express-validatorAn express.js middleware for validator.js.项目地址https://gitcode.com/gh_mirrors/ex/express-validator点击查看免费下载导读matchedData()是 express-validator 提供的用于从请求对象中回读“已被校验链处理过”的数据的核心工具函数。无论是数据分散在req.body、req.query、req.params等多个位置还是字段通过嵌套路径与通配符wildcard选取matchedData()都能将其还原成一个干净的普通对象。读完本篇你将掌握matchedData()的全部选项includeOptionals、onlyValidData、locations及其默认行为、底层实现原理、典型实战场景以及如何结合.optional()、oneOf()、通配符等特性正确取数。一、函数是什么从“校验链”到“干净数据”的最后一步在 express-validator 中校验链如check(email).isEmail()负责对请求字段进行校验与清洗sanitize错误信息则交给validationResult(req)读取。但如果你希望拿到“校验/清洗后的字段值”——比如把清洗后的值直接用于写数据库、构造日志或传递给下游服务——就需要matchedData()。它接收 express 请求对象req返回一个由 express-validator 校验或清洗过的数据构成的普通对象Recordstring, any。嵌套路径如foo.bar与通配符如foo.*同样会被正确还原成嵌套结构。二、函数签名与参数详解2.1 签名const { matchedData } require(express-validator); matchedData(req[, options])在 TypeScript 中见 docs/api/matched-data.md其类型定义如下import { matchedData } from express-validator; matchedData(req, options?: { includeOptionals?: boolean, onlyValidData?: boolean, locations?: Location[], })其中req是 express 的请求对象。options为可选参数包含以下三个配置项选项类型默认值含义includeOptionalsbooleanfalse返回结果是否包含被标记为可选.optional()但请求中未出现的字段onlyValidDatabooleantrue返回结果是否仅包含通过校验的字段设为false时连未通过校验的字段数据也一并返回locationsLocation[]undefined指定从哪些请求位置取数可选值body、cookies、headers、params、query不设置时表示所有位置返回一个对象包含 express-validator 已校验或清洗过的数据。这些默认值在源码中被明确标注见 src/matched-data.ts 中的MatchedDataOptions类型定义includeOptionals默认falseonlyValidData默认truelocations缺省时视为“全部位置”。2.2 参数语义速查includeOptionals: true把“声明为可选、但请求中未提供”的字段也纳入结果。原文档特别提醒某些数据库更新场景下如果可选值缺失数据库可能理解为“不更新这些字段”因此将缺失的可选字段显式设为null或空字符串往往更符合预期。onlyValidData: false把未通过校验的字段数据也带回来。默认true时校验失败的字段会从结果中剔除。locations只从列出的位置取数。例如[query]只返回来自req.query的字段。默认情况下undefinedmatchedData会聚合所有位置中“被校验链处理过”的字段。三、底层实现原理从源码看取数全过程matchedData()的实现并不神秘理解它有助于规避使用中的各种边界问题。其核心实现位于 src/matched-data.tsexport function matchedDataT extends object Recordstring, any( req: Request, options: PartialMatchedDataOptions {}, ): T { const internalReq: InternalRequest req; const fieldExtractor createFieldExtractor(options.includeOptionals ! true); const validityFilter createValidityFilter(options.onlyValidData); const locationFilter createLocationFilter(options.locations); return _(internalReq[contextsKey]) .flatMap(fieldExtractor) .filter(validityFilter) .map(field field.instance) .filter(locationFilter) .reduce((state, instance) _.set(state, instance.path, instance.value), {} as T); }整个流程是一条 lodash 管道依次经历五个阶段读取校验上下文internalReq[contextsKey]。所有校验链运行后都会把自身的Context上下文挂到请求对象上键名为express-validator#contexts定义见 src/base.ts。这解释了为什么matchedData(req)必须在校验中间件运行之后调用——数据来源是校验链写入请求的上下文而不是直接读取req.body。展开字段实例createFieldExtractor对每个Context调用context.getData({ requiredOnly: removeOptionals })取出该上下文记录的FieldInstance字段路径 值 位置。当includeOptionals为true时requiredOnly为false可选字段也会被包含进来。过滤有效性createValidityFilter在onlyValidData为true时逐个检查该字段是否在其所属上下文的errors中命中了type: field且location、path完全匹配的错误记录命中即视为“无效数据”并剔除。过滤位置createLocationFilter在locations未指定空数组时放行所有位置指定后只保留locations.includes(field.location)的字段。重建嵌套对象利用 lodash 的_.set(state, instance.path, instance.value)把诸如bar.baz.qux这样的路径还原成{ bar: { baz: { qux: 4 } } }的嵌套结构——这正是matchedData能正确处理嵌套路径与通配符的原因。其中“可选字段”的判断逻辑在 src/context.ts 的Context.getData()中当requiredOnly为真且上下文声明了 optional 时会按optional的取值undefined/null/falsy对字段值做存在性过滤如value ! undefined、value ! null等。配套快捷方式在部分版本中validationResult对象的matchedData()方法只是对上述函数的透传封装见 src/express-validator.ts 的注释“This method is a shortcut formatchedData; it does nothing different than it.”。四、实战示例以下示例均取自官方文档website/versioned_docs/version-6.8.0/api-matched-data.md并补充了当前版本文档docs/api/matched-data.md中的进阶用法。4.1 从多个位置收集数据当被校验的数据分散在req.body、req.query、req.params等不同位置时matchedData()会自动把它们聚合起来你也可以用locations自定义取数范围// 假设请求形如 // req.query { from: 2017-01-12 } // req.body { to: 2017-31-12 } app.post(/room-availability, check([from, to]).isISO8601(), (req, res, next) { const queryData matchedData(req, { locations: [query] }); const bodyData matchedData(req, { locations: [body] }); const allData matchedData(req); console.log(queryData); // { from: 2017-01-12 } console.log(bodyData); // { to: 2017-31-12 } console.log(allData); // { from: 2017-01-12, to: 2017-31-12 } });这里check([from, to])会在默认位置body、cookies、headers、params、query中查找这两个字段matchedData(req)不指定locations时即可拿到来自 query 与 body 的完整结果。4.2 包含可选数据includeOptionals你可能希望返回结果中同时包含那些“声明为可选、但请求里没出现”的字段// 假设请求形如 // req.body { name: John Doe, bio: } app.post(/update-user, [ check(name).not().isEmpty(), check(bio).optional({ checkFalsy: true }).escape(), ], (req, res, next) { const requiredData matchedData(req, { includeOptionals: false }); const allData matchedData(req, { includeOptionals: true }); console.log(requiredData); // { name: John Doe } console.log(allData); // { name: John Doe, bio: } });注意bio的被optional({ checkFalsy: true })视为“未提供”因此默认的requiredData中不含它而includeOptionals: true时该字段已被.escape()清洗会出现在结果中。关于.optional()的取值语义undefined/null/falsy与“非位置性”特征可参考 docs/api/validation-chain.md。4.3 包含未通过校验的数据onlyValidData默认情况下校验失败的字段不会出现在结果中把onlyValidData设为false可将其一并带回app.post(/signup, body(email).isEmail(), body(password).notEmpty(), (req, res) { const data matchedData(req, { onlyValidData: false }); // { email: not_actually_an_email, password: } });在 src/matched-data.spec.ts 的测试中可以看到当foo的值为bla、bar为123且都经过.isInt()校验时onlyValidData: false会把两个字段原样返回——即使foo校验失败。4.4 指定取数位置locations只关心某个位置的数据时用locations收窄范围app.post( /signup, [body(email).isEmail(), body(password).notEmpty(), query(subscribe_newsletter).isBoolean()], (req, res) { const data matchedData(req); // { email: foobar.com, password: 12345, subscribe_newsletter: true } const data2 matchedData(req, { locations: [query] }); // { subscribe_newsletter: true } }, );五、TypeScript 泛型用法matchedData的签名支持传入泛型作为返回类型默认类型为Recordstring, any。这样可以让取出的数据具备完整的类型提示import { matchedData } from express-validator; app.post( /contact-us, [body(email).isEmail(), body(message).notEmpty(), body(phone).optional().isMobilePhone()], (req, res) { const result validationResult(req); if (!result.isEmpty()) { // 处理校验错误 return res.send(Please fix the request); } const data matchedData{ email: string; message: string; phone?: string; }(req); }, );六、与通配符、oneOf 等特性的协同6.1 通配符与嵌套路径matchedData()能正确处理通配符wildcard校验的结果。官方测试用例src/matched-data.spec.ts验证了这一点当使用check([foo.*, *.*.qux]).isInt()校验数组与嵌套对象时matchedData(req)能还原出完整的嵌套结构// req { headers: { foo: [1, 2, 3] }, query: { bar: { baz: { qux: 4 } } } } matchedData(req) // { foo: [1, 2, 3], bar: { baz: { qux: 4 } } }6.2 与 oneOf() 配合时的“有效数据”判定matchedData()的有效性过滤与oneOf()的上下文错误是联动的。测试用例src/matched-data.spec.ts展示了重要行为当oneOf()的一组备选链中某条校验失败时该备选组内“看起来有效”的字段也不会被返回只有通过oneOf()整体判定的备选链中校验过的数据才会进入结果。因此在oneOf()场景下onlyValidData默认值true的过滤以最终有效的备选组为准。6.3 何时不能使用 matchedData校验链未运行matchedData()读取的是校验链写入req[contextsKey]的上下文。如果校验链尚未执行例如没有把校验中间件挂到路由或使用了 手动运行模式 却未调用.run(req)那么没有上下文可读。测试用例works if no validation or sanitization chains ransrc/matched-data.spec.ts证实此时matchedData({})返回空对象{}。需要原始请求数据matchedData只返回“被校验链处理过”的字段。若需要未经过校验的原始req.body全量数据应直接读取req.body。6.4 多位置同时校验的取值细节从源码 src/context.ts 可以看出当同一字段在多个位置如body与query都有email被校验时Context.getData()要求所有位置都通过校验才保留该字段若所有位置都未提供该字段则至少保留一个实例用于错误报告。这意味着matchedData返回结果的字段取舍与Context对多位置字段的合并规则保持一致。七、小结与最佳实践场景推荐用法需要把校验/清洗后的数据写入数据库const data matchedData(req);默认仅有效、非可选数据更新操作缺失的可选字段也要显式落库matchedData(req, { includeOptionals: true })并把缺失值处理为null或调试、日志需要看到校验失败字段的原始值matchedData(req, { onlyValidData: false })只关心 query/params 等特定位置的数据matchedData(req, { locations: [query, params] })需要强类型的返回结果matchedDataMyShape(req)最后提醒三点其一matchedData(req)必须在校验中间件执行之后调用其二它默认只返回通过校验且非可选缺失的数据这与直接读req.body的语义有本质区别其三嵌套路径与通配符字段会被自动还原为嵌套对象无需手工拍平。更多字段选择、通配符与 globstar 的用法可参考 docs/guides/field-selection.md校验结果对象含matchedData()快捷方法见 docs/api/validation-result.md。赞分享后端【免费下载链接】express-validatorAn express.js middleware for validator.js.项目地址https://gitcode.com/gh_mirrors/ex/express-validator点击查看免费下载相关推荐express-validator matchedData() 完全指南从请求中提取已验证与已清洗数据express validator matchedData 完全指南从请求中提取已验证与已清洗数据 matchedData 是 express validat后端express-validator matchedData() 完全指南从请求中提取已校验数据express validator matchedData 完全指南从请求中提取已校验数据 导读 matchedData 是 express validato后端如何解决华硕主板 FanControl 传感器识别问题完整排查指南如何解决华硕主板 FanControl 传感器识别问题完整排查指南 你打开 FanControl准备画风扇曲线发现主界面的传感器列表是空的CPU 温度一后端上一篇PPTist终极部署指南从零到精通的完整配置方案下一篇腾讯混元3D-Omni开源四模态控制重构3D资产生产流程效率提升10倍创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考