TypeScript Academy · 课时

parse 与 safeParse

Q: 「parse 与 safeParse」这节课中我会学到什么？

平稳地处理验证成功和失败的情况。 你通过在浏览器中直接运行的动手代码来练习 TypeScript Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

平稳地处理验证成功和失败的情况。

parse 与 safeParse 是 CoddyKit 上的免费 TypeScript Academy 课时。这是第 3 节课，共 4 节。你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。这是 TypeScript Academy 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 TypeScript Academy 课程共包含 4 节课。

两种验证方式

Zod 提供两种验证方法：无效数据会导致 parse 抛出错误，而 safeParse 会返回一个结果对象。

import { z } from "zod";
const schema = z.string();
// schema.parse(x) throws on failure
// schema.safeParse(x) returns { success, ... }

parse 在数据无效时抛出错误

成功时，parse 返回经过验证的值；失败时抛出 ZodError。当无效数据确实属于异常情况时，这种方式非常适合。

import { z } from "zod";
const schema = z.number();
const ok = schema.parse(42); // 42
// schema.parse("nope"); // throws ZodError

捕获 parse 错误

将 parse 放在 try/catch 中，以处理抛出的错误，并检查错误详情来了解失败原因。

import { z } from "zod";
const schema = z.number();
try {
  schema.parse("nope");
} catch (err) {
  if (err instanceof z.ZodError) {
    console.log("Invalid:", err.issues.length);
  }
}

safeParse 返回结果

safeParse 永远不会抛出错误。它会返回一个对象：成功时包含 success: true 和 data，失败时包含 success: false 和 error。

import { z } from "zod";
const schema = z.number();
const result = schema.safeParse("nope");
// result is { success: false, error: ZodError }

缩小结果类型范围

该结果是基于 success 的可辨识联合类型。检查它后，类型会缩小为包含 data 或 error 的其中一种。

import { z } from "zod";
const schema = z.object({ id: z.number() });
const result = schema.safeParse({ id: 1 });
if (result.success) {
  console.log(result.data.id); // typed
} else {
  console.log(result.error.issues);
}

何时使用 parse

当无效输入表示程序错误，或应当中止操作时，请使用 parse，例如在启动时读取必需的 config。

import { z } from "zod";
const configSchema = z.object({ port: z.number() });
const config = configSchema.parse({ port: 8080 });
// Fail fast if config is wrong.

何时使用 safeParse

当无效输入属于预期情况，并且您希望优雅地处理它时，请使用 safeParse，例如验证用户提交的表单。

import { z } from "zod";
const formSchema = z.object({ email: z.string() });
const r = formSchema.safeParse({ email: 123 });
if (!r.success) {
  // Show a friendly validation message
}

读取 ZodError 问题

ZodError 包含一个 issues 数组，用于描述每个问题：路径、消息和错误代码。

import { z } from "zod";
const schema = z.object({ age: z.number() });
const r = schema.safeParse({ age: "x" });
if (!r.success) {
  for (const issue of r.error.issues) {
    console.log(issue.path, issue.message);
  }
}

两者都返回推断出的类型

成功时，这两种方法都会返回一个具有 z.infer<typeof schema> 类型的已验证值，因此后续代码可以获得完整的类型信息。

import { z } from "zod";
const userSchema = z.object({ name: z.string() });
type User = z.infer<typeof userSchema>;
const u: User = userSchema.parse({ name: "Ada" });
console.log(u.name);

选择合适的方法

经验法则是：对于可信数据或关键流程，如果失败就应停止执行，请使用 parse；对于必须在不崩溃的情况下处理的不可信输入，请使用 safeParse。

import { z } from "zod";
const schema = z.string();
// Critical: schema.parse(value)
// User-facing: schema.safeParse(value)

组合两种风格

一种常见模式是将 safeParse 包装在辅助函数中，让它返回类型明确的数据或格式化后的错误，从而兼具两种方法的易用性。

import { z } from "zod";
function validate<T extends z.ZodType>(schema: T, value: unknown) {
  const r = schema.safeParse(value);
  return r.success ? { ok: true, data: r.data } : { ok: false, error: r.error };
}
// Reusable, no throwing.

快速检查：parse 与 safeParse

测试您对 parse 和 safeParse 区别的理解。

回顾：parse 与 safeParse

您了解了无效数据会使 parse 抛出错误，而 safeParse 会返回包含 success/error 的结果；您还了解了各自的使用时机，以及如何读取 ZodError 中的问题。

import { z } from "zod";
const schema = z.object({ id: z.number() });
const r = schema.safeParse({ id: 1 });
if (r.success) console.log(r.data.id);

常见问题解答

「parse 与 safeParse」课时是免费的吗？

是的 — 「parse 与 safeParse」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 TypeScript Academy 课程的其余内容，请升级到 CoddyKit PRO。 TypeScript Academy 课程共包含 4 节课。

「parse 与 safeParse」这节课中我会学到什么？

平稳地处理验证成功和失败的情况。你通过在浏览器中直接运行的动手代码来练习 TypeScript Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 TypeScript Academy 需要有经验吗？

无需任何先前经验。CoddyKit 上的 TypeScript Academy 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。这是第 3 节课，共 4 节。

「parse 与 safeParse」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 TypeScript Academy 课中编写并运行代码吗？

能。每节 TypeScript Academy 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

← 返回 TypeScript Academy