План миграции

Инвентаризация текущего использования библиотеки

Первым этапом формируется полный перечень точек интеграции AutoNumeric в кодовой базе. Фиксируются все места инициализации инстансов, прямые вызовы API, а также взаимодействие через DOM-атрибуты и события.

Особое внимание уделяется следующим аспектам:

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

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

Анализ версии и совместимости API

Следующий шаг связан с определением текущей версии AutoNumeric и целевой версии миграции. На практике чаще всего встречаются переходы между:

  • legacy-ветками (1.x / 2.x);
  • промежуточными версиями (3.x);
  • современными API (4.x).

Ключевые зоны несовместимости:

  • изменение структуры конфигурационных объектов;
  • переработка методов управления значениями;
  • различия в обработке событий ввода;
  • изменение поведения форматирования при blur/focus;
  • различия в работе с нативными input-элементами.

Формируется матрица соответствий API, фиксирующая: старый метод → новый метод → стратегия замены.

Построение карты конфигураций

Конфигурации AutoNumeric часто оказываются дублированными и разрозненными. Для миграции требуется их унификация.

Типовой подход включает:

  • выделение базовой конфигурации;
  • выделение расширений под конкретные кейсы;
  • устранение дублирующих параметров;
  • нормализация форматов чисел (десятичный разделитель, группировка, валютные символы).

Пример унифицированной структуры:

const baseConfig = {
  digitGroupSeparator: " ",
  decimalCharacter: ",",
  decimalPlaces: 2,
  currencySymbol: "₸",
  currencySymbolPlacement: "s"
};

const configs = {
  default: baseConfig,
  strict: {
    ...baseConfig,
    decimalPlaces: 0
  }
};

Создание слоя совместимости (adapter layer)

Для минимизации рисков вводится промежуточный слой абстракции, инкапсулирующий работу с библиотекой.

Функции слоя:

  • унификация инициализации;
  • нормализация методов получения/установки значений;
  • преобразование событий;
  • изоляция различий версий.

Пример адаптера:

import AutoNumeric from "autonumeric";

export class NumericField {
  constructor(element, config) {
    this.instance = new AutoNumeric(element, config);
  }

  set(value) {
    this.instance.set(value);
  }

  get() {
    return this.instance.getNumber();
  }

  updateConfig(config) {
    this.instance.update(config);
  }

  destroy() {
    this.instance.remove();
  }
}

Использование подобного слоя позволяет исключить прямую зависимость бизнес-логики от API библиотеки.

Поэтапная замена инстансов

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

Выделяются этапы:

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

Для контроля используется feature toggle:

const useNewAutoNumeric = featureFlags.autoNumericV2;

const field = useNewAutoNumeric
  ? new NumericField(el, config)
  : legacyInit(el, config);

Миграция обработки событий

Существенные изменения часто затрагивают event-слой:

  • input
  • change
  • focus
  • blur

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

Пример унифицированной обработки:

element.addEventListener("input", (e) => {
  const raw = instance.getNumber();
  onValueChange(raw);
});

Дополнительно вводится нормализация событий:

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

Валидация и тестирование миграции

Контроль корректности миграции реализуется через многоуровневое тестирование:

Юнит-тесты:

  • проверка преобразования значений;
  • проверка конфигураций;
  • проверка адаптера.

Интеграционные тесты:

  • взаимодействие с формами;
  • работа в рамках SPA-компонентов;
  • динамическое создание и удаление полей.

E2E-сценарии:

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

Типовой тест:

test("formats currency correctly", () => {
  const field = new NumericField(input, config);
  field.set(1500);
  expect(input.value).toBe("1 500,00 ₸");
});

Стратегия отката изменений

Миграция без механизма отката считается неполной. Используются следующие подходы:

  • сохранение legacy-инициализации;
  • переключение через feature flags;
  • изоляция новых инстансов;
  • возможность параллельного существования двух реализаций.

При обнаружении критических ошибок выполняется мгновенное переключение:

featureFlags.autoNumericV2 = false;

Типовые проблемы при миграции

В процессе перехода регулярно возникают повторяющиеся проблемы:

Несовместимость форматов чисел

  • различия в десятичном и тысячном разделителях;
  • потеря точности при преобразованиях.

Двойная инициализация

  • повторное создание инстанса на одном элементе;
  • утечки памяти при отсутствии destroy/remove.

Конфликты с фреймворками

  • React controlled/uncontrolled input;
  • Vue реактивные поля;
  • Angular change detection циклы.

Проблемы локализации

  • несоответствие форматов региона;
  • некорректное отображение валютных символов.

Организация постепенного перехода на новую архитектуру

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

Оглавление