GraphQL應用程式伺服器

Commerce GraphQL應用程式伺服器可讓Adobe Commerce維護Commerce GraphQL API請求中的狀態。 GraphQL Application Server （以Swoole擴充功能為基礎）會以具有工作者執行緒的處理程式方式運作，以處理要求處理。 GraphQL Application Server可保留GraphQL API請求中的啟動載入應用程式狀態，藉此增強請求處理和整體產品效能。 API要求會大幅提高效率。

GraphQL Application Server僅適用於Adobe Commerce。 它無法用於Magento Open Source。 對於Cloud Pro專案，您必須提交Adobe Commerce支援票證，才能啟用GraphQL應用程式伺服器。

架構

GraphQL Application Server可維護Commerce GraphQL API請求之間的狀態，且無需啟動程式。 藉由跨程式共用應用程式狀態，GraphQL要求可大幅提高效率，最多將回應時間減少30%。

從延遲的角度來看，無共用PHP執行模型是一個挑戰，因為每個請求都需要架構的啟動安裝。 此啟動載入程式包括耗時的工作，例如讀取組態、設定啟動載入程式，以及建立服務類別物件。

將請求處理邏輯轉換為應用程式層級的事件回圈，似乎可解決在企業層級精簡請求處理的挑戰。 此方法可免除在請求執行生命週期期間進行啟動載入的需求。

優點

GraphQL應用程式伺服器可讓Adobe Commerce在連續的Commerce GraphQL API請求之間維持狀態。 跨請求共用應用程式狀態透過最小化處理開銷和最佳化請求處理來增強API請求效率。 因此，GraphQL要求回應時間最多可減少30%。

系統需求

執行GraphQL Application Server需要下列專案：

在雲端基礎結構上啟用和部署

ApplicationServer模組(Magento/ApplicationServer/)啟用GraphQL應用程式伺服器。

啟用Pro專案

在Pro專案上啟用「應用程式伺服器」功能後，請先完成下列步驟，再部署GraphQL Application Server：

部署Pro專案

完成啟用步驟後，將變更推送至您的Git存放庫以部署GraphQL應用程式伺服器：

git push

啟用入門專案

在入門專案上部署GraphQL Application Server前，請先完成下列步驟：

部署入門專案

完成啟用步驟後，將變更推送至您的Git存放庫以部署GraphQL應用程式伺服器：

git push

驗證雲端專案是否啟用

如果這些驗證步驟成功，GraphQL Application Server就會執行並提供/graphql要求。

啟用內部部署專案

ApplicationServer模組(Magento/ApplicationServer/)可為GraphQL API啟用GraphQL應用程式伺服器。

在本機執行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;
}

安裝和設定Swool

若要在本機執行GraphQL Application Server，請安裝Swoole擴充功能（v5.0或更新版本）。 有多種方式可安裝此擴充功能。

下列程式說明如何在OSX系統上安裝PHP 8.2的Swoole擴充功能。 這是安裝Swoole擴充功能的數種方式之一。

pecl install swoole

在安裝期間，Adobe Commerce會顯示提示以啟用openssl、mysqlnd、sockets、http2和postgres的支援。 輸入yes以取得除postgres以外的所有選項。

驗證Swool安裝

確認擴充功能已成功啟用：

php -m | grep swoole

Swoole安裝的常見錯誤

在Swoole安裝期間發生的任何錯誤通常發生在pecl安裝階段。 典型的錯誤包括遺失openssl.h和pcre2.h檔案。 若要解決這些錯誤，請確定這兩個套件已安裝在您的本機系統中。

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相關的問題，請將pcre2.h路徑同步連結到您安裝的PHP延伸模組目錄。 您安裝的特定版本PHP和pcr2.h決定了您應該使用的指令的特定版本。

執行GraphQL應用程式伺服器

啟動GraphQL應用程式伺服器：

bin/magento server:run

這個指令會在9501上啟動HTTP連線埠。 GraphQL應用程式伺服器啟動後，連線埠9501就會變成所有GraphQL查詢的HTTP Proxy伺服器。

若要確認GraphQL Application Server正在您的部署中執行：

ps aux | grep php

確認GraphQL Application Server正在執行的其他方法包括：

確認正在處理GraphQL請求

GraphQL Application Server將值為graphql_server的X-Backend回應標頭新增至其處理的每個要求。 若要檢查GraphQL應用程式伺服器是否已處理要求，請檢查此回應標頭。

確認擴充功能和自訂相容性

擴充功能開發人員和商家應該先確認其擴充功能和自訂程式碼符合​ 技術准則 ​中所述的准則。

在程式碼評估期間請考量下列准則：

停用GraphQL應用程式伺服器

停用GraphQL Application Server的程式會因伺服器是在內部部署或雲端部署中執行而有所不同。

停用GraphQL Application Server （雲端）

停用GraphQL應用程式伺服器（內部部署）

此停用GraphQL應用程式伺服器的方法有助於快速測試或比較效能。

確認GraphQL Application Server已停用

若要確認php-fpm正在處理GraphQL要求而非GraphQL應用程式伺服器，請輸入以下命令： ps aux | grep php。

停用GraphQL Application Server之後：

GraphQL Application Server的整合和功能測試

擴充功能開發人員可執行兩項整合測試，以驗證與GraphQL Application Server的擴充功能相容性： GraphQlStateTest和ResetAfterRequestTest。

GraphQlStateTest

GraphQlStateTest會偵測共用物件中不應重複用於多個要求的狀態。

此測試的目的是偵測ObjectManager產生的服務物件中的狀態變更。 此測試會執行兩次相同的GraphQL查詢，並比較第二次查詢前後的服務物件狀態。

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。

範例：

/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

您可以使用檢視XML或JSON的任何工具來檢查這些檔案，這些工具會顯示GraphQlStateTest等服務物件的修改屬性。 --state-monitor模式使用與GraphQlStateTest相同的略過清單和篩選清單。