接口参数校验与数据格式规范

把不可信输入转换为业务可以直接使用的明确数据

🎯 引言

学完这篇文章,你能为接口字段定义校验规则,拒绝无效输入,并使用校验后的数据。

🧾 先确定字段规则

以接收用户资料为例,接口要求:

字段规则合法示例
name字符串,去掉两侧空白后长度为 1 到 40小明
age整数,0 到 15020
其他字段拒绝,防止提交 role 等内部字段不提交

合法 JSON 只说明语法正确,不能保证这些规则成立。使用 Zod 描述规则,它是用于检查数据类型与内容的校验库。

安装本节需要的依赖:

npm install zod@4.6.7

🏷 定义 name 规则

新建 user-schema.mjs:

user-schema.mjs
import { z } from 'zod';

const nameSchema = z.string().trim().min(1).max(40);

它要求输入为字符串,先移除两侧空白,再检查长度。空字符串或只有空白会失败;长度按 JavaScript 字符串计数,部分 emoji 会占多个单位。


🔢 定义 age 规则

在同一文件添加年龄规则:

user-schema.mjs
const ageSchema = z.number().int().min(0).max(150);

JSON 中的数字 20 可以通过,字符串 "20" 不能通过。这里不自动转换类型,避免客户端发错格式却被悄悄接受。


🧩 组合成用户资料规则

继续导出完整规则:

user-schema.mjs
export const userSchema = z.strictObject({
    name: nameSchema,
    age: ageSchema
});

strictObject 要求只出现声明的字段。缺少 name 或 age、额外带 role 都会失败。校验成功后使用返回的数据,其中 name 已去除两侧空白。


🚪 在接口中执行校验

新建 validation-server.mjs:

validation-server.mjs
import express from 'express';
import { userSchema } from './user-schema.mjs';

const app = express();
app.use(express.json({ limit: '16kb' }));

添加资料检查接口:

validation-server.mjs
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 是校验后的对象。这个接口只检查并回显,没有写数据库。

最后监听:

validation-server.mjs
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:字段格式正确就允许修改吗?

还需检查身份、权限和业务规则,例如名字是否已占用。


🧪 小练习

增加一个可选的简介字段,限制为字符串并设置长度上限,验证缺少该字段和超长输入的不同结果。

// 请在这里编写代码