🤔 Почему новый Gato GraphQL выходил 1,5 года?

Версия 0.9 Gato GraphQL только что вышла. На подготовку ушло почти 1,5 года разработки и более 16 000 коммитов. Это действительно долго!

После того как я поделился анонсом на Hacker News, мне задали следующий вопрос:

[...] Мне интересно узнать, что потребовало 16k коммитов. Проекты, в которых я участвовал, с более чем десятью тысячами коммитов имели многие десятки или сотни людей, работающих полный рабочий день. [...] Есть ли какая-то сложность, которую нужно было преодолеть, о которой в посте не говорится?

Количество коммитов — не очень надёжная метрика, поскольку я могу сделать очень простое изменение и зафиксировать его как один коммит. Многие из этих 16k коммитов были коммитами "typo" или просто улучшением описания в каком-нибудь README.

Тем не менее количество коммитов даёт представление о реальных затраченных усилиях. Было также немало коммитов, наполненных изменениями, включавших десятки и даже сотни правок за раз. Изменения между версиями 0.8 и 0.9 действительно огромны, и чтобы их реализовать, потребовались усилия и время.

В этой записи блога я опишу, что это за изменения, чтобы объяснить, почему это заняло так много времени. И, делая это, я также дам предварительный обзор некоторых расширенных возможностей, которые были добавлены в кодовую базу и увидят свет в предстоящей версии 1.0.

​

История GraphQL-сервера

Для начала поделюсь немного историей движка и техническими деталями того, как он работает.

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

Gato GraphQL основан на PoP — движке, который рендерит компоненты на PHP (аналог React или Vue на JavaScript). Его зависимость от этого движка абсолютна, поэтому плагин размещён в монорепозитории GatoGraphQL/GatoGraphQL на GitHub.

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

Gato GraphQL разрешает GraphQL-запрос, сначала преобразуя его в эквивалентную модель компонентов, которую PoP затем разрешает, получая все необходимые данные, а затем этим данным придаётся форма GraphQL-запроса.

Когда я начал работать над PoP примерно в 2013/2014 году, GraphQL ещё не существовал, и методология разрешения модели компонентов в данные была спроектирована и реализована с нуля. Отсутствие модели для подражания (такой как GraphQL для концепций и эталонный проект graphql-js для реализации) было одновременно и помехой, и благом, как я объясню позже.

PoP изначально был спроектирован для рендеринга всего веб-сайта в виде HTML на стороне сервера, при этом предоставляя сырые данные в формате JSON при добавлении ?output=json к URL страницы, с возможностью дополнительно выбирать, какие данные получать (настройки, данные объектов БД), используя дополнительные параметры URL.

Пожалуйста, перейдите по следующим ссылкам (все они указывают на одну и ту же веб-страницу, только с разными параметрами URL) и обратите внимание на различия:

• HTML-контент: mesym.com/en/posts/
• Сырые данные JSON (настройки + БД): mesym.com/en/posts/?output=json
• Сырые данные JSON (БД): mesym.com/en/posts/?output=json&module=data

При переходе по последней ссылке приходит осознание: это практически GraphQL! Единственное большое отличие состоит в том, что данные в ответе неявны — они уже определены компонентами (на PHP), которые были включены на страницу. GraphQL же позволяет нам решать, какие данные получать, с помощью запроса.

Поэтому, когда я узнал о GraphQL примерно в 2019 году, для меня было очевидно, что PoP тоже должен стать GraphQL-сервером. Всё, что ему нужно было сделать, — принять GraphQL-запрос в качестве входных данных и на лету создать модель компонентов на основе запроса.

И это именно то, что я сделал. И это работало хорошо. Но было медленно, потому что PoP понимал собственный формат входных данных, поэтому GraphQL-запрос приходилось адаптировать к формату PoP:

1. Разобрать GraphQL-запрос; затем
2. Преобразовать запрос в формат PoP; затем
3. Разобрать формат PoP

Разбор GraphQL-запроса тогда выполнялся дважды (один раз для GraphQL, один раз для PoP), а формат PoP не разрешался через AST, а просто посредством повторного разбора строки запроса снова и снова. (Отсутствие AST было ужасным кодированием, но у меня не было спецификации для следования, и разработка происходила органически, где простой substr(...) решал проблему каждый день.)

Вот почему я говорю, что отсутствие спецификации GraphQL было помехой, поскольку моё решение было медленным (и таким было положение дел в версии 0.8). Поэтому я решил это исправить.

​

Преобразование движка в GraphQL-first

