Новый GraphQL endpoint обычно не нужен, если меняется одно поле. Оставьте старый контракт работающим, добавьте новый путь к тем же данным и переведите клиентов постепенно. Начать нужно со schema diff и списка активных operations: без usage evidence метка @deprecated остаётся пожеланием, а дата удаления — догадкой.
Предыдущий аварийный сценарий, где поле уже удалили и frontend сломался, лечится возвратом поля. Здесь задача другая: не допустить аварии. Сервер некоторое время обслуживает обе формы, метрики связывают deprecated coordinate с client name и operation hash, а removal проходит отдельным изменением после доказанного окна без обращений.
Не каждое изменение требует версии, но каждое требует классификации
| Изменение | Обычно совместимо | Что проверить |
|---|---|---|
| Добавить nullable output field | Да | Resolver cost и authorization |
| Добавить optional argument | Да | Default behavior старых operations |
| Переименовать поле | Нет как один шаг | Add new, deprecate old, migrate, remove |
| Nullable сделать Non-Null | Рискованно | Нет ли реальных null и ошибок bubbling |
| Изменить смысл прежнего поля | Нет | Создать новое имя, не менять молча |
| Удалить enum value | Breaking | Сгенерированные клиенты и сохранённые documents |
Совместимость описывает не только SDL. Если поле осталось String, но вместо локального времени внезапно возвращает UTC или меняет единицы измерения, типы совпадают, а контракт сломан. Новая семантика получает новое имя и описание; старый resolver сохраняет прежнее поведение на период миграции.
Два поля работают параллельно
type Film {
director: String @deprecated(reason: "Use directedBy { name }; remove after client migration")
directedBy: Person
}
type Person {
id: ID!
name: String!
}GraphQL specification делает deprecated field легальным для запроса, чтобы существующие клиенты продолжали работать. Reason должен сообщать конкретную замену, а не «старое поле». Если новый resolver ходит в другой источник, сравните результаты на одной выборке и зафиксируйте допустимые различия до перевода клиентов.
Usage отвечает, кого уведомлять
- Нормализовать operations и считать schema coordinates после parse, не искать имя поля регулярным выражением.
- Связать operation hash с проверенным client name, версией приложения и владельцем.
- Отдельно учитывать persisted documents, batch operations, fragments и фоновые jobs.
- Не записывать variables и ответы с персональными данными ради статистики полей.
- Хранить last_seen и объём вызовов, чтобы редкий месячный job не потерялся в коротком окне.
Если introspection закрыт для внешнего трафика, это не мешает server-side usage telemetry. Метрика строится по уже прошедшим authorization запросам внутри execution pipeline. Случайный anonymous probing не должен продлевать срок поддержки старого business field, но активный доверенный клиент должен.
CI запрещает опасные переходы до deploy
schema-diff previous.graphql candidate.graphql
# fail: removed field/type/enum value
# review: nullability change, new required argument
# pass with owner: additive field and deprecation metadata
operation-check candidate.graphql active-operations.jsonНазвания команд условные: используйте checker вашей платформы, но проверяйте две вещи отдельно. Static diff находит изменение контракта, а operation check показывает, ломает ли оно известные documents. Второй результат не доказывает полную безопасность, если registry неполный; поэтому coverage registry становится измеряемым условием удаления.
Удаление — самостоятельный релиз с откатом
- Добавить новое поле и одинаковую authorization policy.
- Пометить старое @deprecated и опубликовать migration note.
- Перевести first-party clients и пересобрать persisted operations.
- Дождаться согласованного окна без trusted usage, включая редкие jobs.
- Удалить поле в canary, наблюдая validation errors по client identity.
- Иметь быстрый rollback схемы и resolver, пока storage path старого поля ещё доступен.
Не удаляйте database column одновременно со schema field. Сначала исчезает внешний usage, затем поле GraphQL, и только после отдельного наблюдения — внутренний storage dependency. Такой порядок оставляет реальный откат: вернуть SDL недостаточно, если данные уже необратимо преобразованы.
Критерий завершения фиксируется заранее
Запишите owners, дату начала deprecation, замену, минимальное окно наблюдения, допустимый список исключений и rollback owner. Для разбора подготовьте current/candidate SDL, schema diff, registry operations, распределение client versions и пример ответа обоих полей. Успех — новый клиент использует только новый coordinate, старый продолжает работать до конца окна, а удаление не создаёт всплеск validation errors.