后端【免费下载链接】express-validatorAn express.js middleware for validator.js.项目地址https://gitcode.com/gh_mirrors/ex/express-validator点击查看免费下载本篇技术指南围绕 express-validator v5.3.0 的Filter API展开该 API 通过require(express-validator/filter)提供。文章核心覆盖两大能力用matchedData()从请求中抽取已被checkAPI 校验过的数据并重组为干净对象以及用sanitize()及其位置变体、buildSanitizeFunction()构建针对不同请求位置的清洗链。阅读完本文你将掌握每个函数的参数语义、默认值、底层实现原理与实战用法并能正确将其迁移到 v6/v7 的新式 API。概述Filter API 在 express-validator 中的定位在 express-validator v5.3.0 中代码按职责拆分为两个独立入口require(express-validator/check)提供check、body、query等校验相关 APIrequire(express-validator/filter)提供matchedData、sanitize、sanitizeBody、sanitizeCookie、sanitizeParam、sanitizeQuery、buildSanitizeFunction等数据抽取与清洗相关 API。Filter API 回答了两个常见问题校验通过后如何方便地拿到一个只含合法数据的干净对象以及如何在不使用整个express-validator中间件的情况下单独对请求字段做清洗本文对应的原版文档位于仓库 website/versioned_docs/version-5.3.0/api-filter.md。需要注意在 v6.0.0 之后express-validator/check与express-validator/filter两个入口均被废弃会向控制台打印警告所有 API 统一从express-validator主入口导入详见 docs/migration-v5-to-v6.md。本文讲解的 API 语义在 v5.3.0 中即为如此而其底层行为至今仍可在仓库源码src/matched-data.ts与src/express-validator.ts中得到印证。matchedData(req[, options])抽取已校验数据matchedData是 Filter API 的核心函数。它的作用是从请求中提取已被checkAPI 校验过的数据并组装成一个对象返回。嵌套路径与通配符wildcards都会被正确处理。函数签名与返回值matchedData(req[, options])reqExpress 的 request 对象。options可选一个对象支持以下选项includeOptionals设为true时返回值包含被标记为 optional 的数据默认false。onlyValidData设为false时返回值将包含未通过校验字段的数据默认true。locations一个数组指定从哪些请求位置抽取数据。可接受的值包括body、cookies、headers、params和query默认undefined表示所有位置。返回值由checkAPI 校验过的数据组成的对象。基础示例原文档给出了一个极具代表性的完整示例覆盖了按位置抽取与全量抽取两种用法// Suppose the request looks like this: // 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 } });可以看到不传locations时matchedData会把不同位置query、body的数据合并进同一个对象传入locations数组后则只输出指定位置的字段。三个选项的完整语义includeOptionals默认false当一个字段链被标记为.optional()且请求中没有该字段值为undefined时该字段默认不会出现在matchedData的结果中。将includeOptionals设为true后这些缺省但可选的字段也会被纳入结果值为undefined或按 optional 规则判定。从源码看这一选项直接映射到Context.getData({ requiredOnly })的行为src/matched-data.ts当removeOptionals为true时Context会按字段的optional设置过滤掉undefined、nulloptional null时或 falsyoptional falsy时的值过滤逻辑见 src/context.ts。onlyValidData默认true默认情况下只要某个字段在对应位置存在校验错误error.type field且location、path匹配该字段的值就不会被返回。当设为false时即使字段未通过校验也会被包含进结果。对应源码中的createValidityFiltersrc/matched-data.ts它为false时直接放行所有数据为true时则检查该字段在 context 的errors数组中是否存在匹配的 field 类型错误。locations默认undefined即全部位置限定抽取范围。源码中createLocationFiltersrc/matched-data.ts的实现很直白locations为空数组时不过滤任何位置否则只保留locations.includes(field.location)的字段。位置的可选值在 src/base.ts 中定义为body | cookies | headers | params | query。底层工作原理matchedData的读取路径在 src/matched-data.ts 中非常清晰可以总结为一条流水线从req的express-validator#contexts键源码常量contextsKey见 src/base.ts取出校验中间件在运行时写入的全部Context对象用flatMap将每个 Context 中的字段实例FieldInstance连同其所属 Context 展开成扁平列表用validityFilter过滤掉有校验错误的字段用locationFilter过滤掉不在指定位置的字段最后通过 lodash 的_.set(state, instance.path, instance.value)按字段路径重组出嵌套对象——这正是嵌套路径如user.name与通配符如foo.*能被正确还原成层级结构的原因。这一实现还被ExpressValidator类的实例方法matchedData复用src/express-validator.ts该方法注释明确说明它是matchedData的快捷方式行为完全一致。由测试用例验证的行为细节仓库中的 src/matched-data.spec.ts 覆盖了文档提到的全部选项组合可直接作为行为契约未运行任何校验/清洗链时返回{}matchedData({})不会抛错默认情况下只包含有效且非 optional的数据check([foo, bar, baz]).optional().isInt()作用于{ headers: { foo: bla, bar: 123 } }时结果只有{ bar: 123 }——foo因未通过isInt被剔除baz因 optional 且缺失被剔除通配符校验结果会被正确合并如check([foo.*, *.*.qux]).isInt()返回嵌套的{ foo: [1, 2, 3], bar: { baz: { qux: 4 } } }在oneOf()中失败的链组其字段即使本身值合法也不会被包含——避免把来自失败分支的数据当作可信数据includeOptionals: true时缺失的 optional 字段baz会出现在结果中onlyValidData: false时未通过isInt的foo: bla也会被返回locations: [params, query]时只返回params与query位置的数据headers中的数据被忽略。sanitize(fields)创建通用清洗链sanitize(fields)fields一个字段名字符串或字符串数组。返回值一个 Sanitization Chain。sanitize为单个或多个字段创建清洗链这些字段可以位于以下任意请求对象中req.bodyreq.cookiesreq.paramsreq.query注意req.headers在 v5.3.0 中暂不支持。关键语义如果某个字段在多个位置同时存在那么该字段在所有位置的实例都会被清洗。一个典型的组合用法是清洗链 中间件执行例如对用户输入做转义与去空格const { sanitizeBody } require(express-validator/filter); app.post(/contact-us, (req, res) { sanitizeBody(message).escape().trim(); // ...后续处理 });v5 时代清洗链通常依赖全局中间件或直接执行迁移到 v6 后需要改为await sanitize(message).escape().trim().run(req)并在路由中使用express-validator主入口导入参见 docs/migration-v5-to-v6.md。位置限定变体sanitizeBody/sanitizeCookie/sanitizeParam/sanitizeQuery四个变体与sanitize(fields)的唯一区别在于清洗位置被锁定函数作用位置等价写法sanitizeBody(fields)仅req.bodybuildSanitizeFunction([body])(fields)sanitizeCookie(fields)仅req.cookiesbuildSanitizeFunction([cookies])(fields)sanitizeParam(fields)仅req.paramsbuildSanitizeFunction([params])(fields)sanitizeQuery(fields)仅req.querybuildSanitizeFunction([query])(fields)它们与校验侧body()、cookie()、param()、query()的对应关系一致——在 v5.3.0 的 api-check.md 中check系列同样按位置拆分。清洗动作通过 Sanitization Chain 执行链上的每个清洗器在运行时被封装为Sanitization上下文项src/context-items/sanitization.ts数组值会被逐元素清洗字符串化toString后交给 validator.js 的标准清洗器结果写回 Context 的 dataMap供后续读取或matchedData使用。buildSanitizeFunction(locations)自定义位置组合buildSanitizeFunction(locations)locations一个请求位置数组可包含body、cookies、params或query中的任意组合。返回值一个sanitize()的变体只清洗传入的这些位置。buildSanitizeFunction让我们不必为每种组合手写位置判断而是直接产出绑定了位置集合的清洗函数。原文档示例非常实用const { buildSanitizeFunction } require(express-validator/filter); const sanitizeBodyAndQuery buildSanitizeFunction([body, query]); app.put(/update-product, [ // id 无论出现在 req.body 还是 req.query都会被转换为 int sanitizeBodyAndQuery(id).toInt() ], productUpdateHandler)当业务上允许某个字段既可能在 body 中也可能在 query 中例如 REST 中 id 可来自路径查询参数时buildSanitizeFunction([body, query])一次即可覆盖两个位置这正是sanitize(fields)多位置同时清洗语义的灵活运用。常见问题与注意事项req.headers不被sanitize支持v5.3.0 的 Filter API 中清洗侧无法覆盖 headers如果需要清洗 headers 中的数据只能在校验侧借助header()与自定义逻辑处理。相比之下校验侧check系列是支持 headers 的。多位置同名字段字段若同时出现在 body 与 querysanitize(fields)会清洗所有实例这与check中多位置同时校验的语义见 api-check.md保持一致底层Context.getData在多位置、多实例场景下还会做去重与至少包含一个用于报错的兜底处理src/context.ts。matchedData依赖校验链先运行matchedData读取的是校验中间件写入req的 contexts 数据express-validator#contexts。如果没有任何check链运行过返回空对象{}不会抛错——这一点有 src/matched-data.spec.ts 的测试保证。v6 迁移express-validator/filter入口在 v6 起废弃统一改为require(express-validator)同时sanitize系列清洗链需要追加.run(req)才会真正执行详见 docs/migration-v5-to-v6.md。小结Filter API 是 express-validator v5.3.0 中数据出口与数据清洗的一体化工具matchedData(req, options)以三个选项includeOptionals、onlyValidData、locations精确控制返回的数据范围内部借助express-validator#contexts存储、Context.getData过滤与 lodash_.set重组天然支持嵌套路径与通配符sanitize(fields)及其四个位置变体sanitizeBody、sanitizeCookie、sanitizeParam、sanitizeQuery把清洗链绑定到指定请求位置buildSanitizeFunction(locations)则进一步支持任意位置组合。这些行为的正确性在仓库测试 src/matched-data.spec.ts 中有完整覆盖读者可据此验证本文结论并在升级到 v6/v7 时无缝迁移 API 形态。赞分享后端【免费下载链接】express-validatorAn express.js middleware for validator.js.项目地址https://gitcode.com/gh_mirrors/ex/express-validator点击查看免费下载相关推荐把孩子的涂鸦变成会跳舞的AI动画一条命令搞定把孩子的涂鸦变成会跳舞的AI动画一条命令搞定 孩子画的小人永远只是纸上的一团线条而 AnimatedDrawings 这个开源项目能让孩子的手绘人物直接动后端Apache DolphinScheduler 发布组装模块 dolphinscheduler-dist 全解析二进制包、源码包与 Docker 镜像的构建原理Apache DolphinScheduler 发布组装模块 dolphinscheduler dist 全解析二进制包、源码包与 Docker 镜像的构建原后端express-validator matchedData() 完全指南从请求中提取已验证与已清洗数据express validator matchedData 完全指南从请求中提取已验证与已清洗数据 matchedData 是 express validat后端上一篇在hub-proxy项目中实现GitHub资源缓存中转的技术解析下一篇Microsoft-Office-For-MacOS自动化脚本一键完成安装配置流程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/10/10 5:14:57 · 阅读 1.2k express-validator v5.3.0 Filter API 完全指南：matchedData 数据抽取与 sanitize 系列清洗函数
后端【免费下载链接】express-validatorAn express.js middleware for validator.js.项目地址https://gitcode.com/gh_mirrors/ex/express-validator点击查看免费下载本篇技术指南围绕 express-validator v5.3.0 的Filter API展开该 API 通过require(express-validator/filter)提供。文章核心覆盖两大能力用matchedData()从请求中抽取已被checkAPI 校验过的数据并重组为干净对象以及用sanitize()及其位置变体、buildSanitizeFunction()构建针对不同请求位置的清洗链。阅读完本文你将掌握每个函数的参数语义、默认值、底层实现原理与实战用法并能正确将其迁移到 v6/v7 的新式 API。概述Filter API 在 express-validator 中的定位在 express-validator v5.3.0 中代码按职责拆分为两个独立入口require(express-validator/check)提供check、body、query等校验相关 APIrequire(express-validator/filter)提供matchedData、sanitize、sanitizeBody、sanitizeCookie、sanitizeParam、sanitizeQuery、buildSanitizeFunction等数据抽取与清洗相关 API。Filter API 回答了两个常见问题校验通过后如何方便地拿到一个只含合法数据的干净对象以及如何在不使用整个express-validator中间件的情况下单独对请求字段做清洗本文对应的原版文档位于仓库 website/versioned_docs/version-5.3.0/api-filter.md。需要注意在 v6.0.0 之后express-validator/check与express-validator/filter两个入口均被废弃会向控制台打印警告所有 API 统一从express-validator主入口导入详见 docs/migration-v5-to-v6.md。本文讲解的 API 语义在 v5.3.0 中即为如此而其底层行为至今仍可在仓库源码src/matched-data.ts与src/express-validator.ts中得到印证。matchedData(req[, options])抽取已校验数据matchedData是 Filter API 的核心函数。它的作用是从请求中提取已被checkAPI 校验过的数据并组装成一个对象返回。嵌套路径与通配符wildcards都会被正确处理。函数签名与返回值matchedData(req[, options])reqExpress 的 request 对象。options可选一个对象支持以下选项includeOptionals设为true时返回值包含被标记为 optional 的数据默认false。onlyValidData设为false时返回值将包含未通过校验字段的数据默认true。locations一个数组指定从哪些请求位置抽取数据。可接受的值包括body、cookies、headers、params和query默认undefined表示所有位置。返回值由checkAPI 校验过的数据组成的对象。基础示例原文档给出了一个极具代表性的完整示例覆盖了按位置抽取与全量抽取两种用法// Suppose the request looks like this: // 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 } });可以看到不传locations时matchedData会把不同位置query、body的数据合并进同一个对象传入locations数组后则只输出指定位置的字段。三个选项的完整语义includeOptionals默认false当一个字段链被标记为.optional()且请求中没有该字段值为undefined时该字段默认不会出现在matchedData的结果中。将includeOptionals设为true后这些缺省但可选的字段也会被纳入结果值为undefined或按 optional 规则判定。从源码看这一选项直接映射到Context.getData({ requiredOnly })的行为src/matched-data.ts当removeOptionals为true时Context会按字段的optional设置过滤掉undefined、nulloptional null时或 falsyoptional falsy时的值过滤逻辑见 src/context.ts。onlyValidData默认true默认情况下只要某个字段在对应位置存在校验错误error.type field且location、path匹配该字段的值就不会被返回。当设为false时即使字段未通过校验也会被包含进结果。对应源码中的createValidityFiltersrc/matched-data.ts它为false时直接放行所有数据为true时则检查该字段在 context 的errors数组中是否存在匹配的 field 类型错误。locations默认undefined即全部位置限定抽取范围。源码中createLocationFiltersrc/matched-data.ts的实现很直白locations为空数组时不过滤任何位置否则只保留locations.includes(field.location)的字段。位置的可选值在 src/base.ts 中定义为body | cookies | headers | params | query。底层工作原理matchedData的读取路径在 src/matched-data.ts 中非常清晰可以总结为一条流水线从req的express-validator#contexts键源码常量contextsKey见 src/base.ts取出校验中间件在运行时写入的全部Context对象用flatMap将每个 Context 中的字段实例FieldInstance连同其所属 Context 展开成扁平列表用validityFilter过滤掉有校验错误的字段用locationFilter过滤掉不在指定位置的字段最后通过 lodash 的_.set(state, instance.path, instance.value)按字段路径重组出嵌套对象——这正是嵌套路径如user.name与通配符如foo.*能被正确还原成层级结构的原因。这一实现还被ExpressValidator类的实例方法matchedData复用src/express-validator.ts该方法注释明确说明它是matchedData的快捷方式行为完全一致。由测试用例验证的行为细节仓库中的 src/matched-data.spec.ts 覆盖了文档提到的全部选项组合可直接作为行为契约未运行任何校验/清洗链时返回{}matchedData({})不会抛错默认情况下只包含有效且非 optional的数据check([foo, bar, baz]).optional().isInt()作用于{ headers: { foo: bla, bar: 123 } }时结果只有{ bar: 123 }——foo因未通过isInt被剔除baz因 optional 且缺失被剔除通配符校验结果会被正确合并如check([foo.*, *.*.qux]).isInt()返回嵌套的{ foo: [1, 2, 3], bar: { baz: { qux: 4 } } }在oneOf()中失败的链组其字段即使本身值合法也不会被包含——避免把来自失败分支的数据当作可信数据includeOptionals: true时缺失的 optional 字段baz会出现在结果中onlyValidData: false时未通过isInt的foo: bla也会被返回locations: [params, query]时只返回params与query位置的数据headers中的数据被忽略。sanitize(fields)创建通用清洗链sanitize(fields)fields一个字段名字符串或字符串数组。返回值一个 Sanitization Chain。sanitize为单个或多个字段创建清洗链这些字段可以位于以下任意请求对象中req.bodyreq.cookiesreq.paramsreq.query注意req.headers在 v5.3.0 中暂不支持。关键语义如果某个字段在多个位置同时存在那么该字段在所有位置的实例都会被清洗。一个典型的组合用法是清洗链 中间件执行例如对用户输入做转义与去空格const { sanitizeBody } require(express-validator/filter); app.post(/contact-us, (req, res) { sanitizeBody(message).escape().trim(); // ...后续处理 });v5 时代清洗链通常依赖全局中间件或直接执行迁移到 v6 后需要改为await sanitize(message).escape().trim().run(req)并在路由中使用express-validator主入口导入参见 docs/migration-v5-to-v6.md。位置限定变体sanitizeBody/sanitizeCookie/sanitizeParam/sanitizeQuery四个变体与sanitize(fields)的唯一区别在于清洗位置被锁定函数作用位置等价写法sanitizeBody(fields)仅req.bodybuildSanitizeFunction([body])(fields)sanitizeCookie(fields)仅req.cookiesbuildSanitizeFunction([cookies])(fields)sanitizeParam(fields)仅req.paramsbuildSanitizeFunction([params])(fields)sanitizeQuery(fields)仅req.querybuildSanitizeFunction([query])(fields)它们与校验侧body()、cookie()、param()、query()的对应关系一致——在 v5.3.0 的 api-check.md 中check系列同样按位置拆分。清洗动作通过 Sanitization Chain 执行链上的每个清洗器在运行时被封装为Sanitization上下文项src/context-items/sanitization.ts数组值会被逐元素清洗字符串化toString后交给 validator.js 的标准清洗器结果写回 Context 的 dataMap供后续读取或matchedData使用。buildSanitizeFunction(locations)自定义位置组合buildSanitizeFunction(locations)locations一个请求位置数组可包含body、cookies、params或query中的任意组合。返回值一个sanitize()的变体只清洗传入的这些位置。buildSanitizeFunction让我们不必为每种组合手写位置判断而是直接产出绑定了位置集合的清洗函数。原文档示例非常实用const { buildSanitizeFunction } require(express-validator/filter); const sanitizeBodyAndQuery buildSanitizeFunction([body, query]); app.put(/update-product, [ // id 无论出现在 req.body 还是 req.query都会被转换为 int sanitizeBodyAndQuery(id).toInt() ], productUpdateHandler)当业务上允许某个字段既可能在 body 中也可能在 query 中例如 REST 中 id 可来自路径查询参数时buildSanitizeFunction([body, query])一次即可覆盖两个位置这正是sanitize(fields)多位置同时清洗语义的灵活运用。常见问题与注意事项req.headers不被sanitize支持v5.3.0 的 Filter API 中清洗侧无法覆盖 headers如果需要清洗 headers 中的数据只能在校验侧借助header()与自定义逻辑处理。相比之下校验侧check系列是支持 headers 的。多位置同名字段字段若同时出现在 body 与 querysanitize(fields)会清洗所有实例这与check中多位置同时校验的语义见 api-check.md保持一致底层Context.getData在多位置、多实例场景下还会做去重与至少包含一个用于报错的兜底处理src/context.ts。matchedData依赖校验链先运行matchedData读取的是校验中间件写入req的 contexts 数据express-validator#contexts。如果没有任何check链运行过返回空对象{}不会抛错——这一点有 src/matched-data.spec.ts 的测试保证。v6 迁移express-validator/filter入口在 v6 起废弃统一改为require(express-validator)同时sanitize系列清洗链需要追加.run(req)才会真正执行详见 docs/migration-v5-to-v6.md。小结Filter API 是 express-validator v5.3.0 中数据出口与数据清洗的一体化工具matchedData(req, options)以三个选项includeOptionals、onlyValidData、locations精确控制返回的数据范围内部借助express-validator#contexts存储、Context.getData过滤与 lodash_.set重组天然支持嵌套路径与通配符sanitize(fields)及其四个位置变体sanitizeBody、sanitizeCookie、sanitizeParam、sanitizeQuery把清洗链绑定到指定请求位置buildSanitizeFunction(locations)则进一步支持任意位置组合。这些行为的正确性在仓库测试 src/matched-data.spec.ts 中有完整覆盖读者可据此验证本文结论并在升级到 v6/v7 时无缝迁移 API 形态。赞分享后端【免费下载链接】express-validatorAn express.js middleware for validator.js.项目地址https://gitcode.com/gh_mirrors/ex/express-validator点击查看免费下载相关推荐把孩子的涂鸦变成会跳舞的AI动画一条命令搞定把孩子的涂鸦变成会跳舞的AI动画一条命令搞定 孩子画的小人永远只是纸上的一团线条而 AnimatedDrawings 这个开源项目能让孩子的手绘人物直接动后端Apache DolphinScheduler 发布组装模块 dolphinscheduler-dist 全解析二进制包、源码包与 Docker 镜像的构建原理Apache DolphinScheduler 发布组装模块 dolphinscheduler dist 全解析二进制包、源码包与 Docker 镜像的构建原后端express-validator matchedData() 完全指南从请求中提取已验证与已清洗数据express validator matchedData 完全指南从请求中提取已验证与已清洗数据 matchedData 是 express validat后端上一篇在hub-proxy项目中实现GitHub资源缓存中转的技术解析下一篇Microsoft-Office-For-MacOS自动化脚本一键完成安装配置流程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考