Установка и первый запуск

Библиотека Ajv распространяется через npm и предназначена для использования в Node.js и браузерных сборках. Установка выполняется стандартными средствами менеджеров пакетов.

Установка через npm

npm install ajv

Установка через yarn

yarn add ajv

Установка через pnpm

pnpm add ajv

После установки пакет становится доступным для импорта в проекте, при этом поддерживаются как CommonJS, так и ES Modules в зависимости от конфигурации среды.

Подключение библиотеки

CommonJS (Node.js)

const Ajv = require("ajv");

ES Modules

import Ajv from "ajv";

В современных проектах предпочтительным считается ESM-формат, особенно при использовании сборщиков вроде Vite, Rollup или Webpack с соответствующей конфигурацией.

Создание экземпляра валидатора

Основная точка входа — создание экземпляра Ajv. Именно через него выполняется компиляция схем и проверка данных.

import Ajv from "ajv";

const ajv = new Ajv();

Экземпляр может быть настроен через параметры конструктора. Наиболее часто используемые опции:

  • allErrors — сбор всех ошибок, а не остановка на первой
  • strict — включение строгого режима проверки схем
  • coerceTypes — автоматическое приведение типов
  • removeAdditional — удаление лишних свойств из объекта

Пример конфигурации:

const ajv = new Ajv({
  allErrors: true,
  coerceTypes: true,
  removeAdditional: true
});

Первая схема и валидация

Основная концепция работы основана на JSON Schema. Сначала определяется схема, затем компилируется функция валидации.

Пример схемы

const schema = {
  type: "object",
  properties: {
    name: { type: "string" },
    age: { type: "number" }
  },
  required: ["name", "age"],
  additionalProperties: false
};

Компиляция схемы

const validate = ajv.compile(schema);

Проверка данных

const data = {
  name: "Ivan",
  age: 30
};

const valid = validate(data);

if (!valid) {
  console.log(validate.errors);
}

Метод compile преобразует JSON Schema в оптимизированную функцию проверки, что обеспечивает высокую производительность при повторных вызовах.

Структура результата валидации

После вызова функции проверки доступны два ключевых элемента:

  • boolean результат выполнения
  • массив errors при наличии ошибок

Пример структуры ошибки:

[
  {
    "instancePath": "/age",
    "message": "must be number",
    "keyword": "type",
    "params": {
      "type": "number"
    }
  }
]

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

Повторное использование схем

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

const validate = ajv.compile(schema);

validate({ name: "Anna", age: 25 });
validate({ name: "John", age: 40 });

Такой подход исключает необходимость повторного парсинга JSON Schema.

Работа с несколькими схемами

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

const schema = {
  $id: "userSchema",
  type: "object",
  properties: {
    id: { type: "string" }
  },
  required: ["id"]
};

ajv.addSchema(schema);

const validate = ajv.getSchema("userSchema");

Это позволяет централизованно управлять схемами и использовать их в разных частях приложения.

Поддержка форматов данных

Ajv позволяет расширять стандартную валидацию через форматы:

const schema = {
  type: "string",
  format: "email"
};

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

import addFormats from "ajv-formats";

addFormats(ajv);

После этого становятся доступны проверки email, URI, date-time и другие стандартные форматы.

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

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

Пример обработки:

if (!validate(data)) {
  for (const err of validate.errors) {
    console.log(err.instancePath, err.message);
  }
}

Дополнительно можно включить строгий режим, который помогает выявлять некорректные схемы на этапе разработки.

const ajv = new Ajv({ strict: true });

Оптимизация первой загрузки

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

const validators = {
  user: ajv.compile(userSchema),
  product: ajv.compile(productSchema)
};

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

Использование в браузере

Ajv может использоваться и в браузере при сборке через Webpack или Vite:

import Ajv from "ajv";

const ajv = new Ajv();

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

Особенности поведения в строгом режиме

Строгий режим влияет на обработку схем:

  • предупреждает о неизвестных ключах
  • запрещает неоднозначные конструкции
  • помогает выявлять ошибки на этапе разработки
const ajv = new Ajv({ strict: true });

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

Оглавление