← Назад к блогу

Практика системного анализа · 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

Можно ли удалить статус, который не встречается в свежих ответах?

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

Добавление значения безопаснее переименования?

Не обязательно для закрытого перечисления клиента. Даже добавленное значение может сломать разбор, если клиент не умеет обрабатывать неизвестные варианты.

Зачем сохранять версию события?

Она помогает выбрать правила чтения старого сообщения. Изменение текущей схемы не переписывает уже отправленные события автоматически.

Что проверять кроме успешной десериализации?

Переход состояния, доступные действия, ветку обработчика и итог отчёта. Клиент может принять строку и принять неверное решение.

Можно ли считать поиск по репозиторию полной инвентаризацией?

Нет. Внешние приложения и генераторы клиентов могут не попасть в поиск. Ограничения покрытия нужно записать в плане миграции.

Автор: Иннокентий Бодров, автор Аналитической мастерской.