🥳 Gato GraphQL v0.9 выпущен!

Спустя почти 1,5 года разработки и более 16000 коммитов, наконец-то вышла новая версия Gato GraphQL! 🥳

Версия 0.9 — крупнейший релиз за всю историю плагина. Вот changelog, а здесь — полный разбор всех новых возможностей:

github.com/GatoGraphQL/GatoGraphQL/releases/tag/0.9.3

Документ довольно объёмный (более 40 минут чтения!), поэтому ниже приведён TL;DR с самыми важными изменениями.

​

Значительно расширена GraphQL-схема

Модель данных WordPress была в значительной мере отображена в GraphQL-схему.

В частности, схема получила следующие улучшения:

• Запрос данных из любого CPT, в том числе из любой темы и плагина
• Поддержка пользовательских таксономий (теги и категории)
• Созданы и возвращаются более подходящие GraphQL-типы (например: HTML, URL, DateTime)
• Field args организованы через input objects
• Использование oneof input objects для выбора сущности по различным свойствам (например: id, slug)
• Возврат payloads мутаций
• Запрос настроек (из wp_options) и мета-значений (для постов, пользователей, комментариев и таксономий)

​

Custom scalars

В GraphQL-сервер добавлена поддержка пользовательских скалярных типов. Custom scalars позволяют лучше представлять ваши данные — как при получении входных данных через аргумент поля, так и при формировании настраиваемого вывода в ответе.

Реализовано несколько стандартных пользовательских скалярных типов, которые сразу готовы к использованию в вашей GraphQL-схеме:

• Date
• DateTime
• Email
• HTML
• URL
• URLAbsolutePath

​

Custom enums

Теперь поддерживаются пользовательские типы enum. Enums — это особый вид скаляра, ограниченный определённым набором допустимых значений. Это позволяет:

• Проверять, что любой аргумент данного типа является одним из допустимых значений
• Сообщать через систему типов, что поле всегда будет принимать одно из конечного набора значений

Реализовано несколько типов enum, применяемых там, где это уместно, в GraphQL-схеме, включая:

• CommentOrderByEnum
• CommentStatusEnum
• CommentTypeEnum
• CustomPostOrderByEnum
• CustomPostStatusEnum
• MediaItemOrderByEnum
• MenuOrderByEnum
• TaxonomyOrderByEnum
• UserOrderByEnum

​

Input Objects

GraphQL-сервер теперь также поддерживает input types, и вы можете добавлять собственные input objects в GraphQL-схему. Input objects позволяют передавать сложные объекты в качестве входных данных полям, что особенно полезно для мутаций.

В схему в подходящих местах добавлено несколько input objects. Например, поля для запроса данных (такие как posts, users, comments и т. д.) принимают сложные input objects через field args filter, sort и pagination, а поля, изменяющие данные (такие как createPost, addCommentToCustomPost и т. д.), принимают input object через field arg input.

​

Oneof Input Objects

«Oneof» input object — это особый тип input object, в котором в качестве входных данных должно быть предоставлено ровно одно из полей; в противном случае возвращается ошибка валидации. Такое поведение вводит полиморфизм для входных данных.

Например, поле Root.post теперь принимает field argument by, являющийся oneof input object, что позволяет получить запись по различным свойствам — по id или по slug:

{
  postByID: post(by: {
    id: 1
  }) {
    id
    title
  }
 
  postBySlug: post(by: {
    slug: "hello-world"
  }) {
    id
    title
  }
}Copy

Преимущество в том, что одно поле может охватывать разные сценарии использования, избавляя от необходимости создавать отдельное поле для каждого случая (например, postByID, postBySlug и т. д.) — GraphQL-схема становится чище и элегантнее.

Реализовано несколько Oneof Input Objects:

• Root.customPost(by:)
• Root.mediaItem(by:)
• Root.menu(by:)
• Root.page(by:)
• Root.postCategory(by:)
• Root.postTag(by:)
• Root.post(by:)
• Root.user(by:)

​

Operation Directives

GraphQL-операции (то есть операции query и mutation) теперь также могут получать директивы.

​

Ограничение директив определёнными типами

Директивы полей можно ограничить применением только к полям определённого типа. Например, директива @strUpperCase, преобразующая значение поля в верхний регистр, имеет смысл только для полей типа String, но не для Int, Float или Boolean. Это ограничение теперь можно объявить в directive resolver.

​

Вывод полного пути к узлу GraphQL-запроса, вызывающему ошибки

Ответ теперь содержит полный путь к узлам GraphQL-запроса, возвращающим ошибку (в подполе extensions.path), что облегчает поиск источника проблемы.

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

query {
  myField @nonExisting
}Copy

Ответ будет следующим:

{
  "errors": [
    {
      "message": "There is no directive with name 'nonExisting'",
      "locations": [
        {
          "line": 2,
          "column": 7
        }
      ],
      "extensions": {
        "type": "QueryRoot",
        "field": "myField @nonExisting",
        "path": [
          "@nonExisting",
          "myField @nonExisting",
          "query { ... }"
        ],
        "code": "PoP\\ComponentModel\\e20"
      }
    }
  ],
  "data": {
    "id": "root"
  }
}Copy

