Практика системного анализа · 6 минут
Миграция enum: как найти потребителей старого значения до смены контракта
Как заменить статус в API без слепого удаления: найти потребителей, проверить старые клиенты, исторические события и отчёты, задать этапы перехода и откат.
Миграция enum меняет набор допустимых значений поля и поведение участников обмена. Проверка новой схемы охватывает только часть задачи. Нужно узнать, кто ещё читает старое значение, кто записывает новое и что произойдёт с историческими событиями.
«Переименуем статус»
Учебная команда хочет заменить статус заявки pending на awaiting_review. В версии v1 сервер возвращает pending, approved, rejected. В версии v2 вместо pending будет awaiting_review; смысл состояния пока сохраняется.
Все контракты и потребители в примере синтетические. Совместимость реальных клиентов не измерялась.
Для разработчика сервера замена выглядит как одно строковое значение. У клиента с закрытым перечислением неизвестная строка может вызвать ошибку десериализации. Отчёт может перестать считать заявки, а обработчик очереди — отправить событие на повторную обработку.
Google AIP-180 рассматривает удаление и переименование компонентов как вопросы обратной совместимости. Для нашего случая из этого следует практическая проверка: каждое принимающее приложение должно понимать значение, которое ему начнут отправлять. Одна успешная сборка сервера эту проверку не заменяет.
Матрица участников обмена
| Участник | Получает или создаёт | Что делает со статусом | Риск перехода | Доказательство готовности |
|---|---|---|---|---|
| API-сервер | Создаёт ответы | Выбирает значение по версии API | Утечка нового значения в v1 | Контрактные тесты v1 и v2 |
| Веб-клиент | Читает API | Показывает статус и доступные действия | Неизвестная строка | Тест интерфейса на обоих значениях |
| Мобильный клиент старой версии | Читает API | Использует закрытый enum | Ошибка разбора | Тест старой сборки или сохранение v1 |
| Отчёт | Читает хранилище | Фильтрует status=pending | Потеря строк в подсчёте | Сверка результата до и после |
| Обработчик событий | Читает очередь | Выбирает ветку обработки | Бесконечные повторы | Повтор исторического события |
Матрица должна перечислять и тех, кого команда не контролирует. «Не нашли других потребителей» — ограничение поиска, пока нет достаточного покрытия журналов, репозиториев и владельцев интеграций.
Источники поиска: контракт API, подписки на события, обращения к полю в коде, запросы отчётов и наблюдения использования версий. Поиск строки pending помогает, но не обнаруживает клиента, который генерирует перечисление из схемы.
План совместимого перехода
В этом примере команда выбирает версионированный ответ: v1 продолжает отдавать pending, v2 отдаёт awaiting_review. Внутреннее состояние можно переименовать отдельно, если отображение наружу сохраняет смысл.
Сначала потребители, которым нужны оба формата, учатся читать оба значения. Затем команда проверяет старые приложения и запускает v2 для готовых клиентов. Удалять v1 можно только по отдельному решению с подтверждёнными условиями прекращения поддержки.
Если сервер временно принимает оба значения на вход, команда должна определить нормализацию. Например, v2 принимает только awaiting_review, а v1 только pending; внутреннее состояние у них общее. Это исключает бесконтрольное появление двух синонимичных статусов в данных.
Здесь переименование не меняет смысл. Если новый статус означает дополнительную проверку, отображение обратно в pending может скрыть существенное различие. Тогда нужен другой план: новая модель состояний, правила переходов и согласованная деградация для старых клиентов.
Контрольные примеры
Ответ v1: {"id":"R7","status":"pending"}. Ответ v2 для той же заявки: {"id":"R7","status":"awaiting_review"}. Историческое событие E1 остаётся {"id":"E1","status":"pending","schema_version":1}.
Тесты должны проверить три направления: старый клиент читает ответ v1, новый клиент читает v2, новый обработчик повторно читает E1. Кроме успешного разбора нужна проверка действия: заявка ожидает согласования, а не попадает в ветку отказа по умолчанию.
Для отчёта возьмём четыре заявки: две ожидают согласования, одна одобрена и одна отклонена. До и после перехода ожидающий итог равен двум. Если после смены внутренней строки отчёт показывает ноль, совместимость схемы API не спасла бизнес-результат.
Условие остановки и откат
Если неизвестный статус растит ошибки разбора, количество повторов событий или расхождения отчёта, выпуск нового значения нужно остановить. Откат должен учитывать уже записанные значения. Возврат старой версии приложения без преобразования данных может сделать ситуацию хуже.
LLM полезна для черновика матрицы и поиска забытых направлений обмена. Подтверждать отсутствие потребителя должны проверяемые источники. Результат перед выпуском — список участников с доказательствами, а не общий вывод «enum совместим».
Изменения схемы сопоставьте с разбором версий требований. Отдельные ответы проверьте по примеру сверки контракта и данных.
Вопросы по enum
Можно ли удалить статус, который не встречается в свежих ответах?
Не сразу. Он может оставаться в исторических событиях, кешах, отчётах и старых приложениях. Нужны проверки этих путей.
Добавление значения безопаснее переименования?
Не обязательно для закрытого перечисления клиента. Даже добавленное значение может сломать разбор, если клиент не умеет обрабатывать неизвестные варианты.
Зачем сохранять версию события?
Она помогает выбрать правила чтения старого сообщения. Изменение текущей схемы не переписывает уже отправленные события автоматически.
Что проверять кроме успешной десериализации?
Переход состояния, доступные действия, ветку обработчика и итог отчёта. Клиент может принять строку и принять неверное решение.
Можно ли считать поиск по репозиторию полной инвентаризацией?
Нет. Внешние приложения и генераторы клиентов могут не попасть в поиск. Ограничения покрытия нужно записать в плане миграции.
Автор: Иннокентий Бодров, автор Аналитической мастерской.