Zod, Valibot 等运行时验证库与 TypeScript 的集成

运行时保镖：Zod、Valibot 如何与 TypeScript 联手，让 Bug 无处遁形

各位观众老爷们，大家好！今天我们要聊点刺激的，聊聊如何在 JavaScript 的世界里，让我们的代码更安全、更可靠，就像给它请了几个专业的“运行时保镖”。这些保镖就是 Zod、Valibot 等运行时验证库，而我们的代码本身，则是用 TypeScript 这件“高级定制战甲”包裹的。

想象一下，你辛辛苦苦用 TypeScript 编写了一个接口，定义了某个数据结构应该长什么样。编译器也尽职尽责地帮你检查代码，确保类型安全。你心想：“这下总没问题了吧？” 结果，发布到线上，用户输入了一些奇奇怪怪的数据，你的代码直接崩溃，留下你一个人在风中凌乱。 😭

为什么会这样？因为 TypeScript 只是编译时的类型检查，它就像一个严格的考官，只在考试的时候盯着你。一旦代码运行起来，离开了编译器的保护，就进入了狂野的 JavaScript 世界。任何数据都可能从外部涌入，你的精心设计的类型定义，瞬间变成了一张废纸。

所以，我们需要“运行时保镖”，在代码真正运行的时候，继续站岗放哨，检查数据的合法性。Zod、Valibot 就是这些“保镖”中的佼佼者。

今天，我们就来聊聊：

1. TypeScript 的“甜美谎言”：编译时类型检查的局限性。
2. 运行时验证的必要性：为什么我们需要“运行时保镖”。
3. Zod、Valibot：两位“保镖”的闪亮登场。
4. 实战演练：Zod 与 TypeScript 的完美结合。
5. Valibot：轻量级选手的实力不容小觑。
6. 性能考量：选择合适的“保镖”。
7. 总结：让类型安全贯穿始终。

1. TypeScript 的“甜美谎言”：编译时类型检查的局限性

TypeScript 就像一个严格的门卫，只允许符合特定类型的人进入你的代码城堡。比如，你定义了一个 User 接口：

interface User {
  id: number;
  name: string;
  email: string;
  age?: number; // 可选属性
}

你信心满满地认为，只有符合这个接口的数据才能进入你的代码。但是，现实总是残酷的。以下情况，TypeScript 无法保证类型安全：

• 外部数据源： 从 API 接口、数据库、用户输入等地方获取的数据，TypeScript 无从得知其类型是否正确。
• JavaScript 动态性： JavaScript 允许你随意修改对象的属性，TypeScript 无法阻止这种行为。
• 类型擦除： TypeScript 在编译成 JavaScript 时，类型信息会被擦除。这意味着在运行时，JavaScript 根本不知道你定义的 User 接口。

举个例子，假设你从 API 接口获取用户数据：

async function fetchUser(): Promise<User> {
  const response = await fetch('/api/user');
  const data = await response.json(); // data 的类型是 any

  //  TypeScript 认为 data 是 User 类型，但实际上...
  return data as User; // 强制类型转换，这是个危险信号！
}

虽然你使用了 as User 强制类型转换，告诉 TypeScript data 是 User 类型，但如果 API 返回的数据不符合 User 接口，你的代码就会在运行时崩溃。 💥

这就是 TypeScript 的“甜美谎言”：它能保证编译时的类型安全，但无法阻止运行时发生的类型错误。

2. 运行时验证的必要性：为什么我们需要“运行时保镖”

为了弥补 TypeScript 的不足，我们需要“运行时保镖”，在代码真正运行的时候，对数据进行验证，确保其符合我们定义的类型。

运行时验证可以：

• 防止运行时错误： 避免因类型错误导致的崩溃。
• 提高代码健壮性： 使代码能够处理各种各样的输入，而不会轻易崩溃。
• 改善用户体验： 及时发现错误，并给出友好的提示，而不是让用户看到一片空白。
• 增强安全性： 防止恶意用户通过构造恶意数据来攻击你的系统。

简而言之，运行时验证就像给你的代码加了一层额外的保护，让它更加安全、可靠。

3. Zod、Valibot：两位“保镖”的闪亮登场

