企业官网建设流程全解析

• 后端

导读

本文聚焦 express-validator 中一个常被忽视但非常实用的能力：全量请求体验证（Whole Body Validation）。当你面对的不是标准 JSON 对象、而是字符串、数组甚至数字形式的请求体时，可以直接省略字段路径，把整个req.body作为验证与清洗目标。文章以 v5.2.0 文档为基础，结合仓库中docs/guides/field-selection.md的字段选择语法与src/field-selection.ts的底层实现，为你讲清原理、给出可复制的代码与 HTTP 示例，并延伸到全量选择在其他请求位置（req.cookies、req.params、req.query、req.headers）的应用方式，帮助你写出既能覆盖"整块数据"、又能精准命中嵌套字段的健壮验证中间件。

何时需要"全量请求体验证"

express-validator 的常规用法是面向对象化请求体做字段级验证，例如body('email').isEmail()。但在真实业务里，请求体并不总是 JSON 对象：

• 文本型接口：密码找回、短信/邮件验证码等接口常以text/plain发送原始字符串，请求体就是一个裸字符串；
• 批量型接口：数组本身就是请求体的核心内容，需要整体校验（如批量更新 ID 列表、数组型标签集合）；
• 数值型接口：请求体可能直接是数字，比如上报心跳间隔、经纬度坐标等。

当请求体的"根"就是待验证的数据时，为它硬套一个字段名毫无意义——这时就应该省略字段参数，直接对整个req.body执行验证与清洗。

v5.2.0 文档website/versioned_docs/version-5.2.0/feature-whole-body-validation.md开篇即点明这一场景："Sometimes you need to validate requests whose body is a string, an array, or even a number!（有时你需要验证请求体是字符串、数组甚至数字的请求！）"

省略字段参数：body() 直接作用于 req.body

经典文本请求体示例

以下代码来自 v5.2.0 原文档，演示了对text/plain文本请求体直接做isEmail()验证的完整配置：

const bodyParser = require('body-parser'); const express = require('express'); const { body } = require('express-validator/check'); const app = express(); // Will handle text/plain requests app.use(bodyParser.text()); app.post('/recover-password', body().isEmail(), (req, res) => { // Assume the validity of the request was already checked User.recoverPassword(req.body).then(() => { res.send('Password recovered!'); }); });

该配置能够正确处理如下原始 HTTP 请求：

POST /recover-password HTTP/1.1 Host: localhost:3000 Content-Type: text/plain my@email.com

逐行拆解这个示例：

1. app.use(bodyParser.text())：express.json()只解析application/json，无法把text/plain解析成req.body对象，因此这里必须先用body-parser的text()中间件把文本请求体挂到req.body上；
2. body()：body链构造函数来自express-validator/check，调用时不传字段参数。从源码看，check()的字段参数默认值是''（空字符串），见src/middlewares/check.ts#L12-L16：

   export function check(fields: string | string[] = '', ...): ValidationChain

   所以body()与body('')在语义上等价，都表示"选中整个req.body"；

3. body().isEmail()：isEmail()直接作用于req.body这个字符串上，验证通过后req.body即为'my@email.com'；
4. User.recoverPassword(req.body)：业务处理器拿到的是被验证过的原始字符串，可以直接使用。

需要特别说明：express-validator 只负责"验证并记录结果"，不会自动中断请求或返回错误响应。上例中的"Assume the validity of the request was already checked"注释意味着：在实际项目中，你应该在处理器内用validationResult(req)检查验证结果，失败时提前返回错误（详见 getting-started.md 的"Handling validation errors"一节）。

为什么不传参数与传空字符串等价

在字段选择层面，全量选择有两条等价写法，出自docs/guides/field-selection.md的 "Whole-body selection" 小节：

