Breaking changes в версиях

Google Maps JavaScript API

Одним из наиболее значимых источников breaking changes в экосистеме картографических веб-приложений является переход между крупными версиями API. В случае Google Maps JavaScript API ключевым разрывом стала миграция от v2 к v3, в ходе которой архитектура библиотеки была полностью переработана.

Версия v2 опиралась на устаревшую модель DOM-обёрток и тесную связку с глобальным пространством имён. В v3 была введена модульная архитектура, асинхронная загрузка и более строгая модель управления состоянием карты. Это привело к тому, что значительная часть старого кода перестала работать без переписывания.

Ключевые изменения:

  • отказ от глобального объекта GMap2
  • замена событийной модели GEvent на google.maps.event
  • полное удаление устаревших контролов и оверлеев
  • изменение принципов работы с проекциями и тайлами

Изменение модели загрузки и инициализации

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

Существенные изменения:

  • обязательная асинхронная загрузка через callback или importLibrary
  • запрет на использование неинициализированных пространств имён
  • разделение функционала на библиотеки (maps, places, geometry)

Это привело к несовместимости со старыми паттернами, где разработчики рассчитывали на доступность API сразу после загрузки <script>.

Изменения в работе с объектом Map

Объект карты претерпел несколько несовместимых изменений в параметрах и поведении.

Удаление и переименование опций

Некоторые параметры конструктора Map были удалены или заменены:

  • draggableCursor и draggingCursor поведение изменено
  • disableDoubleClickZoom стал частью более общей модели управления жестами
  • изменена логика mapTypeControl и его позиций

Жёсткость типов опций

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

Контроль и события: переход на новую систему

Старая модель событий с использованием статического объекта GEvent была полностью заменена на систему событий через пространство имён google.maps.event.

Ключевые breaking changes:

  • удаление GEvent.addListener
  • замена на google.maps.event.addListener
  • изменение контекста this в обработчиках событий
  • необходимость явного управления удалением слушателей через removeListener

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

Оверлеи и кастомные слои

Система оверлеев была полностью переработана.

Устаревшие классы

  • GOverlay удалён
  • GPolyline и GPolygon заменены на google.maps.Polyline и google.maps.Polygon
  • GMarker заменён на google.maps.Marker, а затем частично заменён на AdvancedMarkerElement

Advanced Markers

Поздние версии API ввели новый механизм маркеров:

  • отделение DOM-маркеров от канвас-рендеринга
  • поддержка кастомного HTML внутри маркеров
  • изменение поведения z-index и кластеризации

Это стало одним из наиболее критичных breaking changes, так как старые маркеры перестали поддерживать сложные кастомизации без переписывания логики.

Изменения в работе с сервисами (Places, Geocoding)

Интеграция сервисов была отделена от базового объекта карты.

Ключевые изменения:

  • переход к библиотекам places и geocoding
  • необходимость отдельного подключения сервисов
  • изменение структуры ответов API

В частности:

  • PlaceResult стал более строгим и структурированным
  • удалены неявные поля, ранее доступные без запроса дополнительных параметров
  • изменена модель квотирования запросов

Изменение API ключей и загрузки скриптов

Ранние версии позволяли использовать API без строгой привязки к ключу. В современных версиях:

  • API key стал обязательным
  • введены ограничения по доменам (HTTP referrers)
  • усилена модель биллинга

Любые старые реализации без ключа перестали работать, что стало критическим breaking change для устаревших проектов.

Изменения в TypeScript-типизации и строгих интерфейсах

Хотя JavaScript остаётся динамическим языком, современный Google Maps JavaScript API активно развивается с ориентацией на строгие типы.

Последствия:

  • удаление неявных свойств объектов
  • введение строгих интерфейсов для LatLngLiteral
  • изменение контрактов методов (например, обязательные поля в конструкторе Marker)

Это привело к тому, что код, который ранее «работал по факту», начал падать на этапе выполнения или линтинга.

Изменения в визуализации и WebGL-режимах

Переход к WebGL-ускорению стал ещё одним источником несовместимости.

Основные изменения:

  • введение WebGLOverlayView
  • изменение модели рендеринга тайлов
  • отказ от некоторых Canvas-based кастомизаций

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

Изменения в управлении библиотеками и загрузчиком

Появление нового загрузчика (importLibrary) заменило классический способ подключения через URL.

Последствия:

  • отказ от монолитного maps/api/js?libraries=...
  • ленивая загрузка модулей
  • изменение порядка инициализации зависимостей

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

Совместимость и поведение устаревших API

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

Типичные сценарии breaking changes:

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

Такая стратегия перехода часто приводила к скрытым ошибкам, которые проявлялись только в продакшене.

Изменения в работе с координатами и геометрией

Объекты LatLng и связанные утилиты претерпели изменения:

  • запрет на неявное приведение типов
  • различие между LatLng и LatLngLiteral
  • изменение поведения нормализации координат

Функции геометрии были вынесены в отдельную библиотеку geometry, что сделало старые импорты невалидными.

Переходные паттерны миграции кода

Типовые адаптации старого кода включают:

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

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

Оглавление