express-validator 清洗链(Sanitization Chain)完整指南:中间件用法、标准清洗器与自定义清洗器
express-validator 清洗链(Sanitization Chain)完整指南:中间件用法、标准清洗器与自定义清洗器
本篇指南围绕 express-validator v6 的 Sanitization Chain(清洗链)展开,讲解如何将清洗链作为 Express 中间件使用、如何串联多个清洗器按顺序就地修改请求字段,并深入剖析标准清洗器、customSanitizer、run(req)、toArray() 等附加方法的签名与底层执行原理。读完本文,你将掌握在表单提交、评论发布、对象 ID 解析等场景中安全、可复用地清洗用户输入,并能结合源码理解清洗链在 express-validator 内部的工作机制。
什么是清洗链:一段特殊的 Express 中间件
清洗链(Sanitization Chain)本质上就是一个 Express 中间件,它应当被传给 Express 路由处理器。与校验链(Validation Chain)负责"检查字段是否符合规则"不同,清洗链负责"改写字段的值",使其满足业务侧预期的形态——比如去掉首尾空格、转义 HTML 特殊字符、把字符串转成整数、把值包装成数组等。
你可以在一根链上添加任意多个清洗器。当中间件运行时,它会就地(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()、check()、param()等校验链构建器返回,trim()是链上的一个清洗器; - 清洗在进入路由处理器之前完成,因此路由处理器内读取到的
req.body.trimMe已经是清洗后的值; - 清洗是原地修改,不是返回一个新对象,后续逻辑读取同一字段即可拿到干净数据。
链式调用与执行顺序:源码中的实现方式
在 express-validator 中,清洗链上的每一个方法调用都不是立即执行清洗,而是先把"清洗动作"登记到上下文构建器中。从源码看,SanitizersImpl 的每个方法都会把动作包装成 Sanitization 项追加进 ContextBuilder 的 stack(参见 src/chain/sanitizers-impl.ts):
private addStandardSanitization(sanitizer: StandardSanitizer, ...options: any[]) {
this.builder.addItem(new Sanitization(sanitizer, false, options));
return this.chain;
}
关键点在于:
- 登记顺序即执行顺序。
builder.addItem()按调用顺序把Sanitization项压入stack,最终在中间件真正运行时,ContextRunnerImpl会遍历context.stack依次执行每一项(参见 src/chain/context-runner-impl.ts)。所以body('x').trim().escape()与body('x').escape().trim()的结果可能不同,必须按业务语义决定先后。 - 每个动作返回当前链实例。
addStandardSanitization最后return this.chain,这正是链式调用的语法基础——每次调用都返回同一根链,因而可以无限.method().method()...串联下去。
单个清洗动作的执行逻辑定义在 src/context-items/sanitization.ts:标准清洗器会先把值字符串化(toString)再交给 validator.js 的函数;如果字段值是数组,则对每个元素分别清洗;清洗结果通过 context.setData(path, newValue, location) 写回上下文,再在 ContextRunnerImpl.run() 中通过 _.set(req<a href="https://link.gitcode.com/i/23cc1c4d03cb2c3b344b4e26e1139a4d" target="_blank">location], path, newValue) 写回真实的请求对象。测试用例 [src/context-items/sanitization.spec.ts 验证了"清洗后的值会持久化回上下文"这一行为。
标准清洗器:validator.js 全量可用
validator.js 列出的所有清洗器在清洗链中都可用,express-validator 称之为"标准清洗器(standard sanitizers)"。这意味着你可以直接使用 normalizeEmail、trim、toInt 等方法,无需任何包装。
在 v6 源码的 Sanitizers 接口(参见 src/chain/sanitizers.ts)中,标准清洗器的方法签名如下:
| 方法 | 参数 | 说明 |
|---|---|---|
blacklist(chars) |
chars: string |
删除值中出现在字符列表里的所有字符 |
escape() |
无 | 将 <、>、&、'、" 等 HTML 字符替换为实体(< → <) |
unescape() |
无 | escape() 的逆操作,把 HTML 实体还原为字符 |
ltrim(chars?) |
chars?: string |
去除左侧空白,可指定要裁剪的字符集 |
rtrim(chars?) |
chars?: string |
去除右侧空白,可指定要裁剪的字符集 |
trim(chars?) |
chars?: string |
去除两侧空白,可指定要裁剪的字符集 |
normalizeEmail(options?) |
options?: NormalizeEmailOptions |
规范化邮箱,如统一小写、去点等 |
stripLow(keep_new_lines?) |
keep_new_lines?: boolean |
移除 ASCII 控制字符,true 时保留换行 |
toBoolean(strict?) |
strict?: boolean |
转布尔值;strict 模式下仅 'true' 为真 |
toDate() |
无 | 转 Date 对象 |
toFloat() |
无 | 转浮点数 |
toInt(radix?) |
radix?: number |
转整数,可指定进制 |
toLowerCase() |
无 | 转小写(非字符串值原样保留) |
toUpperCase() |
无 | 转大写(非字符串值原样保留) |
whitelist(chars) |
chars: string |
仅保留字符列表中出现的字符 |
标准清洗器的完整清单与各自选项以 validator.js 官方文档为准。
值得注意的源码细节:toLowerCase 与 toUpperCase 在 express-validator 中并不是直接委托 validator.js,而是用 customSanitizer 实现的——只有值本身是字符串时才做大小写转换,null、undefined、数字等原样透传(参见 src/chain/sanitizers-impl.ts 及测试 src/chain/sanitizers-impl.spec.ts 中 #toLowerCase() / #toUpperCase() 用例)。这意味着对非字符串字段调用这两个方法不会报错,也不会产生意外转换。
附加方法:不止于标准清洗器
在标准清洗器之外,清洗链还提供以下附加方法:
.customSanitizer(sanitizer)
sanitizer(value, { req, location, path }):自定义清洗函数。它接收被清洗字段的值,以及当前 Express 请求req、字段所在位置location和字段路径path。- 返回:当前清洗链实例。
customSanitizer 向当前清洗链添加一个自定义清洗器,必须同步返回新值(注意:虽然底层实现会 Promise.resolve 返回值以兼容 async 清洗器,但文档语义要求同步返回)。
const { param } = require('express-validator');
app.get('/object/:id', param('id').customSanitizer((value, { req }) => {
return req.query.type === 'user' ? ObjectId(value) : Number(value);
}), objectHandler)
上面的例子演示了最常见的用法:根据请求上下文(这里是 req.query.type)决定如何解析 :id 参数——是转成 MongoDB 的 ObjectId 还是普通数字。{ req, location, path } 这个元信息对象与校验链 custom() 中拿到的一致,类型定义见 src/base.ts 中的 Meta。此外,location 取值为 body、cookies、headers、params、query 五种之一,path 是字段在请求对象中的完整路径(如 foo.bar)。
从测试 src/chain/sanitizers-impl.spec.ts 的 #customSanitizer() 用例可以看出,自定义清洗器会被包装为 new Sanitization(sanitizer, true),其中第二个参数 true 标记这是自定义清洗器,从而走"直接调用并写回上下文"的执行路径。
.run(req)
- 返回:一个 Promise,在清洗链运行完成后 resolve。
run(req) 允许你以命令式(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>';
});
注意执行顺序:先 escape() 再 trim(),因此结果是 HTML 实体转义在前、去除首尾空格在后。这个例子也展示了清洗链在 XSS 防护中的典型价值——把用户提交的 <script> 内容转义为无害的 <script> 再入库。
从源码看,run(req) 由 ContextRunnerImpl.run() 实现(参见 src/chain/context-runner-impl.ts):它先基于已登记的字段与位置构建 Context,再按字段实例遍历执行栈中的每个清洗项,并在每次值变化后通过 _.set(req[location], path, newValue) 把新值写回请求对象。run() 也可以传 { dryRun: true } 来"只执行不写回",这在需要预览清洗结果时可用。
.toArray()
- 返回:当前清洗链实例。
toArray() 把字段值转换为数组。规则是:undefined 得到空数组 [],单个值被包装成 [value],已是数组的值保持不变。
app.post('/', [body('checkboxes').toArray()], (req, res, next) => {
// ['foo', 'bar'] => ['foo', 'bar']
// 'foo' => ['foo']
// undefined => []
console.log(req.body.checkboxes);
});
这在处理"可能提交单个值也可能提交多个值"的表单字段(如多选框)时非常实用——统一成数组后,后续 isArray() 校验或 Array.map 处理就无需再判断类型。测试 src/chain/sanitizers-impl.spec.ts 的 #toArray() 用例覆盖了 []、'foo'、['foo']、''、null、undefined 六种输入,其中 '' 会被包装成 ['']、null 会被包装成 [null],仅有 undefined 得到空数组。
其他附加方法:default() 与 replace()
除了文档明确列出的三个附加方法,v6 源码的 Sanitizers 接口还提供了两个通过 customSanitizer 实现的方法(参见 src/chain/sanitizers.ts):
.default(default_value):当字段值为''、null、undefined或NaN之一时,用default_value替换它。对象类型的默认值会被_.cloneDeep深拷贝,避免多个请求共享同一引用(对应测试见 src/chain/sanitizers-impl.spec.ts 的#default()用例)。.replace(values_to_replace, new_value):当字段值命中values_to_replace(可传单个值或数组)中的任意一个时,用new_value替换。替换值同样会被深拷贝。
这两个方法非常适合"给缺省字段补默认值"的场景,例如 body('page').default(1).toInt() 让未传的分页参数默认落在第 1 页。
底层执行原理:清洗器如何被"翻译"为真实请求修改
理解清洗链,关键是把"链式 API"与"执行引擎"分开看。一次完整的清洗过程包含三个阶段:
- 构建阶段:你调用
body('field').trim().escape()时,每个方法只是向ContextBuilder的stack中登记一个Sanitization项(字段、位置、动作列表都被记录下来),不会立即执行任何清洗。 - 运行阶段:作为中间件被 Express 调用时(或你手动调用
run(req)时),ContextRunnerImpl先从请求中按context.fields与context.locations选出字段实例,然后按登记顺序逐个执行Sanitization.run()(参见 src/context-items/sanitization.ts)。 - 写回阶段:清洗结果先写入
Context的dataMap,再被同步写回req对应位置。对body位置就是req.body,对params位置就是req.params,依此类推。
一个值得记住的实现细节:标准清洗器在执行时会先把值字符串化。这意味着如果字段值是数字 123,trim() 这类基于字符串的清洗器会先得到 "123",清洗结果再写回——如果你随后还调用了 toInt(),则会重新变回数字。因此,链内各清洗器的顺序直接决定最终值的类型与内容。
实战组合:清洗 + 校验 + 错误处理
清洗链与校验链可以出现在同一根链上(express-validator 的链同时具备清洗与校验能力,见 src/chain/validation-chain.ts 中 ValidationChain 同时继承 Sanitizers 与 Validators 的接口定义)。一个典型的做法是"先清洗、后校验",保证校验函数看到的输入已经是规整形态:
const { body, validationResult } = require('express-validator');
app.post(
'/signup',
[
body('email').normalizeEmail().isEmail(),
body('password').trim().isLength({ min: 8 }),
body('nickname').blacklist('<>"\'()&').trim().isLength({ min: 2, max: 20 }),
],
(req, res) => {
const errors = validationResult(req);
if (!errors.isEmpty()) {
return res.status(400).json({ errors: errors.array() });
}
// 到这里 req.body.email 已是规范化邮箱,password 已去首尾空格
res.json({ ok: true });
},
);
如果希望在控制器内部"先用再验",可以像下面这样结合 run(req) 与 validationResult 命令式执行:
const { check, validationResult } = require('express-validator');
app.post('/create-post', async (req, res) => {
await check('content').escape().trim().isLength({ min: 1, max: 500 }).run(req);
const errors = validationResult(req);
if (!errors.isEmpty()) {
return res.status(400).json({ errors: errors.array() });
}
res.json({ content: req.body.content });
});
进一步阅读
- 清洗链的接口定义与全部方法签名:src/chain/sanitizers.ts;
- 清洗器的底层实现与
customSanitizer逻辑:src/chain/sanitizers-impl.ts、src/context-items/sanitization.ts; - 相关单元测试:src/chain/sanitizers-impl.spec.ts、src/context-items/sanitization.spec.ts;
- 校验链与命令式运行的更多说明:docs/api/check.md、docs/guides/manually-running.md;
- 清洗概念总览与 schema 清洗:website/versioned_docs/version-6.6.0/feature-sanitization.md、website/versioned_docs/version-6.6.0/feature-schema-validation.md。