express-validator 清洗链(Sanitization Chain)完整指南:中间件用法、标准清洗器与自定义清洗器

原创2026-10-09 10:58:331,765 阅读
文章标签:后端

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 字符替换为实体(< → &lt;)
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! &lt;script&gt;runEvilFunction();&lt;/script&gt;';
});

注意执行顺序:先 escape() 再 trim(),因此结果是 HTML 实体转义在前、去除首尾空格在后。这个例子也展示了清洗链在 XSS 防护中的典型价值——把用户提交的 <script> 内容转义为无害的 &lt;script&gt; 再入库。

从源码看,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"与"执行引擎"分开看。一次完整的清洗过程包含三个阶段:

  1. 构建阶段:你调用 body('field').trim().escape() 时,每个方法只是向 ContextBuilder 的 stack 中登记一个 Sanitization 项(字段、位置、动作列表都被记录下来),不会立即执行任何清洗。
  2. 运行阶段:作为中间件被 Express 调用时(或你手动调用 run(req) 时),ContextRunnerImpl 先从请求中按 context.fields 与 context.locations 选出字段实例,然后按登记顺序逐个执行 Sanitization.run()(参见 src/context-items/sanitization.ts)。
  3. 写回阶段:清洗结果先写入 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 });
});

进一步阅读

登录后查看全文
express-validator