Breaking changes

В библиотеке Naive UI понятие breaking changes крайне важно для стабильности приложений, особенно при переходе между мажорными версиями. Breaking change — это изменение, которое может сломать существующий код, требуя ручной доработки при обновлении библиотеки. Naive UI придерживается строгой семантической версии (SemVer), поэтому любая версия с увеличением мажорного числа (v1 → v2) потенциально содержит такие изменения.

Основные категории breaking changes

  1. Изменение API компонентов

    • Сигнатуры пропсов: добавление обязательных пропсов или изменение типов существующих приводит к ошибкам компиляции и runtime.
    • Удаление устаревших пропсов: компоненты Naive UI регулярно проходят рефакторинг, и пропсы, которые ранее поддерживались, могут быть удалены в новых мажорных версиях.
    • Переименование методов: методы вроде doSomething() могут быть заменены на performAction(), что потребует исправления вызовов в коде.

  2. Изменения в структуре слотов

    • Некоторые слоты могут быть удалены или переименованы. Например, слот footer в диалоговом компоненте NDialog может быть заменён на bottom, что потребует переработки шаблонов.
    • Изменение контракта слотов: если слот ранее принимал строку или элемент, теперь может требоваться строго объект VNode.

  3. Обновление зависимостей и peerDependencies

    • Naive UI может обновлять версии Vue или других зависимостей, что напрямую влияет на работу компонентов.
    • Устаревшие версии Vue (<3.2) больше не поддерживаются, что требует обновления проекта перед миграцией.

  4. Изменения стилей и CSS-переменных

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

  5. Изменения логики внутренних состояний

    • Поведение компонентов, таких как NSelect, NInput или NTable, может быть переработано: события могут вызываться в другой последовательности или с другими аргументами.
    • Обработка асинхронных операций и реактивность могла быть изменена для оптимизации производительности, что требует внимательной проверки существующего кода.

Стратегии работы с breaking changes

  • Проверка changelog Каждый релиз Naive UI сопровождается подробным changelog с указанием, какие изменения являются breaking.
  • Использование v2.x или v3.x только после тестирования Новые мажорные версии должны тестироваться в отдельной ветке до слияния с основной.
  • Модульная миграция Обновление компонентов поэтапно позволяет выявлять проблемы на ранней стадии. Например, сначала обновляются формы, затем таблицы и модальные окна.
  • Проверка типизации TypeScript TypeScript сильно облегчает выявление breaking changes, особенно при изменениях пропсов и слотов.

Практический пример

В версии Naive UI v2.0.0 пропс size компонента NButton был изменён с типа string | number на строгое перечисление 'small' | 'medium' | 'large'. Старый код:

<NButton size={12}>Нажми</NButton>

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

<NButton size="medium">Нажми</NButton>

Также событие onUpdate:value в NInput было заменено на onUpdateValue, что напрямую ломает существующие обработчики:

// Старый вариант
<NInput v-model:value="text" onUpdate:value="handleUpdate" />

// Новый вариант
<NInput v-model:value="text" @onUpdateVa lue="handleUpdate" />

Рекомендации по миграции

  • Создавать ветку feature/upgrade-naive и фиксировать все изменения.
  • Использовать ESLint и TypeScript для автоматического выявления ошибок.
  • Проверять стили на всех ключевых страницах после обновления версии.
  • Сохранять старую версию библиотеки как резервный вариант до полного завершения миграции.

Breaking changes в Naive UI — это не только вызов, но и возможность оптимизировать кодовую базу, очистить устаревшие компоненты и улучшить типизацию. Правильное планирование миграции снижает риски и делает проект более устойчивым к будущим обновлениям.

Оглавление