Express-Validator 6.10.0 中的 Schema 验证详解

Express-Validator 6.10.0 中的 Schema 验证详解

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

什么是 Schema 验证

Schema 验证是 express-validator 提供的一种基于对象的验证和清理（sanitization）定义方式。与传统的链式调用验证器不同，Schema 验证允许开发者以更结构化、更清晰的方式组织验证规则，特别适合处理复杂的数据验证场景。

Schema 验证的基本结构

Schema 验证的核心是一个 JavaScript 对象，其中：

• 键（key）表示要验证的字段路径
• 值（value）是一个包含验证规则的对象

每个字段的验证对象可以包含以下内容：

1. 验证器（validators）
2. 清理器（sanitizers）
3. 错误消息（error messages）
4. 字段位置（location）
5. 其他配置选项

主要功能详解

1. 字段位置指定

通过 in 属性可以指定字段的来源位置：

id: {
  in: ['params', 'query'], // 可以检查 params 和 query 中的 id 字段
  errorMessage: 'ID is wrong',
  isInt: true,
  toInt: true
}

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

2. 内置验证器和清理器

express-validator 提供了丰富的内置验证器和清理器：

password: {
  isLength: {
    errorMessage: 'Password should be at least 7 chars long',
    options: { min: 7 }
  }
},
firstName: {
  isUppercase: {
    negated: true // 否定验证器，表示字段不应全大写
  },
  rtrim: {
    options: [' -'] // 清理器，移除右侧空格和破折号
  }
}

3. 自定义验证器和清理器

对于特殊需求，可以定义自定义验证器和清理器：

myCustomField: {
  custom: {
    options: (value, { req, location, path }) => {
      // 自定义验证逻辑
      return value + req.body.foo + location + path;
    }
  },
  customSanitizer: {
    options: (value, { req, location, path }) => {
      // 自定义清理逻辑
      let sanitizedValue;
      if (req.body.foo && location && path) {
        sanitizedValue = parseInt(value);
      } else {
        sanitizedValue = 0;
      }
      return sanitizedValue;
    }
  }
}

4. 高级功能

4.1 嵌套对象验证

支持使用通配符验证嵌套对象：

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

这可以验证 addresses 数组中每个对象的 postalCode 字段。

4.2 提前终止验证（Bail）

使用 bail 可以在第一个验证失败后停止后续验证：

email: {
  isEmail: {
    bail: true // 如果邮箱格式验证失败，不会继续执行其他验证
  }
}

4.3 可选字段

通过 optional 可以定义字段为可选：

'addresses.*.postalCode': {
  optional: { options: { nullable: true } }, // 允许字段为 undefined 或 null
  isPostalCode: true
}

实际应用示例

以下是一个完整的用户密码修改接口的 Schema 验证示例：

const { checkSchema } = require('express-validator');

app.put('/user/:id/password', 
  checkSchema({
    id: {
      in: ['params'],
      isInt: true,
      toInt: true,
      errorMessage: '用户ID必须为整数'
    },
    oldPassword: {
      isLength: {
        options: { min: 6 },
        errorMessage: '旧密码长度至少6位'
      }
    },
    newPassword: {
      isLength: {
        options: { min: 8 },
        errorMessage: '新密码长度至少8位'
      },
      matches: {
        options: /[A-Z]/,
        errorMessage: '新密码必须包含至少一个大写字母'
      }
    },
    confirmPassword: {
      custom: {
        options: (value, { req }) => value === req.body.newPassword,
        errorMessage: '两次输入的密码不一致'
      }
    }
  }),
  (req, res) => {
    // 处理请求
  }
);

最佳实践

1. 组织验证规则：将复杂的验证逻辑分解为多个小的 Schema 对象，便于维护
2. 重用验证规则：对于常用的验证模式，可以创建可重用的 Schema 片段
3. 清晰的错误消息：为每个验证规则提供明确的错误消息，方便前端展示
4. 合理使用清理器：在验证前对数据进行清理，确保验证的准确性
5. 性能考虑：对于大型 Schema，使用 bail 选项优化验证流程

总结

express-validator 的 Schema 验证提供了一种结构化、可维护的方式来定义复杂的验证逻辑。通过组合内置验证器、清理器和自定义函数，开发者可以轻松构建强大的数据验证层，确保应用程序接收到的数据符合预期格式和业务规则。Schema 验证特别适合中大型项目，能够显著提高代码的可读性和可维护性。

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