Zod 校验集成

本示例展示如何使用 Zod 替换 VextJS 内置的 schema-dsl 校验引擎。通过编写一个 Zod 校验插件，你可以在路由的 validate 配置中直接使用 Zod schema，获得更强大的类型推断和校验能力。

为什么选择 Zod？

特性	内置 schema-dsl	Zod
学习曲线	低（DSL 字符串语法）	中（链式 API）
TypeScript 类型推断	❌ 无（需手动声明泛型）	✅ 自动推断 `z.infer<T>`
复杂校验	基础类型 + 范围 + 枚举	联合类型、递归、transform、refine 等
生态	VextJS 专属	广泛使用，社区生态丰富
包体积	0（框架内置）	~14KB (min+gzip)

Tip

如果你的项目只需要简单的参数校验（字符串/数字/枚举/邮箱等），内置的 schema-dsl 已经足够。Zod 更适合需要复杂校验逻辑、深度类型推断或已在项目中使用 Zod 的场景。

项目结构

zod-validation/
  ├── src/
  │   ├── config/
  │   │   └── default.ts
  │   ├── plugins/
  │   │   └── zod-validator.ts     ← Zod 校验插件
  │   ├── routes/
  │   │   ├── index.ts
  │   │   └── users.ts
  │   ├── services/
  │   │   └── user.ts
  │   ├── schemas/                  ← Zod schema 定义
  │   │   └── user.ts
  │   └── index.ts
  ├── package.json
  └── tsconfig.json

1. 安装依赖

npx vextjs create zod-validation
cd zod-validation
pnpm add zod

2. Zod 校验插件

核心思路：通过 app.setValidator() 替换内置的 schema-dsl 校验引擎。VextValidator 接口要求实现 compile(schema) 方法，返回一个校验函数。

// src/plugins/zod-validator.ts
import { definePlugin } from "vextjs";
import { ZodType, ZodError } from "zod";

/**
 * Zod 校验插件
 *
 * 替换内置 schema-dsl 校验引擎，使路由 validate 配置支持 Zod schema。
 *
 * 使用方式：
 *   validate: {
 *     body: userCreateSchema,   // 直接传入 Zod schema 对象
 *     query: paginationSchema,
 *   }
 *
 * 校验流程：
 *   1. compile(schema) 接收原始 schema 对象
 *   2. 检查 schema 的每个字段是否为 ZodType 实例
 *   3. 如果是 Zod schema，使用 safeParse 进行校验
 *   4. 如果不是（普通对象），回退到原始校验器（兼容 schema-dsl）
 */
export default definePlugin({
  name: "zod-validator",
  setup(app) {
    // 保存原始校验器，用于回退
    const originalValidator = app.getValidator();

    app.setValidator({
      compile(schema: Record<string, unknown>) {
        // ── 判断 schema 是否为 Zod schema ──────────────────
        //
        // 路由 validate 的每个位置（query/body/param/header）都是一个独立的 schema。
        // 如果传入的是 ZodType 实例，使用 Zod 校验。
        // 否则回退到原始 schema-dsl 校验器（保持向后兼容）。

        if (schema instanceof ZodType) {
          // ── Zod 校验路径 ─────────────────────────────────
          const zodSchema = schema;

          return (data: unknown) => {
            const result = zodSchema.safeParse(data);

            if (result.success) {
              return {
                valid: true,
                data: result.data,
              };
            }

            // 转换 Zod 错误格式为 VextJS 标准格式
            return {
              valid: false,
              errors: result.error.issues.map((issue) => ({
                field: issue.path.join("."),
                message: issue.message,
              })),
            };
          };
        }

        // ── 检查 schema 对象的字段是否包含 Zod 实例 ─────────
        //
        // 支持 validate: { body: { name: z.string(), age: z.number() } }
        // 这种「对象字段为 Zod」的混合模式。
        // 但更推荐直接传入完整的 z.object({...}) 作为 schema。

        const hasZodFields = Object.values(schema).some(
          (v) => v instanceof ZodType,
        );

        if (hasZodFields) {
          // 将散落的 Zod 字段收集为 z.object
          const { z } = require("zod");
          const shape: Record<string, ZodType> = {};

          for (const [key, value] of Object.entries(schema)) {
            if (value instanceof ZodType) {
              shape[key] = value;
            } else {
              // 非 Zod 字段，包装为 z.any()
              shape[key] = z.any();
            }
          }

          const objectSchema = z.object(shape);

          return (data: unknown) => {
            const result = objectSchema.safeParse(data);

            if (result.success) {
              return {
                valid: true,
                data: result.data,
              };
            }

            return {
              valid: false,
              errors: result.error.issues.map((issue) => ({
                field: issue.path.join("."),
                message: issue.message,
              })),
            };
          };
        }

        // ── 回退到原始 schema-dsl 校验器 ───────────────────
        return originalValidator.compile(schema);
      },
    });

    app.logger.info("[zod-validator] Zod 校验插件已注册");
  },
});