Zod 和 Valibot 都是强大的运行时验证库，它们可以帮助我们轻松地定义数据模式，并验证数据的合法性。

Zod:

• 功能强大： 支持各种数据类型、复杂的验证规则和自定义验证器。
• 类型推断： 可以从 Zod Schema 中自动推断 TypeScript 类型，减少代码冗余。
• 易于使用： API 设计简洁明了，学习曲线平缓。
• 生态完善： 拥有庞大的社区支持和丰富的插件生态。

Valibot:

• 轻量级： 体积小巧，性能出色，非常适合对性能有要求的场景。
• 函数式 API： 使用函数式编程风格，代码更加简洁、易于组合。
• 类型安全： 与 TypeScript 完美集成，提供强大的类型推断能力。
• 专注于验证： 专注于数据验证，没有额外的功能负担。

我们可以用一个表格来对比一下 Zod 和 Valibot：

特性	Zod	Valibot
体积	较大	较小
API 风格	面向对象式	函数式
功能	丰富，支持自定义验证器和转换器	专注于验证，功能较少
类型推断	强大，能从 Schema 中推断出 TypeScript 类型	强大，能从 Schema 中推断出 TypeScript 类型
性能	良好	优秀
学习曲线	平缓	稍陡峭
社区支持	庞大	活跃

简单来说，如果你需要一个功能强大、生态完善的验证库，Zod 是一个不错的选择。如果你更看重性能和体积，Valibot 可能会更适合你。

4. 实战演练：Zod 与 TypeScript 的完美结合

接下来，我们通过一个例子来演示如何使用 Zod 与 TypeScript 结合，实现运行时验证。

假设我们需要验证一个 Article 对象，它包含以下属性：

• id: number，文章 ID
• title: string，文章标题，长度在 5 到 100 个字符之间
• content: string，文章内容，不能为空
• published: boolean，是否已发布
• createdAt: Date，创建时间

首先，我们使用 Zod 定义一个 Article Schema：

import { z } from 'zod';

const ArticleSchema = z.object({
  id: z.number(),
  title: z.string().min(5).max(100),
  content: z.string().min(1),
  published: z.boolean(),
  createdAt: z.date(),
});

// 从 Zod Schema 中推断 TypeScript 类型
type Article = z.infer<typeof ArticleSchema>;

注意：z.infer<typeof ArticleSchema> 可以从 Zod Schema 中自动推断出 Article 类型，这样我们就不用手动定义 Article 接口了，减少了代码冗余，简直不要太爽！ 🎉

接下来，我们可以使用 ArticleSchema.parse() 方法来验证数据：

const articleData = {
  id: 123,
  title: 'My Awesome Article',
  content: 'This is the content of my article.',
  published: true,
  createdAt: new Date(),
};

try {
  const article = ArticleSchema.parse(articleData);
  console.log('Article is valid:', article);
} catch (error: any) {
  console.error('Article is invalid:', error.errors);
}

如果 articleData 符合 ArticleSchema 的定义，ArticleSchema.parse() 方法会返回验证后的 article 对象。如果 articleData 不符合 ArticleSchema 的定义，ArticleSchema.parse() 方法会抛出一个错误，其中包含详细的错误信息。

例如，如果我们将 title 的长度改为 3 个字符：

const articleData = {
  id: 123,
  title: 'My ',  // 长度小于 5
  content: 'This is the content of my article.',
  published: true,
  createdAt: new Date(),
};

运行代码后，会输出以下错误信息：

Article is invalid: [
  {
    "code": "too_small",
    "minimum": 5,
    "type": "string",
    "inclusive": true,
    "message": "String must contain at least 5 character(s)",
    "path": [
      "title"
    ]
  }
]

Zod 的错误信息非常详细，可以帮助我们快速定位问题。

结合 API 请求:

现在，我们将这个验证应用到 API 请求中：

async function createArticle(data: any): Promise<Article> {
  try {
    const articleData = ArticleSchema.parse(data); // 验证数据
    //  发送 API 请求，创建文章
    const response = await fetch('/api/articles', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(articleData),
    });

    if (!response.ok) {
      throw new Error('Failed to create article');
    }

    const article = await response.json();
    return article;
  } catch (error: any) {
    //  处理验证错误或 API 请求错误
    console.error('Error creating article:', error);
    throw error; //  将错误抛出，让调用者处理
  }
}

在这个例子中，我们首先使用 ArticleSchema.parse() 方法验证从 API 请求中获取的数据。如果数据验证失败，我们会抛出一个错误，让调用者处理。如果数据验证成功，我们会发送 API 请求，创建文章。

这样，我们就实现了运行时验证，确保只有合法的数据才能进入我们的代码，从而避免了运行时错误。

5. Valibot：轻量级选手的实力不容小觑

Valibot 虽然体积小巧，但功能同样强大。它使用函数式 API，代码更加简洁、易于组合。

我们用 Valibot 重新定义 Article Schema：

import { object, string, number, boolean, date, minLength, maxLength } from 'valibot';

const ArticleSchema = object({
  id: number(),
  title: string([minLength(5), maxLength(100)]),
  content: string(),
  published: boolean(),
  createdAt: date(),
});

// 从 Valibot Schema 中推断 TypeScript 类型
type Article = Output<typeof ArticleSchema>;

注意：Output<typeof ArticleSchema> 可以从 Valibot Schema 中自动推断出 Article 类型。

接下来，我们可以使用 safeParse() 方法来验证数据：

import { safeParse } from 'valibot';

const articleData = {
  id: 123,
  title: 'My Awesome Article',
  content: 'This is the content of my article.',
  published: true,
  createdAt: new Date(),
};

const result = safeParse(ArticleSchema, articleData);

if (result.success) {
  console.log('Article is valid:', result.output);
} else {
  console.error('Article is invalid:', result.error);
}

Valibot 的 safeParse() 方法不会抛出错误，而是返回一个包含 success 属性的结果对象。如果 success 为 true，表示数据验证成功，output 属性包含验证后的数据。如果 success 为 false，表示数据验证失败，error 属性包含详细的错误信息。

Valibot 的错误信息也比较详细，可以帮助我们快速定位问题。

Valibot 的优势:

• 性能： Valibot 的性能非常出色，尤其是在验证复杂的数据结构时。
• 体积： Valibot 的体积非常小巧，可以减少项目的打包体积。
• 函数式 API： Valibot 使用函数式 API，代码更加简洁、易于组合。

6. 性能考量：选择合适的“保镖”

在选择运行时验证库时，性能是一个重要的考量因素。不同的验证库性能不同，选择合适的验证库可以提高代码的运行效率。

一般来说，Valibot 的性能比 Zod 更好，尤其是在验证复杂的数据结构时。但是，Zod 的生态更加完善，拥有更多的插件和工具。

因此，在选择运行时验证库时，我们需要根据实际情况进行权衡。如果对性能有较高的要求，可以选择 Valibot。如果更看重生态和功能，可以选择 Zod。

一些优化建议:

• 避免过度验证： 只验证必要的数据，避免对所有数据都进行验证。
• 使用缓存： 将验证结果缓存起来，避免重复验证。
• 异步验证： 将验证操作放在异步任务中执行，避免阻塞主线程。

7. 总结：让类型安全贯穿始终

TypeScript 提供了编译时的类型检查，可以帮助我们发现代码中的类型错误。但是，TypeScript 无法保证运行时的类型安全。

为了弥补 TypeScript 的不足，我们需要使用运行时验证库，例如 Zod 和 Valibot。这些库可以帮助我们轻松地定义数据模式，并验证数据的合法性。

通过将 TypeScript 和运行时验证库结合起来，我们可以实现类型安全贯穿始终，从而提高代码的安全性、可靠性和健壮性。

最后，总结一下今天的核心要点：

• TypeScript 的类型检查只是编译时的，无法保证运行时的类型安全。
• 运行时验证是必要的，可以防止运行时错误，提高代码健壮性。
• Zod 和 Valibot 都是强大的运行时验证库，各有优缺点。
• 选择合适的验证库，可以提高代码的运行效率。
• 将 TypeScript 和运行时验证库结合起来，可以实现类型安全贯穿始终。

希望今天的分享能够帮助大家更好地理解 TypeScript 和运行时验证，并在实际项目中应用这些技术，写出更加安全、可靠的代码。

感谢大家的观看！下次再见！ 👋