Решение, на котором я остановился, — заставить PoP нативно работать с языком GraphQL. Тогда передача GraphQL-запроса в PoP в качестве входных данных уже будет преобразована в модель компонентов, без необходимости каких-либо дополнительных адаптеров или двойной работы.

Это означало, что проект PoP нужно было переориентировать: из PHP-библиотеки, которая рендерила компоненты для веб-сайтов на стороне сервера и была адаптирована для разрешения GraphQL-запросов, она должна была стать настоящим GraphQL-сервером.

Кодовая база претерпела масштабные преобразования: GraphQL AST стал основой для передачи состояния между всеми PHP-сервисами в движке. Объекты GraphQL AST теперь являются входными данными для PoP (вместо строк запросов).

Другие GraphQL-серверы на PHP опираются на graphql-php, но плагин Gato GraphQL — нет. Это плохая новость с точки зрения усилий на поддержку (поскольку я не могу повторно использовать то, что закодировал кто-то другой), но хорошая новость с точки зрения независимости: я могу решать, добавлять ли пользовательские функции в мой плагин в своём собственном темпе и по собственному усмотрению (именно поэтому плагин уже предоставляет входной объект «oneof»).

И, как будет показано в разделе ниже, это большое преимущество.

​

Добавление оригинальных возможностей в GraphQL

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

query {
  posts(
    pagination: { limit: 5, offset: 20 }
    sort: { by: DATE, order: ASC }
  ) {
    id
    title
    content
    url
    author {
      id
      name
      url
    }
    comments {
      id
      date
      content
    }
  }
}Copy

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

Вот несколько примеров, где GraphQL полезен:

• Извлечение информации из одного или нескольких источников (например, пользователей с сайтов WordPress и контактных данных рассылки из Mailchimp), объединение данных и их совместный анализ как единого набора данных
• Выполнение операций для адаптации контента на сайте:
  • Единовременно, например при переносе сайта на другой домен и замене "www.myoldsite.com" на "mynewsite.com" везде в контенте и метаданных
  • На постоянной основе, например для замены любого "http://" на "https://" при каждой публикации нового поста автором
• Подключение к Google Translate API для перевода всех записей блога на другой язык
• Автоматическая публикация твита после публикации записи в блоге

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

• Поддержка полей «функциональности» (в дополнение к полям «данных»), которые добавляются ко всем типам в схеме
• Передача результата одного поля в качестве входных данных другому полю в том же запросе
• Компоновка директив для того, чтобы одна директива изменяла поведение другой директивы
• Динамическое решение о применении директивы или нет, основанное на значении поля

И я определённо не хотел удалять эти функции из GraphQL-сервера: я уже закодировал их, и они безусловно ценны.

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

​

Пример манипуляции данными в GraphQL

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

Следующий GraphQL-запрос получает список пользовательских записей из внешнего REST API (который можно @remove-ить из ответа); подаёт эти данные в другое поле прямо в том же запросе; извлекает свойство email из каждой записи; и наконец преобразует email в верхний регистр, но только если язык в той же записи — английский или немецкий:

###################################################################
# Fetch data from a REST endpoint, extract the emails, and make
# uppercase those ones from users with a special language.
###################################################################
query ExtractEmailsFromAPIAndUpperCaseSpecialOnes
{
  # Retrieve data from a REST API endpoint
  userEntries: _sendJSONObjectCollectionHTTPRequest(
    input: {
      url: "https://newapi.getpop.org/wp-json/newsletter/v1/subscriptions"
    }
  ) # @remove   # <= Uncomment this directive to not print the API data
 
  emails: _echo(value: $__userEntries)
 
    # Iterate all the entries, passing every entry
    # (under the dynamic variable $userEntry)
    # to each of the next 4 directives
    @underEachArrayItem(
      passValueOnwardsAs: "userEntry"
      affectDirectivesUnderPos: [1, 2, 3, 4]
    )
 
      # Extract property "lang" from the entry
      # via the functionality field `_objectProperty`,
      # and pass it onwards as dynamic variable $userLang
      @applyField(
        name: "_objectProperty"
        arguments: {
          object: $userEntry,
          by: {
            key: "lang"
          }
        }
        passOnwardsAs: "userLang"
      )
 
      # Execute functionality field `_inArray` to find out
      # if $userLang is either "en" or "de", and place the
      # result under dynamic variable $isSpecialLang
      @applyField(
        name: "_inArray"
        arguments: {
          value: $userLang,
          array: ["en", "de"]
        }
        passOnwardsAs: "isSpecialLang"
      )
 
      # Extract property "email" from the entry
      # and set it back as the value for that entry
      @applyField(
        name: "_objectProperty"
        arguments: {
          object: $userEntry,
          by: {
            key: "email"
          }
        }
        setResultInResponse: true
      )
 
      # If $isSpecialLang is `true` then execute
      # directive `@strUpperCase` 
      @if(condition: $isSpecialLang)
        @strUpperCase
}Copy

