TypeScript Academy · Урок

parse и safeParse

Корректно обрабатывайте успешную и неуспешную проверку

«parse и safeParse» — бесплатный урок TypeScript Academy на CoddyKit. Это урок 3 из 4. Ты можешь прочитать весь урок бесплатно ниже — а потом практиковать его прямо в браузере с встроенным редактором кода и ИИ-репетитором 24/7. Это часть пути обучения 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» бесплатно доступен здесь в веб-версии. Чтобы практиковать его интерактивно (встроенный редактор кода и ИИ-репетитор 24/7) и разблокировать остальной курс TypeScript Academy, подпишись на CoddyKit PRO. Курс TypeScript Academy содержит 4 уроков всего.

Чему я научусь в уроке «parse и safeParse»?

Корректно обрабатывайте успешную и неуспешную проверку Ты практикуешь TypeScript Academy с помощью реального кода, который запускаешь прямо в браузере, и ИИ-репетитор 24/7 отвечает на твои вопросы во время урока.

Нужен ли мне опыт, чтобы начать TypeScript Academy?

Предыдущий опыт не требуется. TypeScript Academy на CoddyKit структурирован для всех уровней — от новичков до продвинутых, поэтому ты можешь начать отсюда или с самого начала и учиться в своем темпе. Это урок 3 из 4.

Сколько времени занимает урок «parse и safeParse»?

Большинство уроков CoddyKit занимают около 5–10 минут. Каждый из них компактный и интерактивный, поэтому ты постоянно делаешь прогресс и продолжаешь с того же места в веб-версии и приложении.

Можно ли писать и запускать код в этом уроке TypeScript Academy?

Да. Каждый урок TypeScript Academy включает встроенный редактор кода, поэтому ты пишешь и запускаешь реальный код прямо в браузере и получаешь моментальную обратную связь от AI — локальная установка не требуется.

Все уроки этого курса

← Назад к TypeScript Academy