app.post( '/recover-password', // These are equivalent. body().isEmail(), body('').isEmail(), (req, res) => { // Handle request }, );

从实现角度可以更精确地理解"全量选择"：

• selectFields()（见src/field-selection.ts#L10-L21）会依次展开每个字段路径对应的请求位置；
• 在expandField()（src/field-selection.ts#L27-L43）中，当展开后的路径为空字符串''时，取值逻辑是const value = path === '' ? req[location] : _.get(req[location], path);——路径为空时直接返回整个req[location]对象（对body()而言即整个req.body）；
• 因此body().isEmail()与body('').isEmail()产生完全相同的FieldInstance：path: ''、location: 'body'、value: req.body。

全量选择不限于 body：其他请求位置也能整块校验

docs/guides/field-selection.md的全量选择小节有一条重要提示：

It's possible to select the wholereq.cookies,req.paramsand etc too, though it's probably not as useful or common as it'd be withreq.body.

也就是说，"省略字段 = 选择整个位置"的机制对req.cookies、req.params、req.query、req.headers同样成立。这与链构造函数的设计一一对应（见src/middlewares/validation-chain-builders.ts#L10-L50）：

这些构造函数都由buildCheckFunction(locations)生成，内部统一委托给check(fields, locations, message)。因此全量选择的底层规则完全一致：字段为空 → 选中整个位置。

底层原理：字段选择与请求位置展开

理解全量请求体验证，离不开 express-validator 的字段选择模型。一个验证链最终经历如下过程（可结合源码验证）：

1. 构造上下文：body()创建的链内部持有ContextBuilder，setFields([''])、setLocations(['body'])（见src/middlewares/check.ts#L17-L20与src/context-builder.ts#L14-L22）；
2. 选择字段实例：真正执行时，ContextRunner调用selectFields(req, [''] , ['body'])（见src/field-selection.ts#L10-L21），对所有字段 × 位置做笛卡尔展开，再按path+location去重；
3. 空路径特判：expandField()中path === ''时直接取req[location]整体作为value（见src/field-selection.ts#L34），这就是"全量选择"的本质；
4. 执行验证/清洗：每个FieldInstance依次经过验证链上的所有校验器（如isEmail()）与清洗器（如trim()、escape()），结果写入对应Context。

正因为第 3 步的空路径特判，全量选择与字段级选择的代码路径是统一且稳定的——这也是为什么body()、body('')两种写法长期并存、效果完全一致。

全量验证的进阶组合：通配符（Wildcard）与 Globstar

全量选择解决的是"请求体根就是数据"的场景；若请求体是一个对象/数组，但你希望批量命中其中所有同类字段，则属于字段选择的高级特性。以下内容同样来自仓库的docs/guides/field-selection.md，与全量选择共同构成"选择数据"的完整工具箱。

通配符*：命中数组所有下标或对象所有键

*可替换任意一个字段段，精确命中该层数组的所有下标、或该层对象的所有键；每个命中字段都会作为独立实例分别验证/清洗，若所在数组或对象为空则什么都不验证。

假设更新用户资料接口接收如下请求体：

{ "addresses": { "home": { "number": 35 }, "work": { "number": 501 } }, "siblings": [{ "name": "Maria von Validator" }, { "name": "Checky McCheckFace" }] }

可用两条链验证"所有地址编号为整数、所有兄弟名为非空"：

app.post( '/update-user', body('addresses.*.number').isInt(), body('siblings.*.name').notEmpty(), (req, res) => { // Handle request }, );

源码实现（src/field-selection.ts#L98-L102）中，expandPath遇到*段时对Object.keys(object)逐键递归展开，每个键生成一个独立FieldInstance，印证了文档"每个命中字段被独立验证"的表述。

Globstar**：无限深度命中所有同名嵌套字段

当嵌套层级未知时（如递归结构的组织架构图），用**无限深度命中：

{ "name": "Team name", "teams": [{ "name": "Subteam name", "teams": [] }] }

app.put('/update-chart', body('**.name').notEmpty(), (req, res) => { // Handle request });

该链会检查req.body根部的name以及任意深度嵌套的name是否非空。其递归实现位于src/field-selection.ts#L103-L117：对每个键同时尝试"继续用**展开"与"跳过当前段继续匹配剩余路径"两条分支，最后按路径去重。

实战提示：当请求体本身就是普通对象时，"全量选择 + 通配符/Globstar"是互补的两种策略——前者把根数据视为整体（适用于裸字符串/数组/数字），后者把根数据视为容器并批量处理内部字段（适用于嵌套对象）。

版本说明与迁移要点

本文核心代码取自 v5.2.0 文档（website/versioned_docs/version-5.2.0/feature-whole-body-validation.md）。若你正在使用较新版本，请注意以下差异：

1. 导入路径：v5 文档中的require('express-validator/check')在 v6+ 中已弃用并会打印警告，应改为require('express-validator')（见docs/migration-v5-to-v6.md的 Deprecations 小节）。body()等链构造函数本身从 v5 到 v7 持续可用，只是统一从主入口导入；
2. 整体行为不变：v6.15.0 版本的同名文档（website/versioned_docs/version-6.15.0/feature-whole-body-validation.md）保留了与 v5.2.0 几乎一致的示例代码与 HTTP 请求，仅更新了导入语句，证明全量请求体验证这一核心能力跨版本稳定；
3. 运行环境：当前仓库package.json声明"engines": { "node": ">= 14.0.0" }，依赖validator ~13.15.35与lodash，使用本文示例前请确保 Node 版本满足要求。

延伸阅读

• 字段路径语法完整说明（含siblings[0]、websites["www.example.com"]等特殊键选择）：field-selection.md
• 从零搭建 Express 应用并接入验证中间件、处理验证结果：getting-started.md
• 验证结果读取与格式化（validationResult）：validation-result.md
• 链式验证/清洗 API 全览：src/chain/validation-chain.ts、src/chain/validators.ts、src/chain/sanitizers.ts
• 字段选择与未知字段判定的核心实现：field-selection.ts
• 链构造函数的默认参数与请求位置绑定实现：check.ts、validation-chain-builders.ts

• 后端