Express-Validator 中的 Sanitization Chain API 详解

Express-Validator 中的 Sanitization Chain API 详解

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

什么是 Sanitization Chain

Sanitization Chain（净化链）是 express-validator 提供的一个中间件功能，用于对请求数据进行净化和转换处理。它允许开发者通过链式调用的方式，对输入数据应用多个净化器（sanitizer），确保数据符合预期格式和安全要求。

基本用法

Sanitization Chain 应该被传递给 Express 的路由处理器。下面是一个简单示例：

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

在这个例子中，我们创建了一个净化链，对 trimMe 字段应用了 trim() 净化器，去除了字符串两端的空白字符。

标准净化器

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

• trim()：去除字符串两端的空白字符
• toInt()：将字符串转换为整数
• normalizeEmail()：标准化电子邮件地址
• escape()：转义 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,
);

自定义净化器接收当前字段值和上下文对象（包含请求对象、位置和路径信息），必须同步返回处理后的值。

实用净化方法

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) => {
  // 将用户名转换为大写
});

高级用法

.run(req)

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

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

这种方法特别适合需要在特定条件下才执行净化的场景。

最佳实践

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

通过合理使用 express-validator 的 Sanitization Chain，开发者可以轻松实现输入数据的标准化和安全处理，为后续的业务逻辑提供干净、一致的数据。

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