Новый 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 valueBreakingСгенерированные клиенты и сохранённые 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 становится измеряемым условием удаления.

Удаление — самостоятельный релиз с откатом

  1. Добавить новое поле и одинаковую authorization policy.
  2. Пометить старое @deprecated и опубликовать migration note.
  3. Перевести first-party clients и пересобрать persisted operations.
  4. Дождаться согласованного окна без trusted usage, включая редкие jobs.
  5. Удалить поле в canary, наблюдая validation errors по client identity.
  6. Иметь быстрый 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.

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