express-validator 项目中的 Sanitization Chain API 详解

express-validator 项目中的 Sanitization Chain API 详解

express-validator 项目地址: https://gitcode.com/gh_mirrors/exp/express-validator

什么是 Sanitization Chain

在 express-validator 项目中，Sanitization Chain（净化链）是一个中间件，它应该被传递给 Express 的路由处理器。净化链允许你对请求数据进行一系列的净化处理，确保数据符合预期的格式和安全要求。

基本用法

净化链可以包含任意数量的净化器（sanitizer）。当中间件运行时，它会按照指定的顺序依次应用每个净化器来修改字段值：

const { body } = require('express-validator');
app.get('/', body('trimMe').trim(), (req, res, next) => {
  // 如果 req.body.trimMe 原本是 "  something "，
  // 净化后的值将是 "something"
  console.log(req.body.trimMe);
});

标准净化器

express-validator 提供了 validator.js 中列出的所有净化器，这些被称为"标准净化器"。包括但不限于：

• normalizeEmail：标准化电子邮件地址
• trim：去除字符串两端的空白字符
• toInt：将字符串转换为整数
• escape：转义 HTML 特殊字符
• unescape：反转义 HTML 特殊字符

这些净化器可以直接在净化链中使用，为开发者提供了丰富的内置数据处理能力。

自定义净化器

除了标准净化器外，express-validator 还提供了强大的自定义净化功能：

.customSanitizer(sanitizer)

这个方法允许你添加自定义的净化逻辑：

const { param } = require('express-validator');
app.get(
  '/object/:id',
  param('id').customSanitizer((value, { req }) => {
    return req.query.type === 'user' ? ObjectId(value) : Number(value);
  }),
  objectHandler,
);

参数说明：

• sanitizer 函数接收当前字段值和上下文对象
• 上下文对象包含 req（请求对象）、location（字段位置）和 path（字段路径）
• 必须同步返回新值

实用净化方法

express-validator 提供了一系列实用的净化方法：

.default(default_value)

当字段值为 ['', null, undefined, NaN] 其中之一时，将其替换为默认值：

app.post('/', body('username').default('foo'), (req, res, next) => {
  // 空字符串、null、undefined 或 NaN 都会被替换为 'foo'
});

.replace(values_to_replace, new_value)

将特定值替换为新值：

app.post('/', body('username').replace(['bar', 'BAR'], 'foo'), (req, res, next) => {
  // 'bar' 或 'BAR' 会被替换为 'foo'
});

.toArray()

将值转换为数组：

app.post('/', [body('checkboxes').toArray()], (req, res, next) => {
  // 字符串会被转换为单元素数组
  // undefined 会转换为空数组
});

.toLowerCase() 和 .toUpperCase()

转换字符串大小写：

app.post('/', [body('username').toUpperCase()], (req, res, next) => {
  // 'Foo' 会被转换为 'FOO'
  // 非字符串值保持不变
});

高级用法

.run(req)

以命令式方式运行净化链：

app.post('/create-post', async (req, res, next) => {
  await check('content').escape().trim().run(req);
  // 净化后的内容会直接修改 req.body
});

这个方法特别适合在非中间件环境中使用净化功能。

最佳实践

1. 顺序很重要：净化器会按照添加顺序执行，确保先进行必要的格式转换再进行其他处理
2. 组合使用：可以结合多个净化器实现复杂的数据处理逻辑
3. 性能考虑：避免在净化链中进行耗时的同步操作
4. 错误处理：虽然净化通常不会抛出错误，但仍需注意边界情况

通过合理使用 express-validator 的 Sanitization Chain API，开发者可以轻松实现强大的请求数据净化功能，提高应用的安全性和稳定性。

express-validator 项目地址: https://gitcode.com/gh_mirrors/exp/express-validator