​

Включение небезопасных настроек по умолчанию

Gato GraphQL предоставляет безопасные настройки по умолчанию:

• Единственный endpoint отключён
• «Чувствительные» элементы данных в GraphQL-схеме (такие как User.roles или фильтрация постов по status) не раскрываются
• Запросить можно лишь ограниченный набор настроек и мета-ключей (для постов, пользователей и т. д.)
• Количество сущностей, запрашиваемых за один раз, ограничено (для постов, пользователей и т. д.)

Эти безопасные настройки по умолчанию необходимы для защиты «живых» сайтов от вредоносных атак. Однако они не нужны при сборке «статических» сайтов, где сайт WordPress не уязвим для атак (например, когда это сайт разработки на ноутбуке, защищённый надёжным файрволом, или не доступный из интернета в целом).

Начиная с v0.9, можно включить небезопасные настройки по умолчанию, добавив в wp-config.php:

define( 'GRAPHQL_API_ENABLE_UNSAFE_DEFAULTS', true );Copy

Как вариант, можно определить ту же пару ключ/значение как переменную окружения.

При включении небезопасных настроек по умолчанию параметры плагина изменяются следующим образом:

• Единственный endpoint включён
• «Чувствительные» элементы данных раскрываются в GraphQL-схеме
• Можно запрашивать любые настройки и мета-ключи
• Количество сущностей, запрашиваемых за один раз, не ограничено

​

Организация Custom Endpoints и Persisted Queries по категориям

При создании Custom Endpoint или Persisted Query можно добавить к нему «GraphQL endpoint category», чтобы упорядочить все свои endpoints:

Например, можно создать категории для управления endpoints по клиенту, приложению или любому другому необходимому признаку:

В списке Custom Endpoints и Persisted Queries можно видеть их категории; при нажатии на ссылку категории или при использовании фильтра вверху отображаются только записи этой категории.

​

Запрос schema extensions через интроспекцию

Пользовательские метаданные, прикреплённые к элементам схемы, теперь можно запрашивать через поле extensions.

Все элементы интроспекции схемы дополнены новым полем, каждый из которых возвращает объект соответствующего типа «Extensions», раскрывающего пользовательские свойства этого элемента.

# Using "_" instead of "__" in introspection type name to avoid errors in graphql-js
type _SchemaExtensions {
  # Is the schema being namespaced?
  isNamespaced: Boolean!
}
 
extend type __Schema {
  extensions: _SchemaExtensions!
}
 
type _NamedTypeExtensions {
  # The type name
  elementName: String!
 
  # The "namespaced" type name
  namespacedName: String!
 
  # Enum-like "possible values" for EnumString type resolvers, `null` otherwise
  possibleValues: [String!]
 
  # OneOf Input Objects are a special variant of Input Objects where the type system asserts that exactly one of the fields must be set and non-null, all others being omitted.
  isOneOf: Boolean!
}
 
extend type __Type {
  # Non-null for named types, null for wrapping types (Non-Null and List)
  extensions: _NamedTypeExtensions
}
 
type _DirectiveExtensions {
  # If no objects are returned in the field (eg: because they failed validation), does the directive still need to be executed?
  needsDataToExecute: Boolean!
 
  # Names or descriptions of the types the field directives is restricted to, or `null` if it supports any type (i.e. it defines no restrictions)
  fieldDirectiveSupportedTypeNamesOrDescriptions: [String!]
}
 
extend type __Directive {
  extensions: _DirectiveExtensions!
}
 
type _FieldExtensions {
  isGlobal: Boolean!
 
  # Useful for nested mutations
  isMutation: Boolean!
 
  # `true` => Only exposed when "Expose "sensitive" data elements" is enabled
  isSensitiveDataElement: Boolean!
}
 
extend type __Field {
  extensions: _FieldExtensions!
}
 
type _InputValueExtensions {
  isSensitiveDataElement: Boolean!
}
 
extend type __InputValue {
  extensions: _InputValueExtensions!
}
 
type _EnumValueExtensions {
  isSensitiveDataElement: Boolean!
}
 
extend type __EnumValue {
  extensions: _EnumValueExtensions!
}Copy

​

Завершено отделение кода GraphQL-сервера от WordPress

Лежащий в основе плагина GraphQL-сервер теперь можно установить и запустить как самостоятельный PHP-компонент, то есть независимо от WordPress.

Это открывает возможности для использования Gato GraphQL с другими фреймворками (например, Laravel) и в любой PHP-среде — вне зависимости от наличия WordPress (например, при выполнении задачи Continuous Integration).

​

Просмотр документации при редактировании Schema Configuration, Custom Endpoint и Persisted Query

Все блоки, отображаемые при редактировании Schema Configuration, Custom Endpoint и Persisted Query, теперь содержат кнопку «info», при нажатии на которую документация открывается в модальном окне.

​

И многое другое

Чтобы узнать обо всех остальных новых возможностях, ознакомьтесь с полным описанием нового релиза или просмотрите changelog.

И скачайте плагин здесь.

Если вам понравилось, пожалуйста, помогите распространить информацию ❤️