Вот ответ (обратите внимание, как только определённые email были переведены в верхний регистр):

{
  "data": {
    "userEntries": [
      {
        "email": "abracadabra@ganga.com",
        "lang": "de"
      },
      {
        "email": "longon@caramanon.com",
        "lang": "es"
      },
      {
        "email": "rancotanto@parabara.com",
        "lang": "en"
      },
      {
        "email": "quezarapadon@quebrulacha.net",
        "lang": "fr"
      },
      {
        "email": "test@test.com",
        "lang": "de"
      },
      {
        "email": "emilanga@pedrola.com",
        "lang": "fr"
      }
    ],
    "emails": [
      "ABRACADABRA@GANGA.COM",
      "longon@caramanon.com",
      "RANCOTANTO@PARABARA.COM",
      "quezarapadon@quebrulacha.net",
      "TEST@TEST.COM",
      "emilanga@pedrola.com"
    ]
  }
}Copy

Проверьте сами! Нажмите кнопку «Run», чтобы выполнить запрос:

###################################################################
# Fetch data from a REST endpoint, extract the emails, and make
# uppercase those ones from users with a special language.
###################################################################
query ExtractEmailsFromAPIAndUpperCaseSpecialOnes {
  # Retrieve data from a REST API endpoint
  userEntries: _sendJSONObjectCollectionHTTPRequest(
    input: {
      url: "https://newapi.getpop.org/wp-json/newsletter/v1/subscriptions"
    }
  )
  # @remove   # <= Uncomment this directive to not print the API data
  emails: _echo(value: $__userEntries)
    # Iterate all the entries, passing every entry
    # (under the dynamic variable $userEntry)
    # to each of the next 4 directives
    @underEachArrayItem(
      passValueOnwardsAs: "userEntry"
      affectDirectivesUnderPos: [1, 2, 3, 4]
    )
      # Extract property "lang" from the entry
      # via the functionality field `_objectProperty`,
      # and pass it onwards as dynamic variable $userLang
      @applyField(
        name: "_objectProperty"
        arguments: { object: $userEntry, by: { key: "lang" } }
        passOnwardsAs: "userLang"
      )
      # Execute functionality field `_inArray` to find out
      # if $userLang is either "en" or "de", and place the
      # result under dynamic variable $isSpecialLang
      @applyField(
        name: "_inArray"
        arguments: { value: $userLang, array: ["en", "de"] }
        passOnwardsAs: "isSpecialLang"
      )
      # Extract property "email" from the entry
      # and set it back as the value for that entry
      @applyField(
        name: "_objectProperty"
        arguments: { object: $userEntry, by: { key: "email" } }
        setResultInResponse: true
      )
      # If $isSpecialLang is `true` then execute
      # directive `@strUpperCase`
      @if(condition: $isSpecialLang)
        @strUpperCase
}Copy

Я упоминал, что отсутствие ориентиров в виде GraphQL было помехой, но (в ретроспективе) также и благом. Это потому, что у меня не было ограничений спецификации GraphQL, и поэтому я мог позволить себе мечтать об этих новых возможностях.

И теперь, когда эти функции были перенесены в Gato GraphQL, он может стать невероятно полезным союзником для всего, что связано с получением, манипуляцией и преобразованием контента для вашего сайта WordPress. (Хотя они будут доступны только в предстоящей v1.0.)

Заняло некоторое время, но усилия того явно стоили.

​

Попробуйте!

Убедились, что долгое ожидание того стоило? Надеюсь, что да!

Давайте, скачайте плагин и посмотрите:

Хотите получать новости о разработке, новую документацию и анонсы предстоящих релизов, включая v1.0? Добро пожаловать — подпишитесь на рассылку.

Хотите изучить открытый исходный код на GitHub? Посмотрите GatoGraphQL/GatoGraphQL (и смело ставьте звезду... Мы любим звёзды! ⭐️⭐️⭐️)

Кстати, какие преобразования контента вам нужно выполнять в WordPress (для которых вы, возможно, уже используете какой-то специализированный коммерческий плагин)? Пожалуйста, напишите мне сообщение с описанием вашего случая использования.

Если вам нравится то, что вы видите, пожалуйста, поделитесь с друзьями и коллегами, помогите распространить любовь ❤️.