Tip

这个插件向后兼容 schema-dsl。你可以在同一个项目中混合使用 Zod schema 和 schema-dsl DSL 字符串。对于非 Zod 的 schema（如 { name: 'string:1-50' }），插件会自动回退到内置校验引擎。

3. 定义 Zod Schema

将 Zod schema 集中管理在 src/schemas/ 目录下，方便复用和维护。

// src/schemas/user.ts
import { z } from "zod";

// ── 基础字段 schema ──────────────────────────────────────

/** 用户 ID（路径参数） */
export const userIdParam = z.object({
  id: z.string().min(1, "ID 不能为空"),
});

/** 分页查询参数 */
export const paginationQuery = z.object({
  page: z.coerce.number().int().min(1, "页码最小值为 1").default(1),
  limit: z.coerce.number().int().min(1).max(100, "每页最多 100 条").default(10),
  keyword: z.string().optional(),
});

// ── 用户 CRUD schema ────────────────────────────────────

/** 创建用户 */
export const createUserBody = z.object({
  name: z.string().min(1, "姓名不能为空").max(50, "姓名最长 50 个字符").trim(),
  email: z.string().email("邮箱格式无效").toLowerCase(),
  age: z
    .number()
    .int("年龄必须为整数")
    .min(0, "年龄不能为负数")
    .max(200, "年龄不能超过 200")
    .optional(),
  role: z
    .enum(["admin", "user", "editor"], {
      errorMap: () => ({ message: "角色必须为 admin、user 或 editor" }),
    })
    .default("user"),
  tags: z.array(z.string().min(1).max(20)).max(10, "最多 10 个标签").optional(),
  profile: z
    .object({
      bio: z.string().max(500, "简介最长 500 个字符").optional(),
      avatar: z.string().url("头像必须为有效 URL").optional(),
      website: z.string().url("网站必须为有效 URL").optional(),
    })
    .optional(),
});

/** 更新用户（所有字段可选） */
export const updateUserBody = createUserBody
  .partial() // 所有字段变为可选
  .omit({ role: true }) // 不允许通过更新接口修改角色
  .refine((data) => Object.keys(data).length > 0, {
    message: "至少需要提供一个要更新的字段",
  });

/** 批量操作 */
export const batchDeleteBody = z.object({
  ids: z
    .array(z.string().min(1))
    .min(1, "至少选择一个用户")
    .max(50, "单次最多删除 50 个"),
});

// ── 导出推断类型 ─────────────────────────────────────────

/** 从 Zod schema 推断 TypeScript 类型 */
export type CreateUserInput = z.infer<typeof createUserBody>;
export type UpdateUserInput = z.infer<typeof updateUserBody>;
export type PaginationInput = z.infer<typeof paginationQuery>;
export type BatchDeleteInput = z.infer<typeof batchDeleteBody>;

Tip

z.coerce.number() 是 Zod 的类型强制转换，会自动将字符串 '10' 转换为数字 10。这对于查询参数（始终为字符串）特别有用，与 schema-dsl 的自动类型转换行为一致。

4. 配置

// src/config/default.ts
export default {
  port: 3000,
  adapter: "native",
  logger: {
    level: "debug",
    pretty: true,
  },
  cors: {
    enabled: true,
    origins: ["*"],
  },
  response: {
    wrap: true,
    hideInternalErrors: false,
  },
  openapi: {
    enabled: true,
    title: "Zod Validation 示例",
    version: "1.0.0",
    description: "使用 Zod 进行参数校验的 VextJS 示例",
    securitySchemes: {
      bearerAuth: {
        type: "http",
        scheme: "bearer",
        bearerFormat: "JWT",
      },
    },
    guardSecurityMap: {
      auth: "bearerAuth",
    },
  },
  middlewares: [{ name: "auth" }],
};

