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（净化链）是一个中间件机制，专门用于处理和净化传入的请求数据。它允许开发者通过链式调用多个净化器（sanitizer）来对请求中的字段进行顺序处理。

净化链的核心特点是：

• 它是一个中间件，应该传递给 Express 路由处理器
• 可以添加任意数量的净化器
• 净化器会按照添加顺序依次执行
• 会直接修改原始请求中的字段值

基本使用方法

让我们看一个简单的示例：

app.get('/', sanitizeBody('username').trim().toLowerCase(), (req, res) => {
  // 如果原始请求中的 username 是 "  JohnDoe  "
  // 经过处理后将会变成 "johndoe"
  console.log(req.body.username);
});

在这个例子中，我们对 username 字段应用了两个净化器：

1. trim() - 去除字符串两端的空白字符
2. toLowerCase() - 将字符串转换为小写

标准净化器

Express-Validator 内置了 validator.js 提供的所有标准净化方法，包括但不限于：

• trim() - 去除字符串两端空白
• toInt() - 将值转换为整数
• toFloat() - 将值转换为浮点数
• normalizeEmail() - 标准化电子邮件地址
• escape() - 转义 HTML 特殊字符

这些标准净化器可以直接在净化链中使用，无需额外配置。

高级功能

除了标准净化器外，Express-Validator 还提供了一些增强功能：

自定义净化器

.customSanitizer() 方法允许你创建自己的净化逻辑：

app.post('/products', 
  sanitizeBody('price').customSanitizer(value => {
    return Math.round(value * 100) / 100; // 保留两位小数
  }),
  productController.create
);

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

手动执行净化链

.run() 方法允许你在路由处理函数中手动执行净化链：

app.put('/articles/:id', async (req, res) => {
  await sanitizeBody('content').escape().trim().run(req);
  // 现在 req.body.content 已经被净化
  await articleController.update(req, res);
});

这种方式特别适合需要在净化前后执行其他逻辑的场景。

数组转换

.toArray() 方法可以将任何值转换为数组：

app.post('/tags', 
  sanitizeBody('tags').toArray(),
  (req, res) => {
    // 单值: "tech" → ["tech"]
    // 数组: ["tech", "science"] → ["tech", "science"]
    // 未定义: undefined → []
    console.log(req.body.tags);
  }
);

最佳实践建议

1. 净化顺序很重要：先执行转义等安全相关的净化，再执行格式调整
2. 明确净化目标：为每个字段单独创建净化链，避免过度净化
3. 结合验证使用：通常先验证数据格式，再进行数据净化
4. 记录原始值：如需保留原始数据，应在净化前先复制一份

常见使用场景

1. 用户输入处理：

   sanitizeBody('username')
     .trim()
     .toLowerCase()
     .escape()
   

2. 数字类型转换：

   sanitizeQuery('page').toInt()
   sanitizeQuery('price').toFloat()
   

3. 电子邮件标准化：

   sanitizeBody('email').normalizeEmail()
   

4. HTML内容安全处理：

   sanitizeBody('content')
     .escape()
     .trim()
   

通过合理使用 Express-Validator 的净化链功能，可以大大提高应用的安全性和数据一致性，减少因数据格式问题导致的错误。

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