在前后端分离开发模式中,数据校验是保障接口安全与数据规范的核心环节。行业通用开发原则为:前端校验负责优化用户体验,实时提示输入错误;后端校验负责兜底防护,永远不信任用户提交的任何数据,所有接口入参必须经过后端二次校验。
前端 Element-Plus 组件库默认基于 async-validator 实现表单校验,该库拥有配置灵活、规则丰富、支持 Promise 异步调用、可高度自定义等优势。为了实现前后端校验规则统一、降低维护成本、统一报错格式,我们可以在 Express 后端项目中同样引入 async-validator,实现全栈一致的数据校验体系。
本文基于 Node.js + TypeScript + Express 技术栈,手把手讲解后端集成 async-validator 的完整方案,全程采用 TS 语法编写,代码规范可直接用于项目开发。
如需搭建 Node.js + TypeScript 基础开发环境,可参考:Node.js+TypeScript 开发环境搭建教程
一、核心实现原理
1.1 Express 错误处理机制
Express 框架内置默认错误处理机制,可捕获路由、中间件运行过程中产生的所有错误。开发者可自定义全局错误处理中间件,覆盖框架默认逻辑,实现个性化错误响应、统一格式返回。
Express 硬性规范:自定义全局错误处理中间件必须包含四个固定参数:(err, req, res, next),对应 TS 类型为 ErrorRequestHandler。
1.2 Express 三种错误触发方式
-
代码运行时自动抛出的语法错误、逻辑错误;
-
通过
throw new Error()主动抛出错误; -
调用中间件/路由的
next(非空参数)传递错误,交由全局错误中间件捕获。
1.3 后端集成 async-validator 核心思路
-
async-validator校验失败时,会返回 reject 状态的 Promise,并携带完整的错误详情; -
通过
try-catch捕获校验异常,将校验错误信息封装为统一格式; -
通过
next()将错误抛出,交由全局错误处理中间件统一拦截、格式化响应,实现业务代码与错误处理、校验逻辑解耦。
二、完整集成实现步骤
2.1 安装依赖
安装数据校验核心库 async-validator,原生支持 TypeScript,无需额外安装类型声明文件:
npm i async-validator
2.2 编写全局统一错误处理中间件
在项目中独立封装全局错误中间件,统一处理系统异常和数据校验异常,规范后端接口返回格式,提升前端对接效率。
新建 src/middleWares/errorHandler.ts:
import { ErrorRequestHandler } from "express";
// 全局错误处理中间件(固定四参数)
export const errorHandler: ErrorRequestHandler = (err, req, res, next) => {
// 处理 async-validator 数据校验错误
if (err.code === 400) {
return res.status(400).json({
code: 400,
message: "数据校验失败",
errors: err.msg.errors,
fields: err.msg.fields
});
}
// 处理系统未知异常
return res.status(500).json({
code: 500,
message: "服务器内部异常,请稍后重试"
});
};
2.3 封装数据校验中间件
针对具体接口定义校验规则,封装可复用的校验中间件,精准校验请求体参数,业务路由只需专注业务逻辑。
新建 src/middleWares/itemRules.ts:
import Schema, { Rules } from "async-validator";
import { RequestHandler } from "express";
// 定义接口参数校验规则
const descriptor: Rules = {
name: [
{ required: true, message: "姓名必须填写" },
{ min: 3, max: 30, message: "姓名长度需在3-30个字符之间" }
],
age: [
{ required: true, message: "年龄必须填写" }
]
};
// 实例化校验器
const validator = new Schema(descriptor);
// 导出商品新增接口校验中间件
export const itemsPostValidator: RequestHandler = async (req, res, next) => {
try {
// 校验请求体数据
await validator.validate(req.body);
// 校验通过,放行进入业务逻辑
next();
} catch (error) {
// 校验失败,抛出错误至全局错误中间件
next({ code: 400, msg: error });
}
};
2.4 编写业务路由并注册校验中间件
在业务路由中注册对应校验中间件,仅需一行代码即可完成接口校验,无需重复编写判断逻辑。
新建 src/routes/items.ts:
import express from "express";
import { itemsPostValidator } from "../middleWares/itemRules";
export const items = express.Router();
// 商品新增接口:先走校验中间件,再执行业务逻辑
items.post("/", itemsPostValidator, (req, res) => {
// 校验通过后,正常处理业务(入库、逻辑计算等)
res.json({
code: 200,
message: "数据提交成功",
data: req.body
});
});
2.5 全局注册中间件与路由
在项目入口文件统一注册解析中间件、业务路由、全局错误处理中间件,错误中间件必须在所有路由后注册。
新建 src/index\.ts:
import express from "express";
import { errorHandler } from "./middleWares/errorHandler";
import { items } from "./routes/items";
const app = express();
const PORT = 3000;
// 解析 json、form-urlencoded 请求体
app.use(express.json());
app.use(express.urlencoded({ extended: true }));
// 注册业务路由
app.use("/items", items);
// 全局错误处理中间件(必须放在所有路由最后)
app.use(errorHandler);
// 启动服务
app.listen(PORT, () => {
console.log(`服务启动成功,监听端口:${PORT}`);
});
三、接口测试验证
启动项目后,通过接口测试工具向 http://localhost:3000/items 发送 POST 请求,传入不合法参数,测试校验效果。
测试请求参数
{
"name": "mu88888888888888888888888888888888888"
}
参数问题:name 长度超出30个字符、必填字段 age 缺失。
接口返回结果
{
"code": 400,
"message": "数据校验失败",
"errors": [
{
"message": "姓名长度需在3-30个字符之间",
"fieldValue": "mu88888888888888888888888888888888888",
"field": "name"
},
{
"message": "年龄必须填写",
"field": "age"
}
],
"fields": {
"name": [
{
"message": "姓名长度需在3-30个字符之间",
"fieldValue": "mu88888888888888888888888888888888888",
"field": "name"
}
],
"age": [
{
"message": "年龄必须填写",
"field": "age"
}
]
}
}
测试结果:校验规则正常生效,精准拦截非法参数,返回结构化错误信息,前后端可统一对接处理。
四、后端核心注意事项
前端表单提交的所有参数,默认均为 string 类型,因此后端使用 async-validator 需注意类型校验适配:
-
常规文本、账号、姓名等字符串参数,可直接使用
type:'string';规则,无需额外处理; -
数字、布尔类型参数(年龄、状态、价格等),不建议直接使用 type 强制校验类型,否则会因前端传参均为字符串导致校验失败;
-
如需校验数字、布尔类型,可通过
transform主动转换参数类型后再校验,适配前端传参特性,示例如下:age: [ { required: true, message: "年龄必须填写" }, { transform: (val) => Number(val) }, { type: "number", message: "年龄必须为数字" }, { min: 1, max: 120, message: "年龄范围必须在1-120之间" } ]
五、全文总结
-
数据校验必须遵循前端优化体验、后端保障安全的原则,后端不可信任任何用户输入;
-
Express 通过四参数全局错误中间件,可统一捕获全局异常,实现错误处理逻辑解耦;
-
集成
async-validator可实现前后端校验规则统一,减少重复代码,提升项目可维护性; -
后端校验需适配前端传参特性,通过
transform解决参数类型不匹配问题,保证校验规则灵活可用。
300



被折叠的 条评论
为什么被折叠?



