express-validator Sanitization Chain(清洗链)API 完全指南:字段就地清洗与自定义清洗器实战
express-validator Sanitization Chain(清洗链)API 完全指南:字段就地清洗与自定义清洗器实战
导读
本文以 express-validator 6.15.0 官方文档中 Sanitization Chain API 为核心,系统讲解如何基于 validator.js 构建可链式调用的清洗中间件,将请求字段就地改写为干净、可安全使用的数据。读完本文,你将掌握清洗链的完整方法清单(标准清洗器 + customSanitizer、default、replace、run、toArray、toLowerCase、toUpperCase 等扩展方法)、清洗器按序执行的底层机制,以及如何在真实 Express 路由中把验证与清洗组合成一条链。
什么是 Sanitization Chain
Sanitization Chain(清洗链)是 express-validator 提供的一种中间件,它应当被传入 Express 路由处理器(route handler)作为中间件使用。其核心特性包括:
- 可无限链式添加清洗器:一条链上可以挂任意多个清洗方法,没有数量上限。
- 按声明顺序依次执行:当中间件运行时,会按你书写方法的先后顺序依次应用每个清洗器。
- 就地修改(mutates in place):清洗会直接改写请求对象上对应字段的值,后续中间件与路由处理器中读取到的都是清洗后的结果。
例如:
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') 返回一条清洗链,.trim() 为其添加一个清洗步骤,整条链作为中间件运行后,req.body.trimMe 已被就地改写。
链对象的构成
从源码结构看,check() 系列入口(body、param、query、cookie、header)都会返回一个同时实现 Validators、Sanitizers、ContextHandler 与 ContextRunner 接口的 ValidationChain 对象,见 src/chain/validation-chain.ts。因此一条链既可以调用验证方法(.isEmail()、.isInt() 等),也可以调用清洗方法(.trim()、.normalizeEmail() 等),二者共存于同一链上,这正是"验证与清洗写在一起"的基础(详见 src/middlewares/check.ts)。
清洗链的执行机制:就地修改是如何发生的
清洗器被登记为 ContextItem
每次调用链上的清洗方法,都会在底层的 ContextBuilder 中登记一个 Sanitization 上下文项。以 src/chain/sanitizers-impl.ts 的实现为例,所有标准清洗器最终都通过 addStandardSanitization() 把 new Sanitization(sanitizer, false, options) 压入 builder 的栈:
private addStandardSanitization(sanitizer: StandardSanitizer, ...options: any[]) {
this.builder.addItem(new Sanitization(sanitizer, false, options));
return this.chain;
}
而 Sanitization 类(见 src/context-items/sanitization.ts)会在 run() 时完成真正的清洗动作:
const values = Array.isArray(value) ? value : [value];
const newValues = values.map(value => {
return (this.sanitizer as StandardSanitizer)(this.stringify(value), ...this.options);
});
// We get only the first value of the array if the original value was wrapped.
context.setData(path, values !== value ? newValues[0] : newValues, location);
数组值与字符串转换
标准清洗器来自 validator.js,而 validator.js 只接受 string 作为输入。因此任何需要被标准清洗器处理的值(包括数组和对象)都会先被转换为字符串:
- 如果字段值是数组,会先拆分为多个元素逐一清洗,然后以数组形式写回;
- 如果字段值不是数组,则先包裹成单元素数组,清洗完成后只取第一个结果写回;
- 转换逻辑由 src/utils.ts 中的
toString()完成:Date 对象转为 ISO 字符串,普通对象调用其toString(),null/undefined/NaN转为空字符串,其余值用String()转换。
关于"为什么数组没有被正确验证/清洗"的详细讨论,可参见 清洗与数组的 FAQ 说明。
运行期写回请求
当中间件运行(例如被 Express 调用,或手动调用 .run(req))时,src/chain/context-runner-impl.ts 会遍历 context 栈中的每个上下文项,逐个对每个字段实例执行 contextItem.run(),随后把清洗后的新值通过 _.set() 写回 req[location][path]。这段逻辑确保了"清洗链就地修改请求字段"这一行为。
标准清洗器(Standard sanitizers)
validator.js 列出的所有清洗器在 Sanitization Chain 中都可以直接使用,express-validator 称之为"标准清洗器"。这意味着你可以直接调用 normalizeEmail、trim、toInt 等方法。
从 src/chain/sanitizers.ts 的类型定义看,标准清洗器包括(按签名给出的参数整理):
| 方法 | 参数 | 说明 |
|---|---|---|
blacklist(chars) |
字符集合字符串 | 删除输入中出现在黑名单字符集内的所有字符 |
escape() |
— | 将 <、>、&、'、"、/ 等字符替换为对应的 HTML 实体 |
unescape() |
— | escape() 的逆操作,还原 HTML 实体 |
ltrim(chars?) |
可选字符集 | 去除字符串左侧空白(或指定字符) |
rtrim(chars?) |
可选字符集 | 去除字符串右侧空白(或指定字符) |
trim(chars?) |
可选字符集 | 去除字符串两侧空白(或指定字符) |
normalizeEmail(options?) |
NormalizeEmailOptions | 规范化邮箱地址(小写域名、移除部分别名等) |
stripLow(keep_new_lines?) |
布尔值 | 移除 ASCII 控制字符,默认也会移除换行符,传入 true 保留换行 |
toBoolean(strict?) |
布尔值 | 将 '1'/'true'/'yes'/'0'/'false'/'no' 等字符串转为布尔值;strict 为 true 时仅 '1'/'true' 视为 true |
toDate() |
— | 将字符串转为 Date 对象 |
toFloat() |
— | 将字符串转为浮点数 |
toInt(radix?) |
可选进制 | 将字符串按指定进制转为整数 |
whitelist(chars) |
字符集合字符串 | 仅保留输入中出现在白名单字符集内的字符 |
这些方法的实现均直接委托给 validator.js 的对应函数,例如 blacklist(chars) 实现为 this.addStandardSanitization(validator.blacklist, chars)、toInt(radix) 实现为 this.addStandardSanitization(validator.toInt, radix)(见 src/chain/sanitizers-impl.ts)。单元测试 src/chain/sanitizers-impl.spec.ts 中对每个标准清洗器都验证了"调用后会向 builder 登记对应的 Sanitization 项,并返回当前链实例"。
说明:本文按当前仓库源码列出的方法清单整理参数与行为。标准清洗器的完整选项细节以 validator.js 的清洗器文档为准;express-validator 侧会将其选项原样透传给 validator.js。
附加方法(Additional methods)
除标准清洗器外,Sanitization Chain 还提供了以下专属于 express-validator 的扩展方法。其中 toArray()、toLowerCase()、toUpperCase() 在源码中是以自定义清洗器(custom sanitizer)的形式实现的(new Sanitization(fn, true)),其余为链式 API。
.customSanitizer(sanitizer)
- 参数
sanitizer(value, { req, location, path }):自定义清洗函数,接收被清洗字段的值,以及包含 Express 请求对象、位置(location)与字段路径(path)的元信息。 - 返回:当前清洗链实例。
将自定义清洗器添加到当前清洗链中。它必须同步返回新值(但源码层面会通过 Promise.resolve() 兼容异步返回值,见 src/context-items/sanitization.ts 中的 runCustomSanitizer)。
示例——根据查询参数决定把 :id 清洗成 MongoDB ObjectId 还是数字:
const { param } = require('express-validator');
app.get(
'/object/:id',
param('id').customSanitizer((value, { req }) => {
return req.query.type === 'user' ? ObjectId(value) : Number(value);
}),
objectHandler,
);
.default(default_value)
- 返回:当前清洗链实例。
当字段当前值属于 ['', null, undefined, NaN] 这一集合时,用默认值替换它。源码实现为:
default(default_value: any) {
return this.customSanitizer(value =>
[undefined, null, NaN, ''].includes(value) ? _.cloneDeep(default_value) : value,
);
}
注意两点:
- 替换集合与文档声明完全一致:空字符串、
null、undefined、NaN; - 默认值会经过
_.cloneDeep深拷贝,避免同一默认对象被多个请求共享引用。测试 src/chain/sanitizers-impl.spec.ts 专门验证了"两个请求得到的默认对象不是同一引用"。
app.post('/', body('username').default('foo'), (req, res, next) => {
// 'bar' => 'bar'
// '' => 'foo'
// undefined => 'foo'
// null => 'foo'
// NaN => 'foo'
});
.replace(values_to_replace, new_value)
- 返回:当前清洗链实例。
当字段当前值存在于给定数组中时,用新值替换它。源码实现为:
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,
);
}
- 第一个参数既可以传数组,也可以传单个值(源码会自动包装为数组);
- 替换值同样会经过
_.cloneDeep深拷贝,测试中同样验证了不同请求间替换对象互不共享引用; - 判断采用
Array.includes(),使用严格相等(===)语义。
app.post('/', body('username').replace(['bar', 'BAR'], 'foo'), (req, res, next) => {
// 'bar_' => 'bar_'
// 'bar' => 'foo'
// 'BAR' => 'foo'
console.log(req.body.username);
});
.run(req)
- 返回:一个在清洗链执行完成后 resolve 的 Promise。
以命令式(imperative)方式运行当前清洗链。这适用于不在中间件位置执行清洗、而是要在请求处理器内部主动清洗数据的场景。
const { check } = require('express-validator');
app.post('/create-post', async (req, res, next) => {
// BEFORE:
// req.body.content = ' hey your forum is amazing! <script>runEvilFunction();</script> ';
await check('content').escape().trim().run(req);
// AFTER:
// req.body.content = 'hey your forum is amazing! <script>runEvilFunction();</script>';
});
run() 的底层由 ContextRunnerImpl.run() 实现(见 src/chain/context-runner-impl.ts),它依次执行链上每个上下文项,并就地写回清洗结果;如果字段原本不存在于请求中且清洗后值未变化,则不会多余地写入该键。
.toArray()
- 返回:当前清洗链实例。
把值转换为数组。undefined 会得到空数组。源码实现:
toArray() {
return this.customSanitizer(
value => (value !== undefined && ((Array.isArray(value) && value) || [value])) || [],
);
}
app.post('/', [body('checkboxes').toArray()], (req, res, next) => {
// ['foo', 'bar'] => ['foo', 'bar']
// 'foo' => ['foo']
// undefined => []
console.log(req.body.checkboxes);
});
测试 src/chain/sanitizers-impl.spec.ts 覆盖了空字符串([''])、null([null])、undefined([])、普通字符串与已有数组等边界情况,与你预期的转换行为一致。
.toLowerCase()
- 返回:当前清洗链实例。
将字符串值转为小写。非字符串值会原样返回(不会报错)。源码实现:
toLowerCase() {
return this.customSanitizer(value => (typeof value === 'string' ? value.toLowerCase() : value));
}
app.post('/', [body('username').toLowerCase()], (req, res, next) => {
// 'Foo' => 'foo'
// undefined => undefined
// null => null
console.log(req.body.username);
});
注意:与标准清洗器不同,toLowerCase() 不会把非字符串值先转成字符串再处理——数字、布尔值、对象、null、undefined 都会被原样保留(测试中对 null/undefined 的原样返回有明确断言)。
.toUpperCase()
- 返回:当前清洗链实例。
将字符串值转为大写。非字符串值会原样返回。源码实现:
toUpperCase() {
return this.customSanitizer(value => (typeof value === 'string' ? value.toUpperCase() : value));
}
app.post('/', [body('username').toUpperCase()], (req, res, next) => {
// 'Foo' => 'FOO'
// undefined => undefined
// null => null
console.log(req.body.username);
});
实战:验证与清洗链的典型组合
清洗链最常见的用法是与验证链合二为一:在同一条链上先验证格式、再清洗数据。以下示例来自官方 Sanitization 功能文档:
const express = require('express');
const { body } = require('express-validator');
const app = express();
app.use(express.json());
app.post(
'/comment',
body('email').isEmail().normalizeEmail(),
body('text').not().isEmpty().trim().escape(),
body('notifyOnReply').toBoolean(),
(req, res) => {
// Handle the request somehow
},
);
在这个例子中:
email字段先通过.isEmail()验证格式,再用.normalizeEmail()规范化(例如统一域名大小写、移除别名点号等);text字段先验证非空,再.trim()去除两侧空白,最后.escape()把 HTML 特殊字符转义为实体,防止 XSS;notifyOnReply字段没有做任何验证,但依然可以借助同一条body()链调用.toBoolean()将其转换为 JavaScript 布尔值——验证与清洗是正交的,可以独立使用。
重要提醒:清洗会修改请求对象本身。例如
req.body.text发送时为Hello world :>),经过清洗后变为Hello world :>)。这一行为对后续所有中间件和路由处理器可见,请确认这正是你的预期。
类型定义与测试佐证
- 完整的 Sanitizers 接口签名定义在 src/chain/sanitizers.ts,其中
Return泛型即链自身类型,保证每个方法调用后可以继续链式调用。 - 各附加方法的行为(含边界值)均有对应单元测试:src/chain/sanitizers-impl.spec.ts,覆盖
default/replace的深拷贝语义、toArray/toLowerCase/toUpperCase的非字符串值处理、customSanitizer的同步与异步返回值等。 - 类型声明文件 declarations/validator.d.ts 提供了链式 API 的完整 TypeScript 类型。
小结
Sanitization Chain 是 express-validator 中负责"净化数据"的中间件体系:它复用 validator.js 的全部标准清洗器,并额外提供 customSanitizer、default、replace、run、toArray、toLowerCase、toUpperCase 等扩展方法;执行时按声明顺序就地改写请求字段,同时支持与验证链合写、支持命令式调用。理解其"标准清洗器先转字符串、扩展清洗器保持类型"的实现细节,能帮助你在真实项目中写出既安全又符合预期的数据清洗逻辑。