Версионирование в Google Maps JavaScript API определяет, какая именно сборка API загружается в браузер и какие изменения поведения, функций и исправлений будут доступны в конкретный момент времени. Модель версий построена таким образом, чтобы одновременно поддерживать предсказуемость для продакшн-систем и возможность получать актуальные обновления без необходимости постоянного изменения кода.
Google Maps JavaScript API использует несколько каналов
версионирования, которые задаются параметром v при
подключении скрипта.
weekly — основной канал с наиболее свежими изменениями.
Включает:
Пример подключения:
<script src="https://maps.googleapis.com/maps/api/js?key=API_KEY&v=weekly"></script>Характерная особенность канала — отсутствие долгосрочной стабильности поведения. Код, работающий сегодня, может требовать адаптации при очередном обновлении.
quarterly — стабильный канал с фиксированным набором
функций на протяжении квартала.
<script src="https://maps.googleapis.com/maps/api/js?key=API_KEY&v=quarterly"></script>Особенности:
Этот канал используется в системах, где важна предсказуемость поведения и минимизация рисков регрессий.
Помимо каналов, возможно указание конкретной версии API, например:
<script src="https://maps.googleapis.com/maps/api/js?key=API_KEY&v=3.56"></script>Такой подход фиксирует:
Однако фиксированная версия со временем перестает получать обновления, включая критические исправления безопасности и производительности.
Каждая версия Google Maps JavaScript API проходит несколько стадий:
Жизненный цикл построен так, чтобы минимизировать разрыв между новыми функциями и стабильностью продакшн-сред.
Изменения между версиями могут включать:
При переходе между версиями важно учитывать, что:
Помимо основной версии API, используется параметр
libraries, который также подвержен изменениям:
<script src="https://maps.googleapis.com/maps/api/js?key=API_KEY&v=weekly&libraries=places,geometry"></script>Библиотеки:
places — работа с POI и автодополнениемgeometry — геометрические вычисленияdrawing — инструменты рисованияvisualization — тепловые картыКаждая библиотека имеет собственный цикл обновлений, синхронизированный с основным каналом версии.
Современный подход рекомендует использование загрузчика:
import { Loader } from "@googlemaps/js-api-loader";
const loader = new Loader({
apiKey: "API_KEY",
version: "weekly",
libraries: ["places"]
});
loader.load().then(async () => {
const { Map } = await google.maps.importLibrary("maps");
const map = new Map(document.getElementById("map"), {
center: { lat: 55.7558, lng: 37.6173 },
zoom: 10
});
});Параметр version в загрузчике эквивалентен
v в URL-строке и определяет канал получения API.
Ключевой принцип версионирования — обратная совместимость в пределах major-версии.
Основные гарантии:
Однако возможны:
При устаревании функциональности API:
Типичный процесс миграции включает:
Используемая стратегия зависит от требований системы.
Использование weekly:
Использование quarterly:
Использование конкретной версии:
Браузер и CDN активно кэшируют ресурсы API. Версия влияет на:
Изменение версии автоматически приводит к:
Если параметр v не указан:
Такой режим считается непредсказуемым для долгоживущих приложений.
Архитектура приложений, использующих Google Maps JavaScript API, должна учитывать:
Особое значение имеет абстрагирование:
places,
geometry)Процесс перехода между версиями обычно включает:
При переходе с фиксированной версии на quarterly или
weekly чаще всего требуется:
Google поддерживает модель постепенного обновления:
Это позволяет строить системы, где: