В библиотеке Vest обратная совместимость строится вокруг строгого соблюдения принципов семантического версионирования. Любое изменение API оценивается не только с точки зрения функциональности, но и с точки зрения влияния на существующие проекты, уже использующие библиотеку в продакшене.
Мажорные версии используются исключительно для изменений, которые ломают существующее поведение. Это включает переработку API, удаление методов или изменение логики валидации, которая может привести к другим результатам проверки без изменения кода пользователя.
Минорные версии допускают расширение функциональности при сохранении прежнего поведения. Например, добавление новых валидаторов или расширение возможностей существующих функций без изменения их контрактов.
Патч-версии ограничиваются исправлением ошибок, оптимизацией и внутренними улучшениями, не влияющими на публичное поведение API.
Ключевой принцип заключается в том, что любой код, корректно работающий на предыдущей минорной версии, должен продолжать работать без изменений после обновления на новую минорную или патч-версию.
Публичный API Vest разделяется на стабильное ядро и внутренние механизмы. Обратная совместимость гарантируется только для публичной части, которая включает:
Внутренние утилиты и вспомогательные функции могут изменяться без сохранения обратной совместимости. Такая сегрегация позволяет развивать библиотеку, не ограничивая архитектурные изменения.
Особое внимание уделяется структуре результатов валидации. Формат объекта результата считается контрактом, и любые изменения в нём требуют либо полной совместимости, либо введения нового поля без удаления старых.
Перед удалением любой функциональности вводится этап устаревания. Устаревшие API сохраняются в библиотеке минимум на несколько минорных релизов, сопровождаясь предупреждениями.
Механизм устаревания реализуется через:
Критически важно, что устаревший функционал продолжает работать идентично прежнему поведению, даже если он помечен как deprecated. Это снижает риск поломки существующих приложений при обновлении зависимостей.
Одной из сложных областей является совместимость валидаторов. В Vest валидаторы часто представляют собой функции, возвращающие результат проверки или промис.
Проблемы обратной совместимости возникают в следующих случаях:
Для предотвращения нарушений контрактов используется правило неизменности интерфейса валидатора: функция всегда должна принимать одинаковые аргументы и возвращать совместимый тип результата.
При расширении функциональности добавляются новые валидаторы, а не модифицируются существующие.
Vest использует декларативное описание правил, где тесты объединяются в логические структуры. Обратная совместимость здесь обеспечивается за счёт неизменности поведения композиции.
Основные гарантии:
Любые изменения в движке исполнения тестов требуют отдельной версии, так как даже небольшие изменения порядка могут привести к другим результатам в сложных схемах валидации.
Vest используется как в браузере, так и в Node.js, поэтому важной частью обратной совместимости является поддержка различных JavaScript-окружений.
Поддерживаются следующие принципы:
Если вводится зависимость от новых возможностей языка (например, новых методов массива или Promise-расширений), обязательно предусматриваются полифиллы или альтернативные реализации для старых окружений.
Хотя JavaScript не является строго типизированным языком, Vest фактически опирается на контрактную модель данных. Нарушение этих контрактов приводит к поломке обратной совместимости.
Основные требования:
При необходимости изменения структуры вводится параллельная версия API, а старая структура сохраняется для существующего кода.
Асинхронная валидация является одной из наиболее чувствительных зон с точки зрения обратной совместимости. Любое изменение поведения Promise-цепочек может привести к изменению логики проверки.
Гарантируется:
Если вводятся оптимизации асинхронного выполнения, они не должны влиять на наблюдаемое поведение результатов.
Расширение функциональности в Vest реализуется через добавление новых сущностей, а не изменение старых. Это позволяет сохранять стабильность интерфейсов.
Используются следующие подходы:
Каждое новое расширение проходит проверку на потенциальное влияние на существующие сценарии использования.
Обратная совместимость поддерживается не только архитектурными решениями, но и системой тестирования. Для Vest характерно наличие регрессионных тестов, фиксирующих поведение API.
Основные типы тестов:
Регрессионный набор тестов рассматривается как часть публичного контракта: любое изменение, ломающее тесты, считается нарушением обратной совместимости.
Когда изменение невозможно реализовать без нарушения совместимости, применяется многоэтапный процесс:
Такой подход минимизирует риск внезапных поломок в проектах, использующих библиотеку в продакшене.
Схемы валидации часто используются повторно между версиями, поэтому их совместимость является отдельной областью ответственности.
Гарантируется:
Изменения в интерпретации схем допускаются только при явном переходе на новую мажорную версию, где поведение документировано как изменённое.