Nuxt4 中可以利用 Zod 库对请求参数进行类型校验。

Zod 是一个原生支持 TypeScript 的数据校验库。通过使用 Zod，你可以定义 模式（schemas） 并用其校验数据，无论要校验的数据是简单的 string 类型还是复杂的嵌套对象，Zod都可以轻松处理。

并且 Nuxt4 中间接依赖了 Zod，不用安装直接就可以使用

如何使用 Zod

Zod 的使用也非常简单，只需两步，先定义模式，再解析数据。在解析数据时只有校验成功的数据才能拿到解析结果，没有校验成功则会抛出错误。

1、定义模式

import { z } from 'zod'

const UserSchema=z.object({
  name:z.string(),
  password:z.string(),
})

在这里, z.object, z.string() 都是 Zod 中的校验方法，类似的还有 z.boolean()、z.number()、z.undefined() 等等，这些校验方法会返回一个模式，每个模式都有一个parse 方法可以用来解析数据。

2、解析数据

定义模式之后，就可以使用模式上的 parse 方法解析数据，就像前面提到的，在解析数据时只有校验成功的数据才能拿到解析结果，没有校验成功则会抛出错误。

UserSchema.parse({name:'张三',password:'123456',})
// return=> {name:'张三',password:'123456'}

try {
  UserSchema.parse({name:123, password:'123456'})
} catch (error) {
  console.log(error)
// ZodError: [
//   {
//     "code": "invalid_type",
//     "expected": "string",
//     "received": "number",
//     "path": ["name"],
//     "message": "Expected string, received number"
//   }
// ]
}

如果不想校验失败时抛出错误，可以使用模式上的 safeParse 方法，safeParse 方法会返回一个包含成功解析的数据或失败错误的ZodError 对象实例，ZodError对象实例也就是前面parse 方法解析错误抛出的错误对象。

还是以上面的 UserSchema 为例：

const result = UserSchema.safeParse({ name: 42, password:'123456'});
if (!result.success) {
  result.error;   // ZodError instance
} else {
  result.data;    // { username: string; password: string }
}

搭配 Nuxt

在Nuxt4 中，不用安装 Zod 就可以直接上手使用。下面是用户登录接口校验数据的例子

import { z } from 'zod'

const UserSchema=z.object({
  name:z.string(),
  password:z.string(),
})
export default defineEventHandler(async (event) => {
  const body = await readBody(event)
  const result = UserSchema.safeParse(body)
  if(!result.success){
    throw createError({
      statusCode: 400,
      message: 'param error',
    })
  }
  const {name,password}=result.data
})

Nuxt4 提供了内置的 readValidatedBody 方法，可以将上面的读取和校验步骤简化为一步。

import { z } from 'zod'

const UserSchema=z.object({
  name:z.string(),
  password:z.string(),
})
export default defineEventHandler(async (event) => {
  const body = await readValidatedBody(event, body=>UserSchema.safeParse(body))
})

readValidatedBody 方法接收两个参数，分别是 event 和 validateFun，其中 event 是 Nuxt4 提供的事件对象，validateFun 是一个校验函数，这个校验函数接收body参数并返回最后的校验结果。

类似的，对于 get 请求，参数的校验也可以利用 readValidatedQuery 方法实现一步到位

import { z } from 'zod'

const UserSchema=z.object({
  name:z.string(),
  password:z.string(),
})
export default defineEventHandler(async (event) => {
  const query = await readValidatedQuery(event, query=>UserSchema.safeParse(query))
})

Zod 的模式匹配

下面是 Zod 模式匹配的一些常见例子

可选参数

const UserSchema=z.object({
  name:z.string(),
  password:z.string(),
  age:z.optional(z.number()),
})

数字校验

const schema=z.number();

Boolean 校验

const schema=z.boolean();

整数校验

z.int();
z.int32();
z.bigint();

枚举校验

const schema=z.enum(['a','b','c']);

schema.parse('a');✅
schema.parse('d');❌

字符串校验

// 校验
z.string().max(5);
z.string().min(5);
z.string().length(5);
z.string().regex(/^[a-z]+$/);
z.string().startsWith("aaa");
z.string().endsWith("zzz");
z.string().includes("---");
z.string().uppercase();
z.string().lowercase();

// 转换
z.string().trim(); // trim whitespace
z.string().toLowerCase(); // toLowerCase
z.string().toUpperCase(); // toUpperCase

日期校验

对于字符串类型的时间格式

// 日期时间字符串 YYYY-MM-DDTHH:mm:ss.sssZ
const datetime = z.iso.datetime();
datetime.parse("2020-01-01T06:15:00Z"); // ✅
datetime.parse("2020-01-01T06:15:00.123Z"); // ✅
datetime.parse("2020-01-01T06:15:00.123456Z"); // ✅ (arbitrary precision)
datetime.parse("2020-01-01T06:15:00+02:00"); // ❌ (offsets not allowed)
datetime.parse("2020-01-01T06:15:00"); // ❌ (local not allowed)

// 验证 YYYY-MM-DD 格式的字符串
const date = z.iso.date();
date.parse("2020-01-01"); // ✅
date.parse("2020-1-1"); // ❌
date.parse("2020-01-32"); // ❌

// 验证格式为 HH：MM[：SS[.s+]] 的字符串
const time = z.iso.time();
time.parse("03:15"); // ✅
time.parse("03:15:00"); // ✅
time.parse("03:15:00.9999999"); // ✅ (arbitrary precision)

日期格式

const date = z.date()

date.safeParse(new Date()); // success: true
date.safeParse("2022-01-12T06:15:00.000Z"); // success: false

数组校验

// 数字数组
z.array(z.number())

// 对象数组
z.array(z.object({
  name:z.string(),
  password:z.string(),
  age:z.optional(z.number())
}))

更多类型参考 Zod 类型