Если frontend уже получает validation error, самый быстрый безопасный ход — вернуть удалённое поле или прежний тип совместимым resolver. Не заставляйте все клиенты обновиться одновременно: мобильные сборки и открытые вкладки продолжают отправлять старые operations после backend deploy.
Дальше изменение проводят как миграцию: сначала расширяют schema, затем переводят clients и только после наблюдаемого нулевого использования сжимают контракт. Повторное переименование в спешке создаёт третью несовместимую версию.
Schema diff ещё не знает, кто сломался
| Изменение | Почему опасно | Совместимый путь |
|---|---|---|
| Удалено поле | Старая selection set не валидируется | Вернуть, deprecate, мигрировать |
| String стал String! | Сервер обещает больше, но resolver может нарушить обещание | Сначала устранить null и измерить |
| String! стал String | Generated 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, затем повторить обычную проверенную доставку.
- Воспроизвести failing operation конкретной версии клиента.
- Вернуть compatibility field и resolver.
- Проверить старую и новую operations на одном окружении.
- Включить schema check в pull request.
- Провести миграцию clients с telemetry.
- Удалить поле отдельным изменением после контрольного окна.
Что принести на совместный разбор
Нужны SDL до и после, schema diff, failing operation с variables без персональных данных, response errors, client name/version, список subgraphs и порядок deploy resolver/schema. По этому набору видно, что вернуть немедленно и какой migration path не требует синхронного выпуска всех клиентов.