GraphQL Application Server

Commerce GraphQL Application Server を使用すると、Adobe CommerceはCommerce GraphQL API リクエストの状態を維持できます。 Swoole 拡張機能に基づいて構築されたGraphQL Application Server は、リクエスト処理を処理するワーカースレッドを使用したプロセスとして動作します。 GraphQL Application Server は、GraphQL API リクエストの間でブートストラップされたアプリケーションの状態を保持することで、リクエスト処理と製品全体のパフォーマンスを向上させます。 API リクエストが大幅に効率的になります。

GraphQL Application Server は、Adobe Commerceでのみ使用できます。 Magento Open Sourceには使用できません。 Cloud Pro プロジェクトの場合、GraphQL Application Server を有効にするには、Adobe Commerce サポートを送信チケットが必要です。

アーキテクチャ

GraphQL Application Server は、Commerce GraphQL API リクエストの間のステータスを維持し、ブートストラップを不要にします。 複数のプロセスでアプリケーションのステータスを共有することで、GraphQL リクエストの効率が大幅に向上し、応答時間が最大 30% 短縮します。

共有なし PHP 実行モデルは、要求ごとにフレームワークのブートストラップが必要なため、待ち時間の観点から問題があります。 このブートストラッププロセスには、設定の読み取り、ブートストラッププロセスの設定、サービスクラスオブジェクトの作成など、時間のかかるタスクが含まれます。

リクエスト処理ロジックをアプリケーションレベルのイベントループに移行することは、エンタープライズレベルでリクエスト処理を効率化するという課題に対処するように見えます。 このアプローチにより、リクエスト実行のライフサイクル中にブートストラップを行う必要がなくなります。

メリット

GraphQL Application Server を使用すると、Adobe Commerceは、連続するCommerce GraphQL API リクエストの間にステートを維持できます。 リクエスト間でアプリケーション状態を共有すると、処理オーバーヘッドが最小限に抑えられ、リクエスト処理が最適化されるので、API リクエストの効率が向上します。 その結果、GraphQLのリクエストの応答時間を最大 30% 短縮できます。

必要システム構成

GraphQL Application Server を実行するには、以下が必要です。

クラウドインフラストラクチャでの有効化とデプロイ

ApplicationServer モジュール（Magento/ApplicationServer/）は、GraphQL Application Server を有効にします。

Pro プロジェクトの有効化

Pro プロジェクトで Application Server 機能を有効にした後、GraphQL Application Server をデプロイする前に次の手順を実行します。

Pro プロジェクトのデプロイ

イネーブルメント手順を完了したら、変更を Git リポジトリーにプッシュして、GraphQL アプリケーションサーバーをデプロイします。

git push

スタータープロジェクトの有効化

スタータープロジェクトにGraphQL アプリケーションサーバーをデプロイする前に、次の手順を実行します。

スタータープロジェクトのデプロイ

イネーブルメント 手順を完了したら、変更を Git リポジトリーにプッシュして、GraphQL Application Server をデプロイします。

git push

クラウドプロジェクトでのイネーブルメントの検証

これらの検証手順が正常に完了した場合、GraphQL Application Server は実行中で、/graphql リクエストを処理します。

オンプレミスプロジェクトの有効化

ApplicationServer モジュール（Magento/ApplicationServer/）は、GraphQL API 用のGraphQL Application Server を有効にします。

GraphQL Application Server をローカルで実行するには、Swoole 拡張機能をインストールし、デプロイメントの Nginx 設定ファイルに小さな変更を加える必要があります。

前提条件

ApplicationServer モジュールを有効にする前に、次の手順を実行します。

Nginx の設定

Commerceの具体的なデプロイメントによって、Nginx の設定方法が決まります。 一般に、Nginx 設定ファイルはデフォルトで nginx.conf という名前で、/usr/local/nginx/conf、/etc/nginx、/usr/local/etc/nginx のいずれかのディレクトリに配置されます。 Nginx の設定の詳細については、初心者向けガイド を参照してください。

Nginx 設定の例：

location /graphql {
    proxy_set_header Host $http_host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

    proxy_pass http://127.0.0.1:9501/graphql;
}

Swoole のインストールと設定

GraphQL Application Server をローカルで実行するには、Swoole 拡張機能（v5.0 以降）をインストールします。 この拡張機能をインストールする方法は複数あります。

次の手順では、OSX ベースのシステムに Swoole extension for PHP 8.2 をインストールする方法について説明します。 これは、Swoole 拡張機能をインストールする方法の 1 つです。

pecl install swoole

インストール時に、Adobe Commerceで openssl、mysqlnd、sockets、http2 および postgres のサポートを有効にするよう求められます。 postgres を除くすべてのオプションに対して yes を入力します。

Swoole のインストールの確認

拡張機能が正常に有効になったことを確認します。

php -m | grep swoole

Swoole のインストールに関するよくあるエラー

Swoole のインストール中に発生するエラーは、通常、pecl のインストール段階で発生します。 一般的なエラーには、openssl.h ファイルと pcre2.h ファイルの欠落があります。 これらのエラーを解決するには、ローカルシステムにこれらの 2 つのパッケージがインストールされていることを確認します。

openssl version -d

このコマンドは、openssl がインストールされているパスを表示します。

pcre2-config --prefix

コマンド出力にファイルが見つからないことが示されている場合は、Homebrew を使用して、見つからないパッケージをインストールします。

brew install openssl

brew install pcre2

openssl の問題を解決

openssl に関連する問題を解決するには、次を実行します。

