Логирование процесса валидации

Валидация данных в Zod строится вокруг декларативного описания схем и последующего выполнения проверки входных значений. Несмотря на то, что сама библиотека ориентирована на предсказуемое поведение и строгую типизацию, практическое использование в реальных приложениях требует прозрачности происходящего внутри процесса проверки. Логирование в данном контексте становится инструментом наблюдаемости, позволяющим фиксировать входные данные, этапы трансформации и итоговое состояние результата.

Особое значение имеет тот факт, что Zod не предоставляет встроенной системы логирования. Это создаёт гибкость: контроль над тем, что и как фиксируется, полностью переносится на уровень приложения.

safeParse как точка контроля потока выполнения

Основным механизмом, через который обычно строится логирование, является метод safeParse. В отличие от parse, он не выбрасывает исключения, а возвращает структурированный результат.

const result = schema.safeParse(data);

Такой подход позволяет встроить логирование до и после выполнения валидации без необходимости обработки исключений:

  • входные данные фиксируются до проверки
  • результат анализируется после выполнения
  • ошибки доступны в структурированном виде

При использовании parse логирование становится менее предсказуемым, так как поток управления прерывается исключением ZodError.

Структура ZodError и извлечение диагностической информации

Объект ошибки ZodError содержит массив issues, который является основным источником информации для логирования.

Каждый элемент issues включает:

  • path — путь до некорректного значения
  • message — текст ошибки
  • code — тип ошибки
  • expected и received (в зависимости от контекста)

Пример анализа:

if (!result.success) {
  console.log(result.error.issues);
}

Структура path позволяет строить иерархическое представление проблем, особенно в случае вложенных объектов и массивов. Это критично для сложных схем.

Логирование входных данных перед валидацией

Фиксация входного состояния позволяет отслеживать источник некорректных данных. В контексте Zod это особенно важно, так как одна и та же схема может использоваться в разных местах приложения.

console.log("INPUT:", JSON.stringify(data));
const result = schema.safeParse(data);

При работе с чувствительными данными обычно применяется частичное логирование или маскирование полей, чтобы избежать утечек информации в логах.

Логирование результата валидации

После выполнения safeParse фиксируется итоговое состояние:

if (result.success) {
  console.log("VALID DATA:", result.data);
} else {
  console.log("VALIDATION FAILED:", result.error.issues);
}

Разделение на успешный и неуспешный сценарий позволяет строить чёткую диагностическую картину поведения системы.

Детализация ошибок через path-структуру

Одним из ключевых преимуществ Zod является возможность точно определить место нарушения схемы. Поле path представляет собой массив, отражающий вложенность:

[
  "user",
  "address",
  "zipCode"
]

При логировании такие пути часто преобразуются в строковое представление:

const pathString = issue.path.join(".");
console.log(`${pathString}: ${issue.message}`);

Это позволяет быстро локализовать проблему без анализа всего объекта целиком.

Логирование при использовании transform и refine

Методы transform и refine добавляют дополнительный слой обработки, который влияет на итоговый результат валидации.

const schema = z.string().transform((val) => val.trim());

Логирование на этом уровне включает фиксацию промежуточных значений:

  • исходное значение
  • преобразованное значение
  • результат проверки после transform

Для refine логирование становится особенно важным, поскольку ошибки могут быть пользовательскими:

.refine((val) => val.length > 8, {
  message: "Слишком короткое значение"
});

В таких случаях полезно фиксировать как входные данные, так и результат условия.

Расширение сообщений ошибок через errorMap

Zod позволяет переопределять сообщения ошибок через errorMap, что напрямую влияет на логирование диагностических сообщений.

const schema = z.string({
  errorMap: (issue, ctx) => {
    return { message: `Ошибка: ${issue.code}` };
  }
});

При логировании важно учитывать, что итоговое сообщение может отличаться от исходного issue.message, и сохранять оба варианта для диагностики.

Композиция схем и агрегация логов

При построении сложных схем из вложенных частей логирование должно учитывать композиционную природу Zod.

const addressSchema = z.object({
  city: z.string(),
  zip: z.string()
});

const userSchema = z.object({
  name: z.string(),
  address: addressSchema
});

Ошибки во вложенных схемах агрегируются в общий ZodError, и логирование должно сохранять контекст вложенности. Это достигается анализом path и группировкой ошибок по уровням.

Логирование в middleware-архитектурах

В серверных приложениях Zod часто используется как слой валидации входящих запросов. В таких случаях логирование интегрируется в middleware:

  • запрос до валидации
  • результат проверки
  • ошибки валидации
  • контекст запроса (метод, маршрут, заголовки)
function validate(schema) {
  return (req, res, next) => {
    const result = schema.safeParse(req.body);

    if (!result.success) {
      console.log("VALIDATION ERROR", result.error.issues);
      return res.status(400).send(result.error.issues);
    }

    req.body = result.data;
    next();
  };
}

Такой подход связывает логику Zod с жизненным циклом HTTP-запроса.

Структурированное логирование и формат JSON

Для систем наблюдаемости предпочтительно использовать структурированный формат логов:

console.log(JSON.stringify({
  event: "validation_failed",
  issues: result.error.issues,
  timestamp: Date.now()
}));

Это упрощает интеграцию с системами анализа логов и позволяет выполнять агрегацию ошибок по типам, путям и кодам.

Производительность и объём логирования

Избыточное логирование при массовой валидации может влиять на производительность. Особенно это заметно при:

  • обработке больших массивов данных
  • глубоко вложенных схемах
  • частых вызовах safeParse

Практика показывает, что выборочное логирование (например, только ошибок или только определённых путей) снижает нагрузку без потери диагностической ценности.

Контроль чувствительных данных в логах

При работе с пользовательскими данными логирование должно учитывать необходимость исключения или маскирования полей. В контексте Zod это часто касается:

  • паролей
  • токенов
  • персональных данных

Логирование data после успешной валидации может потребовать предварительной фильтрации структуры, особенно если схема используется в разных слоях приложения.

Связывание логов с типами ошибок Zod

Поле code внутри issue позволяет классифицировать ошибки:

  • invalid_type
  • too_small
  • too_big
  • invalid_string
  • и другие

Использование этого поля в логах позволяет строить статистику по типам нарушений схемы, что полезно для анализа качества входящих данных и корректировки API-контрактов.

Оглавление