express-validator Sanitization Chain(清洗链)API 完全指南:字段就地清洗与自定义清洗器实战

原创2026-10-09 20:21:311,923 阅读
文章标签:后端

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! &lt;script&gt;runEvilFunction();&lt;/script&gt;';
});

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 :&gt;)。这一行为对后续所有中间件和路由处理器可见,请确认这正是你的预期。

类型定义与测试佐证

  • 完整的 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 等扩展方法;执行时按声明顺序就地改写请求字段,同时支持与验证链合写、支持命令式调用。理解其"标准清洗器先转字符串、扩展清洗器保持类型"的实现细节,能帮助你在真实项目中写出既安全又符合预期的数据清洗逻辑。

登录后查看全文
express-validator