Валидация запросов

Валидация запросов в прикладных JavaScript-приложениях рассматривается как слой защиты и нормализации данных, поступающих извне. Библиотека Superstruct реализует декларативный подход, при котором структура данных описывается через композицию примитивов и пользовательских правил, а проверка выполняется через единый механизм.

Ключевая особенность подхода заключается в разделении описания схемы и процесса проверки. Схема представляет собой чистую функцию-структуру, а проверка — детерминированную операцию, возвращающую либо нормализованные данные, либо описание ошибки.

Базовые структурные примитивы

В основе лежит набор базовых валидаторов:

  • string — проверка строковых значений
  • number — числовые значения
  • boolean — логические значения
  • array — массивы
  • object — объекты

Каждый примитив выполняет строгое соответствие типу без неявного приведения. Это обеспечивает предсказуемость поведения при обработке входящих запросов.

import { string, number, boolean } from "superstruct";

Валидация выполняется через функцию validate, возвращающую кортеж результата:

import { validate } from "superstruct";

const [error, value] = validate("hello", string());

Если ошибка отсутствует, error равен undefined, а value содержит проверенные данные.

Композиция структур

Основной механизм построения сложных схем основан на композиции. Объекты описываются через структуру object, где поля задаются вложенными структурами.

import { object, string, number } from "superstruct";

const User = object({
  id: number(),
  name: string(),
  email: string()
});

Такая схема формирует строгий контракт входящего объекта. Любое несоответствие типам приводит к детализированной ошибке.

Массивы комбинируются через array:

import { array, number } from "superstruct";

const Scores = array(number());

Валидация запросов в прикладной архитектуре

При обработке HTTP-запросов входящие данные обычно представлены в виде body, query или params. Использование структур позволяет унифицировать проверку на границе системы.

const CreatePostRequest = object({
  title: string(),
  content: string(),
  authorId: number()
});

Применение схемы к телу запроса:

const [error, data] = validate(req.body, CreatePostRequest);

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

Кастомные структуры и расширение логики

Валидация часто выходит за пределы примитивных типов. Для этого используются пользовательские структуры через refine.

import { refine, string } from "superstruct";

const Email = refine(string(), "Email", (value) => {
  return value.includes("@");
});

Функция-валидатор возвращает булево значение, определяющее допустимость значения.

Для более сложных сценариев применяются структурные композиции с дополнительными проверками:

const PositiveNumber = refine(number(), "PositiveNumber", (value) => {
  return value > 0;
});

Преобразование данных (coercion)

Часто входящие данные приходят в несогласованном формате, например строки вместо чисел. Механизм приведения типов позволяет нормализовать значения до валидации.

import { coerce, number, string } from "superstruct";

const NumberFromString = coerce(number(), string(), (value) => Number(value));

В результате строка "42" преобразуется в число 42 перед проверкой.

Обработка ошибок

Ошибки валидации в Superstruct представляют собой структурированные объекты, содержащие путь к полю и описание нарушения.

import { validate } from "superstruct";

const [error] = validate({ id: "abc" }, object({ id: number() }));

Типичная ошибка включает:

  • путь до некорректного поля
  • ожидаемый тип
  • фактическое значение

Это позволяет строить детализированные сообщения для API-ответов.

Глубокая валидация вложенных структур

Сложные запросы часто содержат вложенные объекты и массивы. Валидация распространяется рекурсивно.

const Comment = object({
  text: string(),
  author: object({
    id: number(),
    name: string()
  })
});

Ошибки внутри вложенных структур сохраняют полный путь, например:

author.id: expected number, received string

Условные структуры и optional-поля

Часть данных в запросах может быть необязательной. Для этого используется optional.

import { object, string, optional } from "superstruct";

const Profile = object({
  bio: optional(string())
});

Отсутствие поля не считается ошибкой, но при наличии оно обязано соответствовать типу.

Союзы типов и альтернативные схемы

Некоторые поля могут принимать разные типы. Для этого используется union.

import { union, string, number } from "superstruct";

const Id = union([string(), number()]);

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

Пересечение структур

При объединении требований используется intersection.

import { intersection, object, string } from "superstruct";

const A = object({ name: string() });
const B = object({ role: string() });

const User = intersection([A, B]);

Результирующая структура требует выполнения всех условий одновременно.

Использование в middleware-архитектуре

В серверных приложениях валидация часто выносится в промежуточный слой. Это позволяет централизовать проверку входящих данных до попадания в обработчики маршрутов.

Логика middleware сводится к:

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

Такой подход снижает дублирование кода и уменьшает вероятность ошибок в бизнес-логике.

Производительность и детерминизм

Валидация через Superstruct строится на синхронных функциях без скрытых побочных эффектов. Это обеспечивает:

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

За счёт этого библиотека подходит для высоконагруженных API, где валидация выполняется на каждом запросе.

Структурирование схем в крупных проектах

При масштабировании системы схемы выделяются в отдельный слой. Обычно используется модульная организация:

  • схемы запросов
  • схемы ответов
  • общие примитивы
  • переиспользуемые структуры

Это снижает связность компонентов и упрощает сопровождение контрактов между клиентом и сервером.

Оглавление