My Geocode

Миграция

Миграция серверной интеграции без изменений на клиенте

· 3 мин чтения · My Geocode · #server-side#geocoding#migration#architecture#api-design

Одно из приятных свойств хорошо спроектированной серверной архитектуры в том, что смена поставщика может пройти полностью за границей внутреннего API, незаметно для любого веб- или мобильного клиента, который использует ваш сервис. Успех здесь зависит не столько от конкретного нового поставщика, сколько от того, есть ли такая чёткая граница в вашей кодовой базе ещё до начала миграции.

Ключевой принцип проектирования: клиентские приложения (веб-интерфейсы, мобильные приложения, другие внутренние сервисы) должны обращаться к вашему собственному API, который возвращает ваш собственный нормализованный формат ответа, а не напрямую к стороннему поставщику геокодирования и не получать необработанный формат ответа этого поставщика как есть. Когда такая граница существует, смена поставщика затрагивает только реализацию за вашим эндпоинтом, и все потребители этого эндпоинта не затронуты по построению, а не по счастливой случайности.

Если такой границы пока нет, то есть клиенты сейчас получают необработанный формат ответа конкретного поставщика, миграция станет подходящим моментом, чтобы её ввести, даже если это добавит немного работы на старте. Шаги выглядят примерно так:

  1. Определите собственный нормализованный формат ответа с названиями полей, которые имеют смысл для вашего приложения, а не копируйте дословно соглашения конкретного поставщика
  2. Реализуйте внутреннее преобразование реального ответа текущего поставщика в этот нормализованный формат и переведите каждый клиент на нормализованный формат вместо необработанного ответа поставщика
  3. Когда каждый клиент переведён на нормализованный формат и развёрнут, сама смена поставщика за этой границей становится изменением только на бэкенде, вообще без координации с клиентами

В первый раз это действительно больше работы, но она окупается при каждой следующей миграции, поскольку шаг 3 становится единственным шагом, нужным для любой будущей смены поставщика.

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

Аутентификация самого серверного сервиса поддерживает заголовок X-API-Key, заголовок Authorization: Bearer, HTTP Basic auth или параметр запроса, в зависимости от того, что естественнее вписывается в существующие соглашения вашего бэкенда об исходящих запросах. Расход квоты виден через заголовки ответа при каждом вызове, описанные на странице /docs/rate-limits/, и ваш бэкенд может отслеживать его централизованно, без того чтобы какой-либо клиент вообще знал о существовании квоты.

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

Ещё в разделе «Миграция»