express-validator 清洗链(Sanitization Chain)API 完全指南:从标准清洗器到自定义清洗的实战与源码解析

原创2026-10-09 22:25:151,904 阅读
文章标签:后端

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,
  );
}

两点值得注意的细节:

  1. 空字符串 '' 也会被替换为默认值;
  2. 默认值会经过 _.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! &lt;script&gt;runEvilFunction();&lt;/script&gt;';
});

.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);
});

使用建议与注意事项

  1. 清洗链顺序敏感: 清洗器按声明顺序依次作用于同一字段,trim() 之后再 escape() 与先 escape() 再 trim() 的结果可能不同,请按业务目标排列;
  2. 标准清洗器会强转字符串: 对数组、对象字段调用 trim、toInt 等标准清洗器前,先想清楚 toString 的转换规则是否符合预期,需要保留原始类型时优先使用 customSanitizer、toLowerCase/toUpperCase 这类附加方法;
  3. default 与 replace 的对象值会深拷贝: 传入对象作为默认值/替换值时,每个请求拿到的是独立副本,可放心用于多请求场景;
  4. 清洗链与验证链可混用: 一条 ValidationChain 同时拥有验证器与清洗器方法,可以写出 body('email').isEmail().normalizeEmail() 这种"先校验、后清洗"的管道式代码;
  5. run(req) 适合非中间件场景: 当清洗逻辑需要放在路由处理器内部动态触发时,await chain.run(req) 是标准做法,且无需把链声明为 Express 中间件数组的一部分。

延伸阅读

登录后查看全文
express-validator