接口参数校验与数据格式规范
🎯 引言
学完这篇文章,你能为接口字段定义校验规则,拒绝无效输入,并使用校验后的数据。
🧾 先确定字段规则
以接收用户资料为例,接口要求:
| 字段 | 规则 | 合法示例 |
|---|---|---|
| name | 字符串,去掉两侧空白后长度为 1 到 40 | 小明 |
| age | 整数,0 到 150 | 20 |
| 其他字段 | 拒绝,防止提交 role 等内部字段 | 不提交 |
合法 JSON 只说明语法正确,不能保证这些规则成立。使用 Zod 描述规则,它是用于检查数据类型与内容的校验库。
安装本节需要的依赖:
npm install zod@4.6.7
🏷 定义 name 规则
新建 user-schema.mjs:
import { z } from 'zod';
const nameSchema = z.string().trim().min(1).max(40);
它要求输入为字符串,先移除两侧空白,再检查长度。空字符串或只有空白会失败;长度按 JavaScript 字符串计数,部分 emoji 会占多个单位。
🔢 定义 age 规则
在同一文件添加年龄规则:
const ageSchema = z.number().int().min(0).max(150);
JSON 中的数字 20 可以通过,字符串 "20" 不能通过。这里不自动转换类型,避免客户端发错格式却被悄悄接受。
🧩 组合成用户资料规则
继续导出完整规则:
export const userSchema = z.strictObject({
name: nameSchema,
age: ageSchema
});
strictObject 要求只出现声明的字段。缺少 name 或 age、额外带 role 都会失败。校验成功后使用返回的数据,其中 name 已去除两侧空白。
🚪 在接口中执行校验
新建 validation-server.mjs:
import express from 'express';
import { userSchema } from './user-schema.mjs';
const app = express();
app.use(express.json({ limit: '16kb' }));
添加资料检查接口:
app.post('/users/validate', (req, res) => {
const result = userSchema.safeParse(req.body);
if (!result.success) {
const message = result.error.issues[0].message;
return res.status(400).json({ error: { code: 'INVALID_INPUT', message } });
}
res.json({ data: result.data });
});
safeParse 返回校验结果,不需要为普通校验失败编写异常类。失败时 issues 是错误列表,示例返回第一条提示;成功时 data 是校验后的对象。这个接口只检查并回显,没有写数据库。
最后监听:
app.listen(3000, '127.0.0.1');
🧪 用输入与结果核对规则
运行 node validation-server.mjs,再提交:
curl -i http://127.0.0.1:3000/users/validate -H 'Content-Type: application/json' -d '{"name":" 小明 ","age":20}'
得到 200 和 {"data":{"name":"小明","age":20}}。把 age 改为字符串、删除 name 或添加 role,都会得到 400 和 INVALID_INPUT。
接口给前端的错误码应稳定,提示文字可以按产品需要翻译或调整。不要把数据库异常等内部错误当作字段提示直接公开。
❓ 知识问答
Q1:前端已经校验过,后端还需要吗?
需要,请求可以绕过页面直接发送,后端必须检查实际收到的值。
Q2:校验成功后继续用 req.body 可以吗?
应使用 result.data,里面才是经过规则处理后的数据,例如去除空白后的名字。
Q3:字段格式正确就允许修改吗?
还需检查身份、权限和业务规则,例如名字是否已占用。
🧪 小练习
增加一个可选的简介字段,限制为字符串并设置长度上限,验证缺少该字段和超长输入的不同结果。
// 请在这里编写代码
