Введение в двойной API, представленный в WooCommerce

В WooCommerce 10.9 была представлена новая экспериментальная инфраструктура dual API + GraphQL, совместимая с PHP 8.1+, разработанная в рамках инициативы Radical Speed Month.

Основная идея

Двойной API состоит из трех компонентов:

• Авторитетный кодовый API, представляющий собой простые PHP-классы, декорированные PHP-атрибутами. Эти классы могут быть либо исполняемыми (путем реализации шаблона Command), либо DTO (Data Transfer Object).
• GraphQL API, автоматически генерируемый из кодового API и отражающий его существующие классы. Исполняемые классы становятся запросами и мутациями, DTO — типами ввода и вывода.
• Скрипт сборки, который запускается во время разработки и генерирует часть GraphQL из кодовой части.

Например, если у нас есть следующий класс команд:

#[Name( 'coupon' )]
#[Description( 'Retrieve a single coupon by ID or code. Exactly one of the two arguments must be provided.' )]
#[RequiredCapability( 'read_private_shop_coupons' )]
class GetCoupon {
	public function execute(
		#[Description( 'The ID of the coupon to retrieve.' )]
		?int $id = null,
		#[Description( 'The coupon code to look up.' )]
		?string $code = null,
	): ?Coupon {
		// Retrieve and return the coupon
	}
}

…и следующий класс DTO:

#[Description( 'Represents a WooCommerce discount coupon.' )]
class Coupon {
	use ObjectWithId; //This is a reusable trait

	#[Description( 'The coupon code.' )]
	public string $code;

	#[Description( 'The type of discount.' )]
	public DiscountType $discount_type; //DiscountType is a PHP 8 enum

	#[Description( 'The discount amount.' )]
	public float $amount;

	#[Description( 'The date the coupon was created.' )]
	#[ScalarType( DateTime::class )]
	public ?string $date_created;

	#[Description( 'Product IDs the coupon can be applied to.' )]
	#[ArrayOf( 'int' )]
	public array $product_ids;
	
	//...and more
}

… мы сможем выполнить GraphQL-запрос:

Обратите внимание, что имена классов и свойств, а также типы методов и свойств автоматически преобразуются в их аналоги в GraphQL, но у класса GetCoupon есть атрибут Name, который преобразует имя запроса GraphQL в «coupon». Общее правило таково: соглашения там, где это возможно, атрибуты PHP там, где соглашений недостаточно (например, описания) или где имеет смысл явное переопределение (например, имена запросов и типов).

Это и API, и инструмент для создания API

В ядре WooCommerce содержится небольшой демо-прототип API (подробнее об этом позже) и инфраструктура, необходимая для преобразования его в GraphQL API. И вот что интересно: эту инфраструктуру могут использовать плагины WooCommerce для создания собственных двойных API! Таким образом, вы определяете свои классы кода, запускаете скрипт сборки непосредственно из WooCommerce во время разработки, и получаете часть GraphQL прямо в своем плагине. Затем вы подключаетесь к rest_api_init, чтобы зарегистрировать свой GraphQL API по требуемому URL-адресу конечной точки, используя предоставленный вспомогательный метод, и все готово.

Инфраструктура в ядре содержит несколько вспомогательных классов, которые можно использовать как есть или заменить кастомными вариантами. Например, есть класс-резолвер (по умолчанию это стандартный контейнер внедрения зависимостей WooCommerce), класс Principal (пользователь WordPress) для аутентификации и атрибут RequiresCapability для авторизации: вы можете использовать их или определить кастомный класс-резолвер / кастомный механизм аутентификации/авторизации.

Для наглядности предоставляем пример тестового плагина.

Текущий статус: экспериментальный

Это экспериментальная функция, которую необходимо явно включить перед использованием. Мы надеемся в ближайшее время перевести её в стабильный статус, но пока не гарантируем обратной совместимости ни для инфраструктуры, ни для основного API. В частности:

• Что касается инфраструктурной части (правил создания классов кодового API, атрибутов и вспомогательных классов инфраструктуры, а также скрипта, который собирает часть GraphQL): мы надеемся, что она достаточно стабильна для использования, но нам может потребоваться внести корректировки (возможно, с критическими изменениями) по мере более тщательного тестирования.
• Что касается части кодового API в ядре: WooCommerce 10.9 будет поставляться с ограниченным API, охватывающим товары и купоны. Пожалуйста, рассматривайте этот API как демонстрационный образец: мы, вероятно, внесем существенные изменения в эти классы/запросы (возможно, даже заменим их чем-то совершенно другим) в будущих релизах.

Требуются тестировщики

Учитывая все вышесказанное, вы можете (и даже рекомендуется) протестировать новый двойной API в средах разработки или стейджинга. Документация на сайте WooCommerce содержит все необходимое для начала работы (также вы можете ознакомиться с примером тестового плагина). Помните, что эта функция поставляется с WooCommerce 10.9 и требует PHP 8.1 или более поздней версии.

Если вы хотите сообщить об ошибках или предложить улучшения, пожалуйста, перейдите в специальное обсуждение на GitHub.

У меня PHP 7! Я защищен?

Да. Весь код, специфичный для PHP 8.1, находится в классах, которые никогда не будут выполняться, если эта функция отключена или ваш сервер работает под управлением PHP 7.4 или 8.0, поэтому вы не увидите никаких ошибок, даже если попытаетесь включить эту функцию (конечная точка GraphQL просто не будет работать). Однако обратите внимание, что ничто не мешает вам использовать кодовый API WooCommerce (классы в src/Api) напрямую из кастомного плагина или сниппета; но, естественно, в этом случае вы получите ошибки в PHP 7.4 или 8.0, поскольку эти классы относятся к PHP 8.1 и выше (поэтому, пожалуйста, не делайте так).

Что касается выбора PHP 8.1, то он был обусловлен необходимостью корректного воспроизведения структур кода в виде сущностей и механизмов GraphQL для атрибутов и перечислений (enum) PHP. Мы официально рекомендуем PHP 8.1 или более поздние версии для WooCommerce, и хотя у нас пока нет четкой дорожной карты, в конечном счете мы прекратим поддержку PHP 7.4 и 8.0 (с заблаговременным уведомлением), как это было сделано с более старыми версиями; кроме того, WordPress 7.0 прекратил поддержку PHP 7.2 и 7.3, а его совместимость с PHP 8 больше не имеет статуса «beta» — так что это отличная возможность для обновления.

Источник: https://developer.woocommerce.com