5. 路由（使用 Zod Schema）

// src/routes/users.ts
import { defineRoutes } from "vextjs";
import {
  userIdParam,
  paginationQuery,
  createUserBody,
  updateUserBody,
  batchDeleteBody,
} from "../schemas/user.js";
import type { CreateUserInput, UpdateUserInput } from "../schemas/user.js";

export default defineRoutes((app) => {
  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  // GET /users/list — 分页查询
  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  app.get(
    "/list",
    {
      validate: {
        query: paginationQuery, // ← Zod schema
      },
      docs: {
        summary: "用户列表",
        description: "分页查询用户列表，支持按姓名或邮箱模糊搜索。",
        tags: ["用户"],
      },
    },
    async (req, res) => {
      // req.valid() 返回的数据已经过 Zod 校验和 transform
      // page/limit 已从字符串自动转换为数字（z.coerce.number()）
      // keyword 为 string | undefined
      const { page, limit, keyword } = req.valid("query");

      const result = await app.services.user.findAll({ page, limit, keyword });
      res.json(result);
    },
  );

  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  // GET /users/:id — 查询详情
  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  app.get(
    "/:id",
    {
      validate: {
        param: userIdParam, // ← Zod schema
      },
      docs: {
        summary: "获取用户详情",
        tags: ["用户"],
        responses: {
          200: { description: "查询成功" },
          404: { description: "用户不存在" },
        },
      },
    },
    async (req, res) => {
      const { id } = req.valid("param");
      const user = await app.services.user.findById(id);

      if (!user) {
        app.throw(404, "用户不存在");
      }

      res.json(user);
    },
  );

  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  // POST /users — 创建用户
  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  app.post(
    "/",
    {
      validate: {
        body: createUserBody, // ← Zod schema
      },
      middlewares: ["auth"],
      docs: {
        summary: "创建用户",
        description: "创建新用户。支持标签和个人资料等复杂嵌套结构。",
        tags: ["用户"],
        responses: {
          201: {
            description: "创建成功",
            example: {
              id: "4",
              name: "Diana",
              email: "diana@example.com",
              role: "user",
              tags: ["developer"],
              profile: { bio: "Hello!" },
            },
          },
          400: { description: "参数校验失败" },
          401: { description: "未认证" },
          409: { description: "邮箱已注册" },
        },
      },
    },
    async (req, res) => {
      // Zod 已自动：
      //   - trim() 了 name
      //   - toLowerCase() 了 email
      //   - 设置了 role 默认值 'user'
      //   - 校验了 tags 数组长度和元素格式
      //   - 校验了 profile 嵌套对象的 URL 格式
      const body = req.valid<CreateUserInput>("body");

      const user = await app.services.user.create(body);
      res.json(user, 201);
    },
  );

  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  // PUT /users/:id — 更新用户
  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  app.put(
    "/:id",
    {
      validate: {
        param: userIdParam,
        body: updateUserBody, // ← partial() + refine()
      },
      middlewares: ["auth"],
      docs: {
        summary: "更新用户",
        description:
          "更新用户信息。所有字段可选，但至少需要提供一个字段。不允许修改角色。",
        tags: ["用户"],
        responses: {
          200: { description: "更新成功" },
          400: { description: "参数校验失败（或未提供任何字段）" },
          401: { description: "未认证" },
          404: { description: "用户不存在" },
          409: { description: "邮箱已被其他用户使用" },
        },
      },
    },
    async (req, res) => {
      const { id } = req.valid("param");
      // updateUserBody 使用了 .partial().omit({ role: true }).refine(...)
      // Zod 确保了至少有一个字段，且不包含 role
      const body = req.valid<UpdateUserInput>("body");

      const user = await app.services.user.update(id, body);
      res.json(user);
    },
  );

  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  // DELETE /users/:id — 删除用户
  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  app.delete(
    "/:id",
    {
      validate: {
        param: userIdParam,
      },
      middlewares: ["auth"],
      docs: {
        summary: "删除用户",
        tags: ["用户"],
        responses: {
          204: { description: "删除成功" },
          401: { description: "未认证" },
          404: { description: "用户不存在" },
        },
      },
    },
    async (req, res) => {
      const { id } = req.valid("param");
      await app.services.user.delete(id);
      res.status(204).json(null);
    },
  );

  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  // POST /users/batch-delete — 批量删除
  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  app.post(
    "/batch-delete",
    {
      validate: {
        body: batchDeleteBody, // ← 数组校验
      },
      middlewares: ["auth"],
      docs: {
        summary: "批量删除用户",
        description: "批量删除多个用户。单次最多 50 个。",
        tags: ["用户"],
        responses: {
          200: { description: "批量删除结果" },
          400: { description: "参数校验失败" },
          401: { description: "未认证" },
        },
      },
    },
    async (req, res) => {
      const { ids } = req.valid("body");

      const results = {
        deleted: [] as string[],
        notFound: [] as string[],
      };

      for (const id of ids) {
        try {
          await app.services.user.delete(id);
          results.deleted.push(id);
        } catch {
          results.notFound.push(id);
        }
      }

      res.json(results);
    },
  );
});

6. 服务层

// src/services/user.ts
import type { VextApp, VextLogger } from "vextjs";
import type { CreateUserInput, UpdateUserInput } from "../schemas/user.js";

interface User {
  id: string;
  name: string;
  email: string;
  age?: number;
  role: string;
  tags?: string[];
  profile?: {
    bio?: string;
    avatar?: string;
    website?: string;
  };
  createdAt: string;
  updatedAt: string;
}

export default class UserService {
  private logger: VextLogger;
  private users: Map<string, User> = new Map();
  private nextId = 1;

  constructor(private app: VextApp) {
    this.logger = app.logger.child({ service: "UserService" });
    this.seed();
  }

  private seed(): void {
    const seedUsers: Partial<User>[] = [
      {
        name: "Alice",
        email: "alice@example.com",
        age: 28,
        role: "admin",
        tags: ["管理员"],
      },
      { name: "Bob", email: "bob@example.com", age: 32, role: "user" },
      {
        name: "Charlie",
        email: "charlie@example.com",
        role: "editor",
        profile: { bio: "编辑" },
      },
    ];

    for (const u of seedUsers) {
      const id = String(this.nextId++);
      const now = new Date().toISOString();
      this.users.set(id, { id, ...u, createdAt: now, updatedAt: now } as User);
    }
  }

  async findAll(options: { page: number; limit: number; keyword?: string }) {
    let allUsers = Array.from(this.users.values());

    if (options.keyword) {
      const kw = options.keyword.toLowerCase();
      allUsers = allUsers.filter(
        (u) =>
          u.name.toLowerCase().includes(kw) ||
          u.email.toLowerCase().includes(kw),
      );
    }

    const total = allUsers.length;
    const start = (options.page - 1) * options.limit;
    const items = allUsers.slice(start, start + options.limit);

    return {
      items,
      total,
      page: options.page,
      limit: options.limit,
      totalPages: Math.ceil(total / options.limit),
    };
  }

  async findById(id: string): Promise<User | null> {
    return this.users.get(id) ?? null;
  }

  async create(data: CreateUserInput): Promise<User> {
    // 邮箱唯一性检查
    for (const user of this.users.values()) {
      if (user.email === data.email) {
        this.app.throw(409, "邮箱已注册", 10001);
      }
    }

    const id = String(this.nextId++);
    const now = new Date().toISOString();

    const user: User = {
      id,
      name: data.name,
      email: data.email,
      age: data.age,
      role: data.role,
      tags: data.tags,
      profile: data.profile,
      createdAt: now,
      updatedAt: now,
    };

    this.users.set(id, user);
    this.logger.info({ userId: id, email: data.email }, "用户创建成功");
    return user;
  }

  async update(id: string, data: UpdateUserInput): Promise<User> {
    const user = this.users.get(id);
    if (!user) {
      this.app.throw(404, "用户不存在");
    }

    if (data.email && data.email !== user.email) {
      for (const u of this.users.values()) {
        if (u.email === data.email) {
          this.app.throw(409, "邮箱已被其他用户使用", 10002);
        }
      }
    }

    const updated: User = {
      ...user,
      ...data,
      // 深度合并 profile
      profile: data.profile
        ? { ...user.profile, ...data.profile }
        : user.profile,
      updatedAt: new Date().toISOString(),
    };

    this.users.set(id, updated);
    return updated;
  }

  async delete(id: string): Promise<void> {
    if (!this.users.has(id)) {
      this.app.throw(404, "用户不存在");
    }
    this.users.delete(id);
  }
}

7. 入口文件

// src/index.ts
import { bootstrap } from "vextjs";

bootstrap().catch((err) => {
  console.error("启动失败:", err);
  process.exit(1);
});

8. 运行与验证

# 启动开发服务器
pnpm dev

测试校验

# ✅ 正常创建（Zod 自动 trim name + toLowerCase email）
curl -X POST http://localhost:3000/users \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer user-1-admin" \
  -d '{
    "name": "  Diana  ",
    "email": "Diana@EXAMPLE.COM",
    "age": 25,
    "tags": ["developer", "designer"],
    "profile": { "bio": "全栈开发者", "website": "https://diana.dev" }
  }'
# → 201
# name 被 trim 为 "Diana"
# email 被 toLowerCase 为 "diana@example.com"
# role 默认设为 "user"

# ❌ 嵌套对象校验 — profile.avatar 非 URL
curl -X POST http://localhost:3000/users \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer user-1-admin" \
  -d '{
    "name": "Eve",
    "email": "eve@example.com",
    "profile": { "avatar": "not-a-url" }
  }'
# → 400 {"errors":[{"field":"profile.avatar","message":"头像必须为有效 URL"}]}

# ❌ 数组长度校验 — 超过 10 个标签
curl -X POST http://localhost:3000/users \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer user-1-admin" \
  -d '{
    "name": "Eve",
    "email": "eve@example.com",
    "tags": ["1","2","3","4","5","6","7","8","9","10","11"]
  }'
# → 400 {"errors":[{"field":"tags","message":"最多 10 个标签"}]}

# ❌ refine 校验 — 更新时未提供任何字段
curl -X PUT http://localhost:3000/users/1 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer user-1-admin" \
  -d '{}'
# → 400 {"errors":[{"field":"","message":"至少需要提供一个要更新的字段"}]}

# ❌ omit 校验 — 更新时尝试修改角色（被 omit 移除）
curl -X PUT http://localhost:3000/users/1 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer user-1-admin" \
  -d '{"role": "admin", "name": "Alice Updated"}'
# → 200 但 role 字段被忽略（Zod strip 未知字段），只有 name 被更新

# ❌ 枚举校验 — 无效的角色值
curl -X POST http://localhost:3000/users \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer user-1-admin" \
  -d '{"name":"Frank","email":"frank@example.com","role":"superadmin"}'
# → 400 {"errors":[{"field":"role","message":"角色必须为 admin、user 或 editor"}]}

# ✅ 查询参数自动类型转换（z.coerce.number）
curl "http://localhost:3000/users/list?page=2&limit=5"
# → page 自动从字符串 "2" 转为数字 2

# ✅ 批量删除
curl -X POST http://localhost:3000/users/batch-delete \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer user-1-admin" \
  -d '{"ids": ["1", "2", "999"]}'
# → {"code":0,"data":{"deleted":["1","2"],"notFound":["999"]},...}

Zod 高级技巧

Transform（数据转换）

import { z } from "zod";

// 查询参数：逗号分隔字符串 → 数组
const searchQuery = z.object({
  ids: z
    .string()
    .transform((val) => val.split(",").filter(Boolean))
    .pipe(z.array(z.string().min(1)).min(1))
    .optional(),
  sort: z
    .string()
    .regex(/^[a-zA-Z]+:(asc|desc)$/, "排序格式：field:asc 或 field:desc")
    .transform((val) => {
      const [field, order] = val.split(":");
      return { field, order: order as "asc" | "desc" };
    })
    .optional(),
});

// 使用
app.get("/search", { validate: { query: searchQuery } }, async (req, res) => {
  const { ids, sort } = req.valid("query");
  // ids: string[] | undefined
  // sort: { field: string, order: 'asc' | 'desc' } | undefined
});

Discriminated Union（区分联合类型）

import { z } from "zod";

// 根据 type 字段使用不同的校验规则
const notificationBody = z.discriminatedUnion("type", [
  z.object({
    type: z.literal("email"),
    to: z.string().email(),
    subject: z.string().min(1).max(200),
    body: z.string().min(1),
  }),
  z.object({
    type: z.literal("sms"),
    phone: z.string().regex(/^\+?[\d\s-]{10,15}$/),
    message: z.string().min(1).max(160),
  }),
  z.object({
    type: z.literal("push"),
    deviceToken: z.string().min(1),
    title: z.string().min(1).max(100),
    body: z.string().min(1).max(500),
  }),
]);

app.post("/notify", { validate: { body: notificationBody } }, handler);

Preprocess（预处理）

import { z } from "zod";

// 处理 "true" / "false" 字符串到布尔值的转换（常见于查询参数）
const filterQuery = z
  .object({
    active: z.preprocess((val) => {
      if (val === "true") return true;
      if (val === "false") return false;
      return val;
    }, z.boolean().optional()),
    minAge: z.coerce.number().int().min(0).optional(),
    maxAge: z.coerce.number().int().max(200).optional(),
  })
  .refine(
    (data) => {
      if (data.minAge !== undefined && data.maxAge !== undefined) {
        return data.minAge <= data.maxAge;
      }
      return true;
    },
    { message: "minAge 必须小于等于 maxAge", path: ["minAge"] },
  );

复用与组合

import { z } from "zod";

// 基础 schema
const addressSchema = z.object({
  street: z.string().min(1).max(200),
  city: z.string().min(1).max(50),
  state: z.string().min(1).max(50),
  zip: z.string().regex(/^\d{6}$/, "邮编必须为 6 位数字"),
  country: z.string().min(1).max(50).default("中国"),
});

// 组合使用
const orderSchema = z.object({
  items: z
    .array(
      z.object({
        productId: z.string().uuid(),
        quantity: z.number().int().min(1).max(999),
        price: z.number().positive(),
      }),
    )
    .min(1, "至少需要一个商品"),
  shippingAddress: addressSchema,
  billingAddress: addressSchema.optional(), // 可选，复用同一个 schema
  note: z.string().max(500).optional(),
});

// 从已有 schema 推断类型
type Order = z.infer<typeof orderSchema>;
type Address = z.infer<typeof addressSchema>;

与 schema-dsl 混合使用

Zod 插件支持在同一个项目中同时使用 Zod 和 schema-dsl：

// 这个路由使用 Zod
app.post(
  "/users",
  {
    validate: {
      body: createUserBody, // ← Zod schema
      query: paginationQuery, // ← Zod schema
    },
  },
  handler,
);

// 这个路由使用 schema-dsl（自动回退）
app.get(
  "/health",
  {
    validate: {
      query: {
        verbose: "boolean?", // ← schema-dsl 字符串
      },
    },
  },
  handler,
);

插件内部会自动检测 schema 类型，Zod 实例走 Zod 校验路径，普通对象走 schema-dsl 路径。

关键对比

场景	schema-dsl	Zod
简单字段校验	`name: 'string:1-50'`	`z.string().min(1).max(50)`
可选字段	`age: 'number?'`	`z.number().optional()`
枚举	`role: 'enum:admin,user'`	`z.enum(['admin', 'user'])`
邮箱	`email: 'email'`	`z.string().email()`
嵌套对象	❌ 不支持	`z.object({ profile: z.object({...}) })`
数组校验	`tags: 'array'`	`z.array(z.string()).max(10)`
联合类型	❌ 不支持	`z.union([...])` / `z.discriminatedUnion(...)`
自定义校验	❌ 不支持	`.refine()` / `.superRefine()`
数据转换	仅类型转换	`.transform()` / `.preprocess()`
默认值	❌ 不支持	`.default()`
类型推断	❌ 需手动声明	✅ `z.infer<typeof schema>`

下一步

📖 Drizzle ORM 集成 — 接入类型安全的 ORM
📖 Prisma ORM 集成 — 接入 Prisma 数据库工具
📖 参数校验 — 深入了解内置 schema-dsl 校验
📖 插件 — 了解插件开发的更多细节
📖 测试 — 使用 createTestApp 测试 Zod 校验

#Zod 校验集成

#为什么选择 Zod？

#项目结构

#1. 安装依赖

#2. Zod 校验插件

#3. 定义 Zod Schema

#4. 配置

#5. 路由（使用 Zod Schema）

#6. 服务层

#7. 入口文件

#8. 运行与验证

#测试校验

#Zod 高级技巧

#Transform（数据转换）

#Discriminated Union（区分联合类型）

#Preprocess（预处理）

#复用与组合

#与 schema-dsl 混合使用

#关键对比

#下一步