Express-Validator 6.7.0 中的模式验证(Schema Validation)详解

Express-Validator 6.7.0 中的模式验证(Schema Validation)详解

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

什么是模式验证

模式验证是 Express-Validator 提供的一种结构化验证方式，它允许开发者通过定义 JSON 对象来描述字段的验证规则和清理规则。相比链式调用验证器方法，模式验证提供了更清晰、更集中的验证配置方式，特别适合处理复杂表单或多字段验证场景。

模式验证的基本结构

模式验证对象是一个键值对集合，其中：

• 键：表示要验证的字段路径，可以是简单字段名或嵌套路径（如 addresses.*.postalCode）
• 值：包含该字段的验证配置对象

每个字段配置对象可以包含以下内容：

1. 验证器配置（如 isInt, isLength 等）
2. 清理器配置（如 toInt, rtrim 等）
3. 错误消息定义
4. 字段位置定义
5. 自定义验证/清理逻辑

核心配置选项详解

字段位置定义

使用 in 属性可以指定字段的来源位置：

id: {
  in: ['params', 'query'], // 可接受来自URL参数或查询字符串
  errorMessage: 'ID is wrong',
  isInt: true
}

如果不指定 in 属性，验证器会检查所有可能的请求位置（body、cookies、headers、params 和 query）。

内置验证器使用

Express-Validator 提供了丰富的内置验证器，可以直接在模式中使用：

password: {
  isLength: {
    errorMessage: '密码长度至少7个字符',
    options: { min: 7 }
  }
}

内置清理器使用

清理器可以自动转换输入数据：

firstName: {
  rtrim: {
    options: [' -'], // 移除右侧空格和破折号
  }
}

自定义验证逻辑

当内置验证器不能满足需求时，可以使用自定义验证器：

myCustomField: {
  custom: {
    options: (value, { req, location, path }) => {
      // 自定义验证逻辑
      return value + req.body.foo + location + path;
    }
  }
}

嵌套字段验证

使用点表示法或通配符可以验证嵌套对象或数组：

'addresses.*.postalCode': {
  optional: { options: { nullable: true } },
  isPostalCode: true
}

这里的 * 表示验证数组中的每个元素的 postalCode 字段。

高级特性

否定验证器

通过设置 negated: true 可以反转验证器的逻辑：

firstName: {
  isUppercase: {
    negated: true, // 验证字段不是全大写
  }
}

可选字段处理

使用 optional 可以定义字段在什么情况下是可选的：

{
  optional: { 
    options: { 
      nullable: true // 当字段为null或undefined时跳过验证
    } 
  }
}

类型转换

验证前可以进行自动类型转换：

id: {
  isInt: true,
  toInt: true // 将输入转换为整数
}

最佳实践建议

1. 错误消息统一管理：在大型项目中，考虑将错误消息提取到单独的文件中统一管理

2. 合理使用嵌套验证：对于复杂数据结构，使用嵌套验证可以提高代码可读性

3. 组合使用验证和清理：先清理数据再进行验证，确保验证逻辑处理的是标准化数据

4. 性能考虑：对于高频接口，避免在模式中使用过于复杂的自定义验证逻辑

5. 文档化验证规则：模式验证对象本身可以作为API文档的一部分，保持其清晰和完整

模式验证是 Express-Validator 中非常强大的功能，它通过声明式的方式简化了请求验证的复杂性，使开发者能够更专注于业务逻辑的实现。

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