express-validator 清洗链(Sanitization Chain)API 完全指南:从标准清洗器到自定义清洗的实战与源码解析
express-validator 清洗链(Sanitization Chain)API 完全指南:从标准清洗器到自定义清洗的实战与源码解析
清洗链(Sanitization Chain)是 express-validator 提供的一类内置中间件,用于在 Express 请求进入业务处理前,对 req.body、req.query、req.params、req.cookies、req.headers 中的字段进行原地(in-place)清洗与规范化。本文以 v6.12.0 官方文档(api-sanitization-chain.md)为骨架,结合仓库源码(src/chain/sanitizers-impl.ts、src/context-items/sanitization.ts、src/chain/context-runner-impl.ts)与测试用例(src/chain/sanitizers-impl.spec.ts),带你掌握清洗链的全部 API、执行原理与实战技巧。
什么是清洗链
清洗链本质上是一个 Express 中间件,因此它应当被直接传递给 Express 路由处理器(route handler)作为参数使用。你可以在一根链上添加任意数量的清洗器(sanitizer)。当中间件运行时,它会对每个选中的字段就地修改,并按照添加的顺序依次应用每一个清洗器。
const { body } = require('express-validator');
app.get('/', body('trimMe').trim(), (req, res, next) => {
// 如果 req.body.trimMe 原本是 " something ",
// 清洗后的值将是 "something"
console.log(req.body.trimMe);
});
在这个例子中,body('trimMe') 选中 req.body 中的 trimMe 字段,.trim() 是第一个清洗器;若链上还有后续清洗器,它们会以前一个清洗器的输出作为输入继续处理。从类型定义看,一条完整的 ValidationChain 同时继承了 Validators、Sanitizers、ContextHandler 与 ContextRunner 四组能力(见 src/chain/validation-chain.ts),清洗链正是其中 Sanitizers 部分所构成的行为集合。
标准清洗器(Standard Sanitizers)
validator.js 列出的所有清洗器都可以在清洗链中使用,express-validator 中称之为"标准清洗器(standard sanitizers)"。这意味着你可以直接调用 normalizeEmail、trim、toInt 等方法。
标准清洗器的完整列表及其选项,请参考 validator.js 的 sanitizers 文档。以下方法已由仓库源码确认可用(见 src/chain/sanitizers.ts):
| 方法 | 参数 | 说明 |
|---|---|---|
blacklist(chars) |
string |
移除字符黑名单中出现的字符 |
escape() |
— | 对 HTML 实体(<、>、&、"、')进行转义 |
unescape() |
— | 与 escape() 相反,反转义 HTML 实体 |
ltrim(chars?) |
可选字符串 | 从左侧去除空白(或指定字符) |
rtrim(chars?) |
可选字符串 | 从右侧去除空白(或指定字符) |
trim(chars?) |
可选字符串 | 从两侧去除空白(或指定字符) |
normalizeEmail(options?) |
可选项对象 | 规范化电子邮件地址(如统一小写、去除点号等) |
stripLow(keep_new_lines?) |
可选布尔值 | 移除 ASCII 控制字符,true 时保留换行符 |
toBoolean(strict?) |
可选布尔值 | 将 'true'/'1' 等转为布尔值,strict 模式下仅接受 'true'/'false' |
toDate() |
— | 将字符串转为 Date 对象 |
toFloat() |
— | 将字符串转为浮点数 |
toInt(radix?) |
可选基数 | 将字符串按指定进制转为整数 |
whitelist(chars) |
string |
仅保留字符白名单中出现的字符 |
这些方法由 SanitizersImpl 中的 addStandardSanitization(sanitizer, ...options) 统一登记:每个标准清洗器都被包装为一个 Sanitization 上下文项,并携带调用时传入的选项参数(例如 blacklist('foo') 会生成 new Sanitization(validator.blacklist, false, <a href="https://link.gitcode.com/i/2bf402f6f335d6fc3e1feed25075ffd1" target="_blank">'foo']),这一点在 [sanitizers-impl.spec.ts 的断言中可以得到验证)。
标准清洗器的类型转换行为
注意: 由于 validator.js 的清洗器只接受
string类型的输入,任何需要被标准清洗器处理的值(包括数组和对象)都会被首先转换为字符串再交给清洗器。这正是"数组无法被正确清洗"这一 FAQ 的根源(见 faq.md)。
这一行为在源码 src/context-items/sanitization.ts 中体现得很直接:
const values = Array.isArray(value) ? value : [value];
const newValues = values.map(value => {
return (this.sanitizer as StandardSanitizer)(this.stringify(value), ...this.options);
});
其中 stringify 是 src/utils.ts 导出的 toString 函数,它的转换规则是:
Date实例会转为toISOString()输出;- 带
toString方法的普通对象会调用其toString(); null、undefined、NaN等空值一律转为空字符串'';- 其余值使用
String(value)转换。
因此,如果你对数组字段直接调用 trim() 等标准清洗器,数组会被整体转成 'a,b' 这类逗号拼接的字符串后处理——这正是文档提示"数组清洗结果不符合直觉"的实现层原因。要逐项清洗数组,请使用自定义清洗器(见下文)。
附加方法:清洗链专属增强 API
除标准清洗器外,清洗链还提供以下由 express-validator 自身实现的附加方法。
.customSanitizer(sanitizer)
sanitizer(value, { req, location, path }):自定义清洗函数。它接收被清洗字段的值,以及包含 Express 请求对象req、字段所在位置location、字段路径path(还有通配符展开信息pathValues)的元数据对象(Meta,见 src/base.ts)。- 返回: 当前清洗链实例。
向当前清洗链添加一个自定义清洗器,它必须同步返回新的值。与 validator.js 标准清洗器不同,自定义清洗器收到的就是原始值,不会被强制转成字符串。
const { param } = require('express-validator');
app.get(
'/object/:id',
param('id').customSanitizer((value, { req }) => {
return req.query.type === 'user' ? ObjectId(value) : Number(value);
}),
objectHandler,
);
从源码看,customSanitizer 的实现是直接向 ContextBuilder 添加一个 custom: true 的 Sanitization 项(src/chain/sanitizers-impl.ts)。在运行阶段,Sanitization.run() 会以 await Promise.resolve(sanitizer(value, meta)) 的方式调用它(src/context-items/sanitization.ts),这意味着返回 Promise 的异步自定义清洗器同样会被支持——测试用例 sanitizers-impl.spec.ts 覆盖了异步 resolve 与 reject 两种场景。
.default(default_value)
- 返回: 当前清洗链实例。
当当前值属于 ['', null, undefined, NaN] 这一集合时,用 default_value 替换它。
app.post('/', body('username').default('foo'), (req, res, next) => {
// 'bar' => 'bar'
// '' => 'foo'
// undefined => 'foo'
// null => 'foo'
// NaN => 'foo'
});
实现上,default() 是通过 customSanitizer 实现的(src/chain/sanitizers-impl.ts):
default(default_value: any) {
return this.customSanitizer(value =>
[undefined, null, NaN, ''].includes(value) ? _.cloneDeep(default_value) : value,
);
}
两点值得注意的细节:
- 空字符串
''也会被替换为默认值; - 默认值会经过
_.cloneDeep深拷贝。测试 sanitizers-impl.spec.ts 专门验证了:当默认值是对象时,两次请求得到的默认值对象互不相同(req2.body.foo !== req1.body.foo),避免多个请求共享同一对象引用导致状态污染。
.replace(values_to_replace, new_value)
- 返回: 当前清洗链实例。
当当前值包含在给定的数组 values_to_replace 中时,用 new_value 替换它。
app.post('/', body('username').replace(['bar', 'BAR'], 'foo'), (req, res, next) => {
// 'bar_' => 'bar_'
// 'bar' => 'foo'
// 'BAR' => 'foo'
console.log(req.body.username);
});
源码实现同样基于 customSanitizer(src/chain/sanitizers-impl.ts):
replace(values_to_replace: any, new_value: any) {
if (!Array.isArray(values_to_replace)) {
values_to_replace = [values_to_replace];
}
return this.customSanitizer(value =>
values_to_replace.includes(value) ? _.cloneDeep(new_value) : value,
);
}
需要注意的实现细节:
- 即使
values_to_replace传入的是单个值,也会被自动包装成数组处理; - 与
default()不同,replace()使用includes做严格相等判断,因此''、null、undefined、NaN只有显式列在替换集合中才会被替换(测试 sanitizers-impl.spec.ts 验证了空集合时这些值都原样保留); - 替换值同样经过
_.cloneDeep深拷贝,对象作为替换值时每次请求都会得到独立副本(见 sanitizers-impl.spec.ts)。
.run(req)
- 返回: 一个在清洗链运行完毕时 resolve 的 Promise。
以命令式(imperative)方式运行当前清洗链。这让你可以在路由处理函数内部、非中间件的位置主动触发清洗。
const { check } = require('express-validator');
app.post('/create-post', async (req, res, next) => {
// 清洗前:
// req.body.content = ' hey your forum is amazing! <script>runEvilFunction();</script> ';
await check('content').escape().trim().run(req);
// 清洗后:
// req.body.content = 'hey your forum is amazing! <script>runEvilFunction();</script>';
});
.run() 对应的底层实现是 ContextRunnerImpl.run()。该实现会依次完成:构建 Context → 通过字段选择器(selectFields)收集字段实例 → 按链上顺序逐个执行每个上下文项 → 将新值通过 _.set 写回请求对象。其中有两个关键行为:
- 就地写回: 每执行一个清洗项后,只要新值与请求中的原值不同(且未开启
dryRun),就会用_.set(req<a href="https://link.gitcode.com/i/27303c95cd89ff9febd7363045abf1cd" target="_blank">location], path, newValue)更新请求对象([src/chain/context-runner-impl.ts); - 返回结果:
.run(req)resolve 的结果是一个包含context信息的Result对象(ResultWithContext),可用于进一步读取清洗后的字段数据。
.toArray()
- 返回: 当前清洗链实例。
将值转换为数组:undefined 会得到空数组。
app.post('/', [body('checkboxes').toArray()], (req, res, next) => {
// ['foo', 'bar'] => ['foo', 'bar']
// 'foo' => ['foo']
// undefined => []
console.log(req.body.checkboxes);
});
源码实现(src/chain/sanitizers-impl.ts):
toArray() {
return this.customSanitizer(
value => (value !== undefined && ((Array.isArray(value) && value) || [value])) || [],
);
}
结合测试 sanitizers-impl.spec.ts 可以确认完整的行为矩阵:空字符串 '' → ['']、null → [null]、undefined → []、已有数组保持原样、普通值被单元素包装。也就是说,只有 undefined 会被特殊处理成空数组,其余非数组值(包括 '' 和 null)都会被包装成单元素数组。
.toLowerCase()
- 返回: 当前清洗链实例。
将值转换为小写;非字符串值会原样返回。
app.post('/', [body('username').toLowerCase()], (req, res, next) => {
// 'Foo' => 'foo'
// undefined => undefined
// null => null
console.log(req.body.username);
});
源码实现(src/chain/sanitizers-impl.ts):
toLowerCase() {
return this.customSanitizer(value => (typeof value === 'string' ? value.toLowerCase() : value));
}
注意它并未委托给 validator.js,而是以自定义清洗器的方式实现,因此不会触发前文所述的字符串强转:数字、布尔值、null、undefined、对象等非字符串类型都会被原样透传(测试见 sanitizers-impl.spec.ts)。
.toUpperCase()
- 返回: 当前清洗链实例。
将值转换为大写;非字符串值会原样返回。
app.post('/', [body('username').toUpperCase()], (req, res, next) => {
// 'Foo' => 'FOO'
// undefined => undefined
// null => null
console.log(req.body.username);
});
实现与 toLowerCase() 完全对称(src/chain/sanitizers-impl.ts),同样只在 typeof value === 'string' 时生效(测试见 sanitizers-impl.spec.ts)。
清洗链的底层执行原理
链式调用的本质:Context 栈
每一次 body('field').trim().escape() 式调用,本质上是往一个 ContextBuilder 的 stack 中追加 ContextItem(见 src/context-builder.ts)。SanitizersImpl 持有同一个 builder 引用,所有清洗方法都会调用 builder.addItem(...) 并返回链实例本身,从而实现链式 API。最终 build() 生成一个 Context,其中按序保存了全部验证/清洗步骤。
清洗项如何执行
每个清洗步骤都是一个 Sanitization 上下文项(src/context-items/sanitization.ts),其 run() 方法区分两类行为:
- 自定义清洗器(
custom: true): 直接调用sanitizer(value, meta),返回值即新值,不做任何类型转换; - 标准清洗器(
custom: false): 先经过toString强转,再调用 validator.js 的函数,并把构造时传入的选项一并透传。
字段实例在链中逐项流过:上一个清洗器产生的新值会作为下一个清洗器的输入。运行循环见 src/chain/context-runner-impl.ts:对每个上下文项,会并行处理所有被选中的字段实例,清洗完立即把新值写回 req,这样后续清洗器读取到的就是已更新后的值。
一个综合实战示例
以下示例把标准清洗器、附加方法与命令式运行组合在一起,展示一个完整的"规范化用户注册输入"场景:
const { body, check } = require('express-validator');
// 中间件方式:声明式组合清洗链
app.post(
'/register',
[
body('email').trim().normalizeEmail({ gmail_remove_dots: false }),
body('username').trim().toLowerCase().default('anonymous'),
body('tags').customSanitizer(value => {
// 自定义清洗:把逗号分隔字符串转为数组并逐项 trim
return typeof value === 'string' ? value.split(',').map(s => s.trim()) : value;
}),
body('nickname').replace(['admin', 'root'], 'user'),
],
(req, res) => {
// req.body.email 已被规范化,req.body.username 已小写且有默认值兜底
res.json(req.body);
},
);
// 命令式方式:在业务逻辑中按需清洗
app.post('/posts', async (req, res) => {
await check('content').stripLow(true).trim().escape().run(req);
// 此时 req.body.content 中的 HTML 脚本已被转义
savePost(req.body);
});
使用建议与注意事项
- 清洗链顺序敏感: 清洗器按声明顺序依次作用于同一字段,
trim()之后再escape()与先escape()再trim()的结果可能不同,请按业务目标排列; - 标准清洗器会强转字符串: 对数组、对象字段调用
trim、toInt等标准清洗器前,先想清楚toString的转换规则是否符合预期,需要保留原始类型时优先使用customSanitizer、toLowerCase/toUpperCase这类附加方法; default与replace的对象值会深拷贝: 传入对象作为默认值/替换值时,每个请求拿到的是独立副本,可放心用于多请求场景;- 清洗链与验证链可混用: 一条 ValidationChain 同时拥有验证器与清洗器方法,可以写出
body('email').isEmail().normalizeEmail()这种"先校验、后清洗"的管道式代码; run(req)适合非中间件场景: 当清洗逻辑需要放在路由处理器内部动态触发时,await chain.run(req)是标准做法,且无需把链声明为 Express 中间件数组的一部分。
延伸阅读
- 清洗链 API 声明与类型定义:src/chain/sanitizers.ts
- 清洗链完整实现(含全部附加方法源码):src/chain/sanitizers-impl.ts
- 清洗步骤执行逻辑:src/context-items/sanitization.ts
- 清洗链运行与写回机制:src/chain/context-runner-impl.ts
- 清洗链行为测试:src/chain/sanitizers-impl.spec.ts
- 本版本官方文档原文:api-sanitization-chain.md
- 数组清洗行为 FAQ:faq.md