My Geocode

Миграция

Сопоставление кодов ошибок разных провайдеров до перехода

· 3 мин чтения · My Geocode · #error-handling#migration-planning#geocoding#api-errors#testing

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

У каждого поставщика геокодирования и данных о местоположении свои соглашения о том, как сообщать о сбое: одни используют исключительно коды состояния HTTP, другие вкладывают поле статуса в JSON-ответ, который в остальном имеет статус 200, третьи различают «результаты не найдены» и «недопустимый запрос» разными кодами, а четвёртые сводят оба случая к общей ошибке. Логика повторных попыток приложения, сообщения об ошибках для пользователей и оповещения мониторинга обычно построены вокруг соглашений об ошибках одного конкретного поставщика, иногда без того, чтобы кто-то явно задокументировал эту зависимость.

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

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

My Geocode описывает свои ответы об ошибках и соглашения о статусах на странице /docs/errors/, а каждый ответ также содержит заголовки квоты X-Quota-Limit, X-Quota-Used, X-Quota-Free-Remaining, X-Quota-Network-Used, X-Credits-Remaining, X-Key-IPs-Used, X-Key-IPs-Limit и X-Quota-Reset. Они охватывают категорию информации (состояние квоты и лимитов), которую некоторые поставщики прячут в теле ответа об ошибке, а не отдают напрямую в заголовках. Проверить, разбирает ли ваша текущая логика повторных попыток информацию о квоте из тела ответа или из заголовка, будет хорошим конкретным пунктом для чек-листа миграции, поскольку информацию о квоте в заголовках обычно проще читать, не затрагивая путь разбора ответа, используемый для самих данных.

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

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

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