Пользовательские возможности для схемы

Множество возможностей, предложенных для спецификации GraphQL, уже реализованы в Gato GraphQL — ждать больше не нужно.

Пространства имён схемы

Если плагины WooCommerce и Easy Digital Downloads оба реализовали тип Product для GraphQL API, мы не смогли бы установить оба плагина одновременно, поскольку их типы конфликтовали бы.

Пространства имён схемы позволяют избежать конфликтов в схеме, присваивая всем именам типов пространство имён. Таким образом, тип Product стал бы Woo_Product и EDD_Product соответственно, и эти типы можно было бы добавить в одну и ту же схему.

На этом изображении показана схема с пространствами имён, в которой типам Event и Location был добавлен префикс EM_ для предотвращения коллизий имён:

Схема с пространствами имён

Глобальные поля

Глобальные поля — это поля, доступные в каждом типе схемы GraphQL (при этом определяемые только один раз).

Схема GraphQL предоставляет типы, такие как Post, User и Comment, и поля, доступные для каждого типа, например Post.title, User.name и Comment.responses. Эти поля работают с «данными», поскольку получают конкретную часть данных из сущности.

Gato GraphQL, помимо этого, также предлагает иной вид полей: те, которые предоставляют «функциональность» вместо данных.

Некоторые примеры глобальных полей:

_not
_if
_equals
_isEmpty
_echo
_sprintf
_arrayItem
_arrayAddItem
_arrayUnique
и многие другие

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

Поля функциональности принадлежат не конкретному типу, например Post или User, а всем типам схемы. Именно поэтому они обрабатываются особым образом в Gato GraphQL под названием «глобальные поля».

Field to input

Получите значение поля, манипулируйте им и передайте его в качестве входных данных в другое поле — всё в рамках одного запроса.

query {
  posts {
    excerpt
 
    # Referencing previous field with name "excerpt"
    isEmptyExcerpt: _isEmpty(value: $__excerpt)
 
    # Referencing previous field with alias "isEmptyExcerpt"
    isNotEmptyExcerpt: _not(value: $__isEmptyExcerpt)
  }
}

Составные директивы

Нередко директиву нельзя применить к полю, потому что её входные данные отличаются от выходных данных поля. Например, директива @strUpperCase принимает строку на вход, поэтому её нельзя применить к полю User.capabilities, которое возвращает массив строк.

С составными директивами одна директива может дополнять другую, изменяя её поведение или заполняя пробел. Это устраняет необходимость дублировать поля или директивы только для изменения их входных или возвращаемых типов, избегая раздувания кода.

В этом запросе директива @underEachArrayItem итерирует массив строк и применяет вложенную директиву @strUpperCase к каждой из них, устраняя несоответствие типов:

query {
  users {
    capabilities
      @underEachArrayItem
        @strUpperCase
  }
}

Директивы для нескольких полей

Применяйте директивы к нескольким полям (а не только к одному) для повышения производительности и расширенных сценариев использования.

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

Например, в следующем запросе директива @strTranslate применяется только к полю content:

query {
  posts {
    excerpt
    content @strTranslate
  }
}

К полю excerpt также можно применить директиву @strTranslate, добавив аргумент директивы affectAdditionalFieldsUnderPos со значением [1] (поскольку 1 — это относительная позиция поля excerpt от директивы @strTranslate):

query {
  posts {
    excerpt
    content
      @strTranslate(
        affectAdditionalFieldsUnderPos: [1]
      )
  }
}

Версионирование полей и директив

Версионируйте поля и директивы независимо от схемы.

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

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

Проактивная обратная связь

Используйте запись верхнего уровня extensions для отправки данных об устареваниях и предупреждениях в ответе на запрос.

Устаревания: Устаревания возвращаются в том же запросе, включающем устаревшие поля, а не только при выполнении интроспекции.
Предупреждения: Предупреждения — это проблемы, которые можно считать некритическими, то есть они улучшают запрос, но не нарушают его работу.

Например, следующий запрос экспортирует два поля, используя одно и то же имя динамической переменной "prop", что генерирует предупреждение:

query {
  posts {
    excerpt @export(as: "prop")
    content @export(as: "prop")
  }
}

Ответ будет содержать раздел warnings (внутри extensions) с соответствующим сообщением:

{
  "extensions": {
    "warnings": [
      {
        "message": "Dynamic variable with name 'props' had already been set, had its value overridden",
        "locations": [
          {
            "line": 4,
            "column": 25
          }
        ]
      }
    ]
  },
  "data": {
    "posts": {
      "excerpt": "Hello world!",
      "Content": "<p>Hello world!</p>"
    }
  }
}

Возможность: