后端【免费下载链接】express-validatorAn express.js middleware for validator.js.项目地址https://gitcode.com/gh_mirrors/ex/express-validator点击查看免费下载express-validator 通过其底层依赖 validator.js 内置了数十个即插即用的验证器与净化器但真实业务中总会有内置规则覆盖不到的校验需求——例如邮箱是否已被注册密码确认是否一致字符串 ID 是否合法 MongoDB ObjectId等。本文以 v6.4.0 官方文档《Custom validators/sanitizers》为核心讲解如何用链式方法.custom()与.customSanitizer()编写自定义校验逻辑并结合仓库源码与测试用例剖析其异步 Promise 语义、错误消息机制、Meta 上下文参数以及底层执行原理让你能够写出可复用、可测试、生产可用的自定义校验中间件。为什么需要自定义验证器与净化器express-validator 的验证链与净化链本质上是对 validator.js 的封装。打开 src/chain/validators.ts 可以看到Validators接口暴露了isEmail、isInt、isURL、isMobilePhone等几十个标准验证器src/chain/sanitizers.ts 则暴露了trim、escape、toInt、normalizeEmail等标准净化器。它们覆盖面虽广却都是通用规则——判断一个字符串是否形如邮箱、是否为合法整数等。但业务校验往往依赖外部状态与请求上下文邮箱是否已存在于数据库、两次输入的密码是否一致、某个商品是否还有库存。这类校验无法用纯函数式的内置规则表达因此 express-validator 为验证链和净化链预留了两条逃生通道方法所属链作用签名.custom(validator)验证链Validation Chain自定义验证器判定字段是否有效custom((value, meta) any).customSanitizer(sanitizer)验证链 / 净化链Sanitization Chain自定义净化器转换字段值customSanitizer((value, meta) any)二者都接受一个函数该函数接收两个参数字段的当前值value以及描述字段上下文的meta对象详见下文Meta 参数一节。自定义验证器.custom()基本用法与有效性判定规则在 docs/api/validation-chain.md 中.custom()的完整签名是custom(validator: (value, { req, location, path, pathValues }) any): ValidationChain字段值被视为有效当且仅当满足以下任一条件自定义验证器返回真值truthy自定义验证器返回的Promise 成功 resolve。字段值被视为无效当出现以下任一情况自定义验证器返回假值falsy返回的Promise 被 reject函数内部throw了任何值。这条规则在 v6.4.0 文档中也有明确说明Custom validators may return Promises to indicate an async validation (which will be awaited upon), orthrowany value/reject a promise to use a custom error message。特别要注意文档中的 Note如果自定义验证器返回的是 Promise它必须通过 reject 来表示字段无效——也就是说返回一个 resolve 的 Promise 始终意味着校验通过。从源码看src/context-items/custom-validation.ts 完整实现了这套语义async run(context: Context, value: any, meta: Meta) { try { const result this.validator(value, meta); const actualResult await result; const isPromise result?.then; const failed this.negated ? actualResult : !actualResult; // A promise that was resolved only adds an error if negated. // Otherwise it always succeeds if ((!isPromise failed) || (isPromise this.negated)) { context.addError({ type: field, message: this.message, value, meta }); } } catch (err) { if (this.negated) return; context.addError({ type: field, message: this.message || (err instanceof Error ? err.message : err), value, meta, }); } }这段代码值得仔细解读验证器返回值总是被await因此同步与异步验证器在底层走同一条执行路径通过isPromise result?.then区分同步与异步返回值同步假值直接判失败而 resolve 的 Promise 永不判失败除非被.not()取反throw与 Promise reject 都会落入catch分支被记录为字段错误抛出的值如果是Error实例则取其message否则原样作为错误消息这就是throw 任意值自定义错误消息的原理。示例一检查邮箱是否已被占用v6.4.0 文档给出的经典场景是注册时校验邮箱唯一性。使用 Promise 风格const { body } require(express-validator); app.post(/user, body(email).custom(value { return User.findUserByEmail(value).then(user { if (user) { return Promise.reject(E-mail already in use); } }); }), (req, res) { // Handle the request });这里Promise.reject(E-mail already in use)既标记了字段无效又直接提供了错误消息——E-mail already in use会原样出现在校验结果中这正是上一节源码里message: this.message || (err instanceof Error ? err.message : err)的体现E-mail already in use不是Error实例因此被直接用作消息。更符合现代风格的 async/await 写法后续版本的官方文档也采用了这种形式app.post(/signup, body(email).custom(async value { const existingUser await Users.findUserByEmail(value); if (existingUser) { throw new Error(E-mail already in use); } }), (req, res) { /* Handle request */ }, );注意文档特别提醒此类校验会触达数据层——如果查询数据库本身出错网络抖动、连接断开验证器会 throw/reject从而把数据访问故障误判为字段校验失败。因此访问数据层进行校验的副作用与可靠性需要仔细权衡必要时应在自定义验证器内区分业务违规与基础设施异常。示例二校验密码确认字段同步自定义验证器的典型用法是结合 Meta 中的req读取请求体中的其他字段const { body } require(express-validator); app.post(/user, body(passwordConfirmation).custom((value, { req }) { if (value ! req.body.password) { throw new Error(Password confirmation does not match password); } // Indicates the success of this synchronous custom validator return true; }), (req, res) { // Handle the request });要点拆解第二个参数解构出{ req }即可访问req.body.password做跨字段比对校验失败时throw new Error(...)其.message会被提取为错误消息校验成功时显式return true。虽然自定义验证器不返回或返回undefined时也会被当作假值判失败但显式返回真值能让语义更清晰也避免无意的失败。你还可以在同一个链上叠加内置验证器例如先对password做isLength({ min: 5 })长度检查再对passwordConfirmation做一致性比对使两条规则职责分明。跨字段校验与通配符场景当字段是用通配符或 globstar 选中的详见 docs/guides/field-selection.md自定义验证器还可以通过 Meta 的pathValues拿到通配符匹配到的索引/键从而读取同层级的其他属性。例如校验购物车中每个商品的数量是否超过库存app.post( /purchase, [ body(products.*.quantity).custom((quantity, { req, pathValues }) { const index Number(pathValues[0]); const { id } req.body.products[index]; if (getProductStock(id) quantity) { throw new Error(Theres not enough of product ${id} in stock); } }), ], (req, res) { /* Handle request */ }, );自定义净化器.customSanitizer()基本用法自定义净化器通过.customSanitizer()注册且同时存在于验证链与净化链Sanitization Chain上验证链版本body(field).customSanitizer(...)与.custom()在同一链上混用净化链版本见 v6.4.0 文档 api-sanitization-chain.md签名与语义一致。其规则非常朴素净化器函数返回什么值字段就变成什么值。v6.4.0 文档明确写道 sanitizer 函数mustbe synchronous at the moment当时必须同步。不过从后续源码与测试来看src/context-items/sanitization.ts 中自定义净化器同样会被Promise.resolve包裹后await——从实现层面看异步净化器也能工作src/context-items/sanitization.spec.ts 中有对 async sanitizer 的测试但文档建议按同步函数编写这是最稳妥的生产实践。const { param } require(express-validator); app.post(/object/:id, param(id).customSanitizer(value { return ObjectId(value); }), (req, res) { // Handle the request });执行后req.params.id已从字符串变成 MongoDB 的ObjectId实例后续路由处理器直接消费该对象即可。净化器返回 undefined 的陷阱在 docs/guides/customizing.md 中有明确警告如果自定义净化器没有返回值字段会变成undefined。例如param(id).customSanitizer(value { ObjectId(value); // 忘了 return });这是 JavaScript 箭头函数的经典陷阱——函数体花括号内没有return函数返回undefined字段值就被覆盖成了undefined后续校验或业务逻辑将拿到空值。因此自定义净化器函数体内务必保证每个分支都有显式返回。与内置净化器配合自定义净化器可以与其他链方法任意组合例如先trim()再自定义转换。在 src/chain/sanitizers-impl.ts 中customSanitizer的实现是把净化器包装成Sanitization上下文项custom: true追加到 context 构建器而内置净化器如trim、toInt走addStandardSanitizationcustom: false。二者的关键差异在于标准净化器会把值先stringify再逐个作用于数组元素见 src/context-items/sanitization.ts而自定义净化器直接接收原始值数组原样传入并直接写回字段。const { body } require(express-validator); app.post(/user, body(age) .customSanitizer(value String(value).trim()) // 自定义先规整输入 .toInt() // 内置转整数 .custom(value value 18) // 自定义验证 , (req, res) { /* ... */ });Meta 参数自定义函数能拿到什么上下文.custom()与.customSanitizer()的第二个参数是Meta对象其类型定义在 src/base.tstype Meta { req: Request; // 当前的 Express 请求对象 location: body | cookies | headers | params | query; path: string; // 字段在请求对象中的完整路径如 foo.bar pathValues: readonly (string | string[])[]; // 通配符/globstar 匹配到的值 };属性说明典型用途req当前 Express 请求对象跨字段比对如密码确认、读取请求头/查询参数location字段来源body/cookies/headers/params/query根据来源执行不同规则path字段的完整路径构建精确的错误提示、动态查找关联数据pathValues通配符/globstar 捕获的值通配符选中的字段间联动校验例如下面的自定义净化器会根据查询参数决定转换策略取自 v6.4.0 净化链文档示例app.post(/object/:id, param(id).customSanitizer((value, { req }) { // In this app, users have MongoDB style object IDs, everything else, numbers return req.query.type user ? ObjectId(value) : Number(value); }), (req, res) { /* Handle request */ });自定义验证器的错误消息机制默认情况下字段校验失败的错误消息是固定的Invalid value。自定义验证器有两条途径定制消息详见 v6.4.0 文档 feature-error-messages.mdthrow / reject 的值即消息验证器throw new Error(Password confirmation does not match password)或Promise.reject(E-mail already in use)时抛出的值Error取其message会被用作该字段的错误消息。这是文档重点推荐的custom validator level消息方式。.withMessage()显式指定在链上调用.withMessage(msg)会覆盖验证器抛出的值具有更高优先级。这也与源码对应——CustomValidation的message属性由.withMessage()写入优先于抛出的错误值message: this.message || (err instanceof Error ? err.message : err),在 src/context-items/custom-validation.spec.ts 的测试中withMessage设置的nope在验证器 throwboom与 Promise rejecta bomb两种情况下都优先胜出直接印证了这一优先级规则。底层执行原理从链方法到校验结果自定义验证器/净化器之所以能与链式 API 无缝衔接是因为它们最终都被抽象成了上下文项Context Item与内置规则统一执行。调用链如下你在链上调用.custom(...)或.customSanitizer(...)实现类把函数包装成CustomValidationsrc/chain/validators-impl.ts或Sanitizationsrc/chain/sanitizers-impl.ts实例追加到ContextBuilder中间件运行时见 src/middlewares/check.ts收集请求中的字段值逐个执行上下文项的run(context, value, meta)CustomValidation.run依据真值/假值、resolve/reject、throw判定并调用context.addError记录字段错误src/context-items/custom-validation.tsSanitization.run把返回值通过context.setData(path, newValue, location)写回字段src/context-items/sanitization.ts净化后的值会继续传给同链后续的验证器。因此净化器总是先于同链的验证器生效body(age).customSanitizer(...).toInt().custom(...)中字段值依次经历自定义转换 → 内置toInt→ 自定义校验每个上下文项按链式顺序依次消费并更新字段值。完整实战注册接口的组合校验把本文的知识点整合成一个真实可运行的注册接口示例结合 v6.4.0 文档的校验/净化与错误处理模式const { body, validationResult } require(express-validator); app.post( /register, [ // 净化统一邮箱格式忽略大小写 body(email).normalizeEmail().trim(), // 验证邮箱格式 唯一性异步自定义验证器 body(email) .isEmail().withMessage(Invalid e-mail address) .custom(value User.findUserByEmail(value).then(user { if (user) { return Promise.reject(E-mail already in use); } }), ), // 验证密码强度 密码确认一致同步自定义验证器 body(password).isLength({ min: 5 }).withMessage(Password must have at least 5 chars), body(passwordConfirmation).custom((value, { req }) { if (value ! req.body.password) { throw new Error(Password confirmation does not match password); } return true; }), ], (req, res) { const errors validationResult(req); if (!errors.isEmpty()) { return res.status(400).json({ errors: errors.array() }); } // 校验通过执行业务逻辑创建用户等 res.sendStatus(201); }, );这个示例同时展示了本文的全部核心能力内置净化器与自定义净化器/验证器混用、.withMessage()定制内置规则消息、throw/reject 定制自定义规则消息、Meta 中的req做跨字段比对以及用validationResult(req)统一收集错误。小结自定义验证器.custom()返回真值或 resolve 的 Promise 表示有效返回假值、reject 或 throw 表示无效。适合一切依赖外部数据或请求上下文的校验。自定义净化器.customSanitizer()返回值直接写回字段验证链与净化链均可使用务必确保函数有显式返回值避免字段意外变成undefined。Meta 参数提供req、location、path、pathValues让自定义函数拥有与内置规则同等的上下文感知能力。错误消息优先使用.withMessage()显式指定未指定时throw/reject 的值即消息。源码依据接口定义见 src/chain/validators.ts 与 src/chain/sanitizers.ts执行语义见 src/context-items/custom-validation.ts 与 src/context-items/sanitization.ts行为佐证见 src/context-items/custom-validation.spec.ts 与 src/context-items/sanitization.spec.ts。当你发现内置规则不够用时.custom()与.customSanitizer()就是表达任意业务校验逻辑的通用接口——掌握它们express-validator 便能覆盖几乎任何你遇到的校验与清洗场景。赞分享后端【免费下载链接】express-validatorAn express.js middleware for validator.js.项目地址https://gitcode.com/gh_mirrors/ex/express-validator点击查看免费下载相关推荐express-validator 自定义验证器与自定义净化器Custom Validators/Sanitizers完整实战指南express validator 自定义验证器与自定义净化器Custom Validators/Sanitizers完整实战指南 express vali后端express-validator 自定义校验器与净化器Custom Validators Sanitizers实战指南express validator 自定义校验器与净化器Custom Validators Sanitizers实战指南 express validat后端express-validator 自定义校验器与净化器Custom Validators Sanitizers实战指南express validator 自定义校验器与净化器Custom Validators Sanitizers实战指南 express validat后端上一篇Gramps从零开始构建你的家族历史数据库让家族记忆永不褪色下一篇ASP.NET Core 集成 CouchDB基于 RESTful API 的文档型 NoSQL 实战指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考