export LDFLAGS="-L/opt/homebrew/etc/openssl@3/lib" export CPPFLAGS="-I/opt/homebrew/etc/openssl@3/include"

ローカル dev 環境からのパスを使用していることを確認します。

Openssl 関連の問題の解決の確認

次のコマンドを再度実行すると、openssl 関連の問題が解決されたかどうかを確認できます。

pecl install swoole

pcre2.h の問題を解決

pcre2.h に関連する問題を解決するには、インストールされている PHP 拡張ディレクトリに pcre2.h パスをシンボリックリンクします。 使用するコマンドの特定のバージョンは、PHP および pcr2.h の特定のインストール済みバージョンによって決まります。

GraphQL Application Server の実行

GraphQL Application Server を起動します。

bin/magento server:run

このコマンドは、9501 で HTTP ポートを開始します。 GraphQL Application Server が起動すると、ポート 9501 はすべてのGraphQL クエリの HTTP プロキシサーバーになります。

デプロイメントでGraphQL Application Server が実行中であることを確認するには：

ps aux | grep php

GraphQL Application Server が実行中であることを確認するその他の方法を次に示します。

GraphQL リクエストが処理中であることを確認します

GraphQL Application Server は、処理する各リクエストに graphql_server 値を持つ X-Backend 応答ヘッダーを追加します。 GraphQL Application Server がリクエストを処理したかどうかを確認するには、この応答ヘッダーを確認します。

拡張機能とカスタマイズの互換性の確認

拡張機能の開発者とマーチャントは、まず、拡張機能とカスタマイズコードが テクニカルガイドライン に記載されたガイドラインに従っていることを確認する必要があります。

コード評価時には、次のガイドラインを考慮してください。

GraphQL Application Server の無効化

GraphQL Application Server を無効にする手順は、サーバーがオンプレミスとクラウドのどちらのデプロイメントで実行されているかによって異なります。

GraphQL Application Server （Cloud）を無効にする

GraphQL Application Server を無効にする（オンプレミス）

GraphQL Application Server を無効にするこの方法は、パフォーマンスを迅速にテストまたは比較するのに役立ちます。

GraphQL Application Server が無効になっていることを確認します。

php-fpm がGraphQL Application Server ではなくGraphQL リクエストを処理していることを確認するには、コマンド ps aux | grep php を入力します。

GraphQL Application Server が無効になった後：

GraphQL Application Server の統合および機能テスト

拡張機能の開発者は、2 つの統合テスト（GraphQlStateTest および ResetAfterRequestTest）を実行して、GraphQL Application Server との拡張機能の互換性を確認できます。

GraphQlStateTest

GraphQlStateTest は、複数のリクエストで再利用してはいけない共有オブジェクトの状態を検出します。

このテストの目的は、ObjectManager で生成されるサービスオブジェクトの状態変化を検出することです。 このテストでは、同一のGraphQL クエリを 2 回実行し、2 回目のクエリの前後でサービスオブジェクトのステートを比較します。

GraphQlStateTest の失敗と潜在的な修正

vendor/bin/phpunit -c $(pwd)/dev/tests/integration/phpunit.xml dev/tests/integration/testsuite/Magento/GraphQl/App/GraphQlStateTest.php を実行して GraphQlStateTest を実行します。

ResetAfterRequestTest

この ResetAfterRequestTest は、ResetAfterRequestInterface を実装するすべてのクラスを検索し、_resetState() メソッドが ObjectManager によって構築された後に保持したのと同じ状態にオブジェクトの状態を返すことを確認します。  このテストでは、ObjectManager でサービスオブジェクトを作成してから、そのオブジェクトを複製し、_resetState() を呼び出して、両方のオブジェクトを比較します。 このテストでは、オブジェクトのインスタンス化と _resetState() の間でメソッドは呼び出されないので、可変状態のリセットは確認されません。 _resetState() のバグやタイプミスによって元の状態とは異なる状態に設定される可能性がある問題を見つけることができます。

ResetAfterRequestTest エラーと修復の可能性

機能テスト

GraphQL Application Server のデプロイ中に、拡張機能の開発者は、WebAPI 機能テストと、GraphQLのカスタム自動または手動の機能テストを実行する必要があります。 これらの機能テストは、開発者が潜在的なエラーや互換性の問題を特定するのに役立ちます。

状態監視モード

機能テスト（または手動テスト）の実行中に、GraphQL Application Server を --state-monitor mode を有効にして実行すると、ステートが意図せずに再利用されているクラスを見つけることができます。 --state-monitor パラメーターの追加を除き、アプリケーションサーバーを通常どおり起動します。

bin/magento server:run --state-monitor

各リクエストが処理されると、新しいファイルが tmp ディレクトリに追加されます（例：var/tmp/StateMonitor-thread-output-50-6nmxiK）。 テストが完了したら、これらのファイルは bin/magento server:state-monitor:aggregate-output コマンドを使用して結合でき、XML と JSON の 2 つの結合ファイルが作成されます。

例：

/var/workspace/var/tmp/StateMonitor-json-2024-04-10T18:50:39Z-hW0ucN.json
/var/workspace/var/tmp/StateMonitor-junit-2024-04-10T18:50:39Z-oreUco.xml

これらのファイルは、GraphQlStateTest のようなサービスオブジェクトの変更されたプロパティを表示する XML または JSON の表示に使用する任意のツールを使用して調べることができます。 --state-monitor モードでは、GraphQlStateTest と同じスキップリストとフィルターリストを使用します。