Если frontend уже получает validation error, самый быстрый безопасный ход — вернуть удалённое поле или прежний тип совместимым resolver. Не заставляйте все клиенты обновиться одновременно: мобильные сборки и открытые вкладки продолжают отправлять старые operations после backend deploy.

Дальше изменение проводят как миграцию: сначала расширяют schema, затем переводят clients и только после наблюдаемого нулевого использования сжимают контракт. Повторное переименование в спешке создаёт третью несовместимую версию.

Schema diff ещё не знает, кто сломался

ИзменениеПочему опасноСовместимый путь
Удалено полеСтарая selection set не валидируетсяВернуть, deprecate, мигрировать
String стал String!Сервер обещает больше, но resolver может нарушить обещаниеСначала устранить null и измерить
String! стал StringGenerated types клиента меняютсяДобавить новое поле либо координировать release
Добавлен required inputСтарые mutations не передают значениеСделать optional/default, затем мигрировать
Переименован enum valueСтарый input не проходит coercionДобавить новое значение и сохранить старое на переход

Static diff показывает потенциальный риск, а operation checks отвечают, используются ли затронутые элементы реальными clients. Оба сигнала нужны: отсутствие telemetry не является доказательством безопасности, если часть трафика не подписана client name/version.

Expand: новый контракт живёт рядом со старым

type Order {
  id: ID!
  totalCents: Int!
  total: Money! @deprecated(
    reason: "Use totalCents; removal after client migration"
  )
}

# Старый resolver total остаётся рабочим на переходный период.

GraphQL September 2025 определяет @deprecated для fields, arguments, input fields и enum values. Deprecated field всё ещё разрешено включать в selection set — именно это сохраняет старых клиентов, пока tooling показывает причину и замену.

Migrate: считаем operations по версиям clients

Добавьте client name и version в телеметрию gateway, составьте список persisted и ad-hoc operations, затем обновляйте web, mobile и интеграции отдельно. Для каждой версии нужен smoke query против новой schema и фактический ответ resolver, а не только успешная генерация types.

  • Проверить composition/build schema до runtime тестов.
  • Сравнить diff с историческими operations.
  • Найти клиентов без имени или версии.
  • Обновить generated types и обработку новых enum values.
  • Оставить алерт по обращениям к deprecated field.

Contract: дата удаления зависит от наблюдений

Календарный срок сам по себе не доказывает, что field больше не нужен. Удаление разрешают, когда охвачено полное окно жизни clients, operation telemetry не показывает обращений и владельцы внешних интеграций подтвердили миграцию. Для клиентов без телеметрии сохраняют более консервативный контракт.

Перед удалением schema check должен сравнить proposed schema с активными operations. Apollo GraphOS, например, разделяет build, operations и linter checks; конкретный инструмент можно заменить, но проверка должна блокировать deploy, а не оставаться отчётом, который никто не читает.

Откат schema согласуется с resolver deploy

Возврат старого SDL не поможет, если код resolver уже перестал выдавать поле. В federation отдельно сверяют router/supergraph и версии subgraphs. Часто безопаснее roll forward: снова добавить совместимый field и resolver, затем повторить обычную проверенную доставку.

  1. Воспроизвести failing operation конкретной версии клиента.
  2. Вернуть compatibility field и resolver.
  3. Проверить старую и новую operations на одном окружении.
  4. Включить schema check в pull request.
  5. Провести миграцию clients с telemetry.
  6. Удалить поле отдельным изменением после контрольного окна.

Что принести на совместный разбор

Нужны SDL до и после, schema diff, failing operation с variables без персональных данных, response errors, client name/version, список subgraphs и порядок deploy resolver/schema. По этому набору видно, что вернуть немедленно и какой migration path не требует синхронного выпуска всех клиентов.

Проверенные источники