Обратная совместимость

Архитектура JavaScript API от HERE Technologies строится вокруг принципа контролируемой эволюции интерфейсов, при котором новые версии библиотеки сохраняют работоспособность значительной части существующего кода. Это достигается сочетанием версионирования загрузчика, модульной структуры, слоя устаревших интерфейсов и стабильного ядра пространственных типов данных.

Версионирование и стабильность API

HERE Maps JavaScript API исторически развивался как набор версий 3.x, где ключевая идея заключается в сохранении совместимости внутри мажорной ветки.

Основные характеристики подхода:

  • Мажорная версия (3.x) фиксирует базовые контракты API
  • Минорные обновления добавляют функциональность без изменения существующих сигнатур
  • Патчи исправляют ошибки без модификации публичных интерфейсов
  • Устаревшие методы сохраняются в течение нескольких релизов с пометками deprecation

Ключевой принцип: код, написанный под 3.0, должен продолжать работать в 3.1 и последующих минорных версиях без изменений, если он не использует явно помеченные устаревшие возможности.

Механизм загрузки и влияние на совместимость

Система загрузки SDK через H.service.Platform и динамические скрипты играет ключевую роль в сохранении совместимости.

Пример базовой структуры:

  • загрузчик SDK фиксируется на уровне версии URL
  • модули подгружаются лениво
  • базовый namespace H остаётся стабильным
const platform = new H.service.Platform({
  apikey: 'YOUR_API_KEY'
});

const defaultLayers = platform.createDefaultLayers();

Даже при обновлении SDK структура H.service.Platform сохраняется, что минимизирует необходимость рефакторинга.

Стабильное ядро пространственных объектов

Одним из главных механизмов обратной совместимости является неизменность фундаментальных классов:

  • H.map.Map
  • H.geo.Point
  • H.map.Marker
  • H.map.Polyline
  • H.map.Polygon

Эти классы формируют ядро API и редко подвергаются структурным изменениям. Вместо изменения поведения вводятся:

  • новые методы рядом со старыми
  • расширения через прототипы
  • дополнительные параметры с дефолтными значениями

Пример расширения без нарушения совместимости:

const point = new H.geo.Point(52.5, 13.4);
map.addObject(new H.map.Marker(point));

Даже при появлении новых типов координат или проекций старый код остаётся валидным.

Слой устаревших интерфейсов (Deprecation Layer)

Для обеспечения плавной миграции используется слой устаревших API.

Основные механизмы:

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

Пример типичного сценария:

map.setCenter({ lat: 52.5, lng: 13.4 });

Метод остаётся рабочим, даже если внутренне предпочтительным становится использование объектов H.geo.Point.

Модульная система и совместимость

Современная архитектура HERE Maps API использует модульную загрузку:

  • mapsjs-core
  • mapsjs-service
  • mapsjs-ui
  • mapsjs-mapevents

Совместимость обеспечивается тем, что:

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

Пример подключения:

<script src="https://js.api.here.com/v3/3.1/mapsjs-core.js"></script>
<script src="https://js.api.here.com/v3/3.1/mapsjs-service.js"></script>
<script src="https://js.api.here.com/v3/3.1/mapsjs-ui.js"></script>
<script src="https://js.api.here.com/v3/3.1/mapsjs-mapevents.js"></script>

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

Обратная совместимость событийной модели

Система событий в H.mapevents и H.ui сохраняет единый подход:

  • события генерируются через стандартный EventTarget-подобный механизм
  • подписка через addEventListener или addListener
  • сохранение старых типов событий при добавлении новых

Пример:

map.addEventListener('tap', function (evt) {
  console.log(evt.currentPointer);
});

Даже при расширении структуры события evt старые поля остаются доступными.

Совместимость геокодинга и сервисных API

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

Пример:

platform.getSearchService().geocode({
  q: 'Berlin'
}, result => {
  console.log(result.items);
}, error => {
  console.error(error);
});

Стабильность обеспечивается за счёт:

  • неизменности ключевых полей ответа (items, position, address)
  • добавления новых полей без удаления старых
  • версионирования REST-эндпоинтов

Политика расширения объектов вместо изменения

Одним из ключевых механизмов сохранения обратной совместимости является правило:

“Не изменять — расширять”

Применяется к:

  • объектам конфигурации
  • параметрам сервисов
  • структурам геометрии
  • UI-компонентам

Пример эволюции API:

// ранний вариант
map.setZoom(10);

// расширенный вариант
map.setZoom(10, true);

Старый вызов продолжает работать без изменений.

Совместимость пользовательского интерфейса (H.ui)

UI-компоненты библиотеки проектируются с учётом стабильности:

  • стандартные виджеты (ZoomControl, ScaleBar) сохраняют API
  • кастомизация через конфигурационные объекты
  • добавление новых опций без изменения базовой структуры
const ui = H.ui.UI.createDefault(map, defaultLayers);

Даже при изменении внутреннего DOM-рендеринга публичный API UI остаётся прежним.

Управление изменениями через feature flags

Для минимизации риска регрессий применяется механизм скрытых флагов:

  • новые функции активируются через параметры инициализации
  • экспериментальные возможности изолированы от стабильного API
  • отключаемые функции позволяют тестировать новые модели поведения

Это позволяет поддерживать стабильную ветку API без разрушения существующих приложений.

Работа с типами и структурная совместимость

JavaScript API сохраняет совместимость на уровне структур данных:

  • координаты всегда имеют lat и lng
  • геометрические объекты поддерживают единый интерфейс
  • массивы точек остаются совместимыми между версиями

Пример:

const line = new H.map.Polyline([
  { lat: 52.5, lng: 13.4 },
  { lat: 52.6, lng: 13.5 }
]);

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

Эволюция без разрушения: стратегия долгосрочной поддержки

Обратная совместимость в HERE Maps JavaScript API реализуется через многоуровневую стратегию:

  • сохранение стабильного публичного namespace H
  • отказ от удаления устаревших методов до завершения переходного периода
  • документирование изменений с указанием альтернатив
  • изоляция внутренних реализаций от публичных интерфейсов

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

Оглавление