TypeScript + Zod：构建类型安全的API，从验证到生成的完整方案

// 这个接口在编译时看起来很安全
interface User {
  id: string;
  name: string;
  email: string;
  age: number;
}

// 但运行时，外部数据可能是这样的：
const response = await fetch("/api/users/1");
const user: User = await response.json(); // 危险！没有任何运行时验证

// user.age 可能是字符串 "25"，可能是 null，甚至不存在
// TypeScript 不会告诉你这些，直到代码在运行时崩溃

npm install zod

import { z } from "zod";

// 定义一个用户Schema
const UserSchema = z.object({
  id: z.string().uuid(),
  name: z.string().min(2, "姓名至少2个字符").max(50, "姓名最多50个字符"),
  email: z.string().email("请输入有效的邮箱地址"),
  age: z.number().int().min(0).max(150),
  role: z.enum(["admin", "editor", "viewer"]),
  isActive: z.boolean().default(true),
  createdAt: z.string().datetime(),
});

// 自动推导TypeScript类型 —— 与手动定义的interface完全等价
type User = z.infer<typeof UserSchema>;
// 等价于：
// type User = {
//   id: string;
//   name: string;
//   email: string;
//   age: number;
//   role: "admin" | "editor" | "viewer";
//   isActive: boolean;
//   createdAt: string;
// }

// 字符串验证
z.string()                    // 基础字符串
z.string().min(5)             // 最小长度
z.string().max(100)           // 最大长度
z.string().email()            // 邮箱格式
z.string().url()              // URL格式
z.string().uuid()             // UUID格式
z.string().regex(/^[a-z]+$/)  // 正则匹配
z.string().trim()             // 自动去除首尾空格
z.string().nonempty()         // 非空字符串

// 数字验证
z.number()                    // 基础数字
z.number().int()              // 整数
z.number().positive()         // 正数
z.number().min(0).max(100)    // 范围约束
z.number().multipleOf(0.01)   // 步长约束（适合金额）

// 其他类型
z.boolean()                   // 布尔值
z.date()                      // 日期对象
z.bigint()                    // BigInt
z.null()                      // 仅null
z.undefined()                 // 仅undefined
z.nullable(z.string())        // string | null
z.optional(z.string())        // string | undefined

// 高级类型
z.array(z.string())           // 字符串数组
z.tuple([z.string(), z.number()])  // 元组
z.record(z.string(), z.number())  // Record<string, number>
z.map(z.string(), z.number())     // Map<string, number>
z.set(z.string())             // Set<string>

// 联合类型与判别联合
z.union([z.string(), z.number()])    // string | number
z.literal("admin")                   // 字面量类型
z.discriminatedUnion("type", [       // 判别联合
  z.object({ type: z.literal("text"), content: z.string() }),
  z.object({ type: z.literal("image"), url: z.string().url() }),
]);

// src/middleware/validate.ts
import { Request, Response, NextFunction } from "express";
import { ZodSchema, ZodError } from "zod";

interface ValidationSchemas {
  body?: ZodSchema;
  query?: ZodSchema;
  params?: ZodSchema;
}

export function validate(schemas: ValidationSchemas) {
  return (req: Request, res: Response, next: NextFunction) => {
    try {
      if (schemas.body) {
        req.body = schemas.body.parse(req.body);
      }
      if (schemas.query) {
        req.query = schemas.query.parse(req.query) as any;
      }
      if (schemas.params) {
        req.params = schemas.params.parse(req.params) as any;
      }
      next();
    } catch (error) {
      if (error instanceof ZodError) {
        res.status(400).json({
          success: false,
          error: "请求参数验证失败",
          details: error.errors.map((err) => ({
            field: err.path.join("."),
            message: err.message,
            code: err.code,
          })),
        });
        return;
      }
      next(error);
    }
  };
}

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

export const CreateUserSchema = z.object({
  name: z.string().min(2).max(50),
  email: z.string().email(),
  password: z
    .string()
    .min(8, "密码至少8位")
    .regex(/[A-Z]/, "密码必须包含大写字母")
    .regex(/[0-9]/, "密码必须包含数字")
    .regex(/[^A-Za-z0-9]/, "密码必须包含特殊字符"),
  role: z.enum(["admin", "editor", "viewer"]).default("viewer"),
});

export const UpdateUserSchema = CreateUserSchema.partial().omit({
  password: true,
});

export const QueryUsersSchema = z.object({
  page: z.coerce.number().int().min(1).default(1),
  pageSize: z.coerce.number().int().min(1).max(100).default(20),
  search: z.string().optional(),
  role: z.enum(["admin", "editor", "viewer"]).optional(),
  sortBy: z.enum(["name", "email", "createdAt"]).default("createdAt"),
  sortOrder: z.enum(["asc", "desc"]).default("desc"),
});

export const UserIdParamsSchema = z.object({
  id: z.string().uuid(),
});

// 推导类型

## 高级特性：Refinements与Transforms

### 自定义验证规则（Refinement）

// 验证总金额是否正确
if (Math.abs(data.totalAmount - subtotal) > 0.01) {
  ctx.addIssue({
    code: z.ZodIssueCode.custom,
    message: `总金额计算错误，应为 ${subtotal}`,
    path: ["totalAmount"],

// schemas/api.schema.ts
import { z } from "zod";

// ===== 请求Schema =====
export const CreateArticleSchema = z.object({
  title: z.string().min(5).max(200),
  content: z.string().min(100),
  tags: z.array(z.string()).max(10),
  category: z.enum(["tech", "design", "business"]),
  isDraft: z.boolean().default(false),
});

export const PaginationSchema = z.object({
  page: z.coerce.number().int().min(1).default(1),
  limit: z.coerce.number().int().min(1).max(50).default(20),
});

// ===== 响应Schema =====
export const ArticleSchema = z.object({
  id: z.string().uuid(),
  title: z.string(),
  content: z.string(),
  tags: z.array(z.string()),
  category: z.string(),
  isDraft: z.boolean(),
  authorId: z.string().uuid(),
  createdAt: z.string().datetime(),
  updatedAt: z.string().datetime(),
});

export const PaginatedResponseSchema = z.object({
  data: z.array(ArticleSchema),
  pagination: z.object({
    page: z.number(),
    limit: z.number(),
    total: z.number(),

## 错误处理模式

### 统一错误格式化

### 前端表单验证集成

// src/schemas/__tests__/user.schema.test.ts
import { describe, it, expect } from "vitest";
import { CreateUserSchema, UpdateUserSchema } from "../user.schema";

describe("CreateUserSchema", () => {
  it("应该通过有效的用户数据", () => {
    const validData = {
      name: "张三",
      email: "zhangsan@example.com",
      password: "SecurePass123!",
      role: "viewer" as const,
    };

    const result = CreateUserSchema.safeParse(validData);
    expect(result.success).toBe(true);
  });

  it("应该拒绝过短的姓名", () => {
    const result = CreateUserSchema.safeParse({
      name: "A",
      email: "test@example.com",
      password: "SecurePass123!",
    });

    expect(result.success).toBe(false);
    if (!result.success) {
      expect(result.error.errors[0].path).toContain("name");
    }
  });

  it("应该拒绝无效的邮箱格式", () => {
    const result = CreateUserSchema.safeParse({
      name: "张三",
      email: "not-an-email",
      password: "SecurePass123!",
    });

    expect(result.success).toBe(false);
  });

  it("应该拒绝不满足复杂度要求的密码", () => {
    const weakPasswords = ["short", "nodigits!", "NOLOWERCASE1!", "noupper1!"];

    for (const password of weakPasswords) {
      const result = CreateUserSchema.safeParse({
        name: "张三",
        email: "test@example.com",
        password,

## 实战中的最佳实践

### 1. Schema组织结构

### 2. Schema复用与组合