Случаи использования версионирования полей и директив

Пожалуйста, сначала прочитайте руководство Эволюция схемы с помощью версионирования полей, в котором объясняется функция «field versioning» в Gato GraphQL.

Gato GraphQL позволяет полям и директивам принимать аргумент versionConstraint, чтобы выбрать конкретную версию (то есть реализацию) поля или директивы:

query GetPosts {
  posts(versionConstraint: "^1.0") {
    id
    title(versionConstraint: ">=2.1")
    excerpt @strUpperCase(versionConstraint: "~1.5.3")
  }
}Copy

Поле (или директива) также может иметь реализацию по умолчанию — ту, у которой нет версии (и которая используется, когда versionConstraint не указан в запросе).

При выполнении интроспекции извлекаются данные только для полей и директив по умолчанию. Как следствие, аргумент versionConstraint никогда не появится при интроспекции, поскольку поле или директива по умолчанию его не поддерживают.

Из-за этого мы всегда должны заранее знать, что у поля или директивы есть две или более версии на выбор, и знать номера этих версий. По умолчанию эта информация не является публичной.

Так в чём же польза версионирования? Вот несколько случаев использования.

​

Быстрое исправление ошибки для конкретного пользователя

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

Вы находите и исправляете проблему, но хотите убедиться, что она решена, прежде чем развёртывать изменение для всех. Тогда вы можете развернуть изменение под новым field resolver с версией "1.0.1" и попросить пользователя с проблемой изменить GraphQL-запрос, чтобы он указывал на эту версию поля:

{
  someBuggyField(versionConstraint: "1.0.1")
}Copy

Если ошибка действительно была исправлена, только тогда скопируйте код в field resolver по умолчанию.

​

Просьба к выбранным пользователям протестировать предстоящий релиз

Если поле или директива имеют версию и не имеют реализации по умолчанию (то есть без версии), то они вообще не будут отображаться при интроспекции.

{
  someField
    # This directive has no default implementation,
    # so it won't appear during introspection,
    # but it can still be added in the GraphQL query
    # when providing a constraint that satisfies it
    @someExperimentalDirective(versionConstraint: ">1.0")
}Copy

Вы можете развернуть поле или директиву, и они не будут видны в GraphQL API. Затем попросите выбранных пользователей их протестировать — для этого в своих запросах они должны указать соответствующий аргумент versionConstraint.

После принятия версионирование удаляется, и поле или директива становятся видимыми через интроспекцию и, следовательно, доступными для всех.