DocumentazioneCommerceBest practice per le prestazioni

Server applicazioni GraphQL

Last update: Tue May 07 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

Creato per:

  • Esperto
  • Amministratore
  • Sviluppatore

Il server applicazioni Commerce GraphQL consente ad Adobe Commerce di mantenere lo stato tra le richieste API di Commerce GraphQL. GraphQL Application Server, basato sull'estensione Swoole, funziona come un processo con thread di lavoro che gestiscono l'elaborazione delle richieste. Mantenendo uno stato di applicazione avviato tra le richieste API di GraphQL, GraphQL Application Server migliora la gestione delle richieste e le prestazioni complessive del prodotto. Le richieste API diventano notevolmente più efficienti.

GraphQL Application Server è disponibile solo per Adobe Commerce. Non è disponibile per il Magento Open Source. Devi inviare un messaggio di supporto Adobe Commerce ticket per abilitare GraphQL Application Server sui progetti Pro.

NOTE
GraphQL Application Server non è attualmente compatibile con Amazon Simple Storage Service (AWS S3). I clienti di Adobe Commerce su infrastruttura cloud attualmente utilizzano AWS S3 per archiviazione remota non può utilizzare GraphQL Application Server finché Adobe non rilascia un hotfix più tardi nel 2024.

Architettura

GraphQL Application Server mantiene lo stato tra le richieste API di Commerce GraphQL ed elimina la necessità di avviare il sistema. La condivisione dello stato dell'applicazione tra i processi rende le richieste GraphQL notevolmente più efficienti e riduce i tempi di risposta fino al 30%.

Il modello di esecuzione PHP senza condivisione rappresenta una sfida dal punto di vista della latenza, in quanto ogni richiesta richiede l’avvio automatico del framework. Questo processo di bootstrap include attività che richiedono tempo, ad esempio la configurazione della lettura, l'impostazione del processo di bootstrap e la creazione di oggetti della classe di servizio.

La transizione della logica di gestione delle richieste a un ciclo di eventi a livello di applicazione sembra rispondere alla sfida di semplificare l’elaborazione delle richieste a livello aziendale. Questo approccio elimina la necessità di bootstrap durante il ciclo di vita di esecuzione delle richieste.

Vantaggi

GraphQL Application Server consente ad Adobe Commerce di mantenere lo stato tra richieste API consecutive di Commerce GraphQL. La condivisione dello stato dell’applicazione tra le richieste migliora l’efficienza delle richieste API riducendo al minimo il sovraccarico di elaborazione e ottimizzando la gestione delle richieste. Di conseguenza, il tempo di risposta alle richieste di GraphQL può essere ridotto fino al 30%.

Requisiti di sistema

L'esecuzione di GraphQL Application Server richiede quanto segue:

  • PHP 8.2 o superiore
  • Estensione PHP Swoole v5+ installata
  • RAM e CPU adeguate in base al carico previsto

Abilitare e distribuire su infrastruttura cloud

Il ApplicationServer modulo (Magento/ApplicationServer/) abilita GraphQL Application Server.

Abilita progetti Pro

NOTE
Il server applicazioni è una funzione di consenso nelle istanze di Cloud Pro. Per abilitarlo, invia una richiesta di supporto.

Dopo aver attivato la funzionalità Application Server nel progetto Pro, completare i passaggi seguenti prima di distribuire GraphQL Application Server:

  1. Distribuire Adobe Commerce sull’infrastruttura cloud utilizzando il modello cloud di Ramo 2.4.7-appserver.

  2. Assicurati che tutte le personalizzazioni ed estensioni di Commerce siano compatibile con GraphQL Application Server.

  3. Clona il progetto Commerce Cloud.

  4. Se necessario, regola le impostazioni nel file application-server/nginx.conf.sample.

  5. Commenta la sezione "web" attiva in project_root/.magento.app.yaml interamente.

  6. Rimuovi il commento dalla seguente configurazione di sezione "web" in project_root/.magento.app.yaml file che include GraphQL Application Server start comando.

    code language-yaml 
    web:
    upstream:
        socket_family: tcp
        protocol: http
    commands:
        start: ./application-server/start.sh > var/log/application-server-status.log 2>&1

  7. Aggiungi i file aggiornati all’indice Git con questo comando:

    code language-bash 
    git add -f .magento.app.yaml application-server/*

  8. Esegui il commit delle modifiche con questo comando:

    code language-bash 
    git commit -m "AppServer Enabled"

Distribuire progetti Pro

Dopo aver completato i passaggi di abilitazione, invia le modifiche all’archivio Git per distribuire GraphQL Application Server:

git push

Abilita progetti iniziali

Prima di distribuire GraphQL Application Server su progetti iniziali, effettuare le operazioni riportate di seguito.

  1. Distribuire Adobe Commerce sull’infrastruttura cloud utilizzando il modello cloud di Ramo 2.4.7-appserver.

  2. Assicurati che tutte le personalizzazioni ed estensioni Commerce siano compatibili con GraphQL Application Server.

  3. Confermare che CRYPT_KEY la variabile di ambiente è impostata per l’istanza. Puoi controllare lo stato di questa variabile sul Cloud Project Portal (Interfaccia utente di onboarding).

  4. Clona il progetto Commerce Cloud.

  5. Rinomina application-server/.magento/.magento.app.yaml.sample a application-server/.magento/.magento.app.yaml e, se necessario, regola le impostazioni in .magento.app.yaml.

  6. Rimuovi commento dalla configurazione della route seguente in project_root/.magento/routes.yaml file da reindirizzare /graphql traffico verso GraphQL Application Server.

    code language-yaml 
    "http://{all}/graphql":
    type: upstream
    upstream: "application-server:http"

  7. Aggiungi file aggiornati all’indice Git:

    code language-bash 
    git add -f .magento/routes.yaml application-server/.magento/*

  8. Eseguire il commit delle modifiche:

    code language-bash 
    git commit -m "AppServer Enabled"
NOTE
Verifica che tutte le impostazioni personalizzate nella directory principale .magento.app.yaml i file vengono migrati in modo appropriato al application-server/.magento/.magento.app.yaml file. Dopo il application-server/.magento/.magento.app.yaml aggiunta al progetto, è necessario gestirla oltre alla directory principale .magento.app.yaml file. Ad esempio, se devi configura rabbitmq o gestire le proprietà web devi aggiungere la stessa configurazione a application-server/.magento/.magento.app.yaml anche.

Distribuire progetti iniziali

Dopo aver completato l’abilitazione passaggi, invia le modifiche all’archivio Git per distribuire GraphQL Application Server:

git push

Verificare l’abilitazione nei progetti cloud

  1. Esegui una query GraphQL o una mutazione rispetto all’istanza per confermare che graphql endpoint accessibile. Ad esempio:

    code language-none 
    mutation {
 createEmptyCart
}

    La risposta prevista dovrebbe essere simile a questo esempio:

    code language-terminal 
    {
 "data": {
     "createEmptyCart": "HLATPzcLw5ylDf76IC92nxdO2hXSXOrv"
     }
 }

  2. Utilizza SSH per accedere alla tua istanza cloud. Il project_root/var/log/application-server.log deve contenere un nuovo record di registro per ogni richiesta GraphQL.

  3. È inoltre possibile verificare se GraphQL Application Server è in esecuzione eseguendo il comando seguente:

    code language-bash 
    ps aux|grep php

    Dovresti vedere un bin/magento server:run processo con più thread.

Se questi passaggi di verifica hanno esito positivo, GraphQL Application Server è in esecuzione /graphql richieste.

Abilita progetti locali

Il ApplicationServer modulo (Magento/ApplicationServer/) abilita le API di GraphQL Application Server per GraphQL.

L'esecuzione locale di GraphQL Application Server richiede l'installazione dell'estensione Swoole e una modifica minore al file di configurazione Nginx della distribuzione.

Prerequisiti

Completa i passaggi seguenti prima di abilitare ApplicationServer modulo:

  • Configurare Nginx
  • Installare e configurare l’estensione Swoole v5+

Configurare Nginx

La tua specifica implementazione di Commerce determina come configurare Nginx. In generale, il file di configurazione di Nginx è denominato per impostazione predefinita nginx.conf e si trova in una delle seguenti directory: /usr/local/nginx/conf, /etc/nginx, o /usr/local/etc/nginx. Consulta Guida per principianti per ulteriori informazioni sulla configurazione di Nginx.

Esempio di configurazione di 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;
}

Installare e configurare Swoole

Per eseguire GraphQL Application Server localmente, installare l'estensione Swoole (v5.0 o successiva). Esistono diversi modi per installare questa estensione.

La procedura seguente descrive come installare l’estensione Swoole per PHP 8.2 su sistemi basati su OSX. Si tratta di uno dei diversi modi per installare l’estensione Swoole.

pecl install swoole

Durante l’installazione, Adobe Commerce visualizza le richieste per abilitare il supporto per openssl, mysqlnd, sockets, http2, e postgres. Invio yes per tutte le opzioni eccetto postgres.

Verifica installazione Swoole

Conferma che l'estensione sia stata abilitata correttamente:

php -m | grep swoole

Errori comuni con l’installazione di Swoole

Eventuali errori che si verificano durante l’installazione di Swoole si verificano in genere durante pecl fase di installazione. Gli errori tipici includono mancanti openssl.h e pcre2.h file. Per risolvere questi errori, accertati che questi due pacchetti siano installati nel sistema locale.

  • Controlla la posizione di openssl eseguendo:
openssl version -d

Questo comando mostra il percorso in cui openssl è installato.

  • Controlla la posizione di pcre2 eseguendo:
pcre2-config --prefix

Utilizzare Homebrew per installare i pacchetti mancanti se l'output del comando indica che mancano file:

brew install openssl

brew install pcre2

Risolvere i problemi con openssl

Per risolvere i problemi relativi a openssl, esegui:

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

Conferma di utilizzare il percorso dal tuo dev ambiente.

Conferma la risoluzione dei problemi correlati a openssl

È possibile eseguire nuovamente il comando seguente per verificare se i problemi correlati a openssl sono stati risolti:

pecl install swoole

Risolvere i problemi relativi a pcre2.h

Per risolvere i problemi relativi a pcre2.h, collegano simbolicamente il pcre2.h percorso della directory dell'estensione PHP installata. La versione specifica installata di PHP e pcr2.h determina la versione specifica del comando da utilizzare.

Esegui server applicazioni GraphQL

Avvia GraphQL Application Server:

bin/magento server:run

Questo comando avvia una porta HTTP su 9501. Dopo l'avvio di GraphQL Application Server, la porta 9501 diventa un server proxy HTTP per tutte le query GraphQL.

Per verificare che GraphQL Application Server sia in esecuzione nella distribuzione:

ps aux | grep php

Altri metodi per verificare che GraphQL Application Server sia in esecuzione includono:

  • Controlla la /var/log/application-server.log file per le voci correlate alle richieste GraphQL elaborate.
  • Provare a connettersi alla porta HTTP su cui viene eseguito GraphQL Application Server. Ad esempio: curl -g 'http://localhost:9501/graph.

Conferma l’elaborazione delle richieste GraphQL

GraphQL Application Server aggiunge X-Backend intestazione di risposta con il valore graphql_server a ogni richiesta elaborata. Per verificare se una richiesta è stata gestita da GraphQL Application Server, controllare questa intestazione di risposta.

Conferma compatibilità di estensione e personalizzazione

Gli sviluppatori e i commercianti di estensioni devono prima verificare che il loro codice di estensione e personalizzazione sia conforme alle linee guida tecniche descritte in Linee guida tecniche.

Considera queste linee guida durante la valutazione del codice:

  • Classi di servizio (ovvero classi che forniscono il comportamento ma non i dati, ad esempio EventManager) non deve avere uno stato mutabile.
  • Evitare l'accoppiamento temporale.

Disabilita server applicazioni GraphQL

Le procedure per la disattivazione di GraphQL Application Server variano a seconda che il server sia in esecuzione in una distribuzione locale o cloud.

Disabilita server applicazioni GraphQL (cloud)

  1. Rimuovi eventuali nuovi file e altre modifiche al codice inclusi nel AppServer Enabled esegui il commit durante i preparativi per l’implementazione.

  2. Eseguire il commit delle modifiche utilizzando questo comando:

    code language-bash 
    git commit -m "AppServer Disabled"

  3. Distribuisci le modifiche utilizzando questo comando:

    code language-bash 
    git push

Disabilita GraphQL Application Server (locale)

  1. Commenta il /graphql sezione di nginx.conf file aggiunto quando si abilita GraphQL Application Server.
  2. Riavvia indice.

Questo metodo di disattivazione di GraphQL Application Server può essere utile per testare o confrontare rapidamente le prestazioni.

Verificare che GraphQL Application Server sia disabilitato

Per confermare che le richieste GraphQL vengono elaborate da php-fpm anziché GraphQL Application Server, immettere il comando seguente: ps aux | grep php.

Dopo aver disabilitato GraphQL Application Server:

  • bin/magento server:run è inattivo.
  • var/log/application-server.log non contiene voci dopo le richieste di GraphQL.

Integrazione e test funzionali per GraphQL Application Server

Gli sviluppatori di estensioni possono eseguire due integration test per verificare la compatibilità delle estensioni con GraphQL Application Server: GraphQlStateTest e ResetAfterRequestTest.

GraphQlStateTest

GraphQlStateTest rileva lo stato negli oggetti condivisi che non devono essere riutilizzati per più richieste.

Questo test è progettato per rilevare le modifiche dello stato negli oggetti del servizio prodotti da ObjectManager. Il test esegue due volte query GraphQL identiche e confronta lo stato dell'oggetto servizio prima e dopo la seconda query.

Errori GraphQlStateTest e potenziale correzione

  • Impossibile aggiungere, saltare o filtrare un elenco. Se si verifica un errore che indica che non è sicuro aggiungere, saltare o filtrare un elenco, valutare se è possibile eseguire il refactoring della classe in modo compatibile con le versioni precedenti per utilizzare le factory delle classi di servizio con stato mutabile.

  • La classe presenta uno stato mutabile. Se la classe stessa presenta uno stato mutabile, prova a riscrivere il codice per aggirare questo stato. Se per motivi di prestazioni è necessario lo stato mutabile, implementa ResetAfterRequestInterface e utilizzare _resetState() per ripristinare lo stato di costruzione iniziale dell'oggetto.

  • Impossibile accedere alla proprietà digitata $x prima del messaggio di inizializzazione. Errori con questo tipo di messaggio indicano che la proprietà specificata non è stata inizializzata dal costruttore. Si tratta di una forma di accoppiamento temporale che si verifica perché l'oggetto non può essere utilizzato dopo che è stato inizialmente costruito. Questo accoppiamento si verifica anche se la proprietà è privata perché l’agente di raccolta che recupera i dati dalle proprietà utilizza la funzione di riflessione PHP. In questo caso, provare a rieseguire il factoring della classe per evitare l'accoppiamento temporale e lo stato mutabile. Se il refactoring non risolve l'errore, è possibile modificare il tipo di proprietà in un tipo nullable in modo che possa essere inizializzato in null.  Se la proprietà è un array, provare a inizializzarla come array vuoto.

Esegui GraphQlStateTest eseguendo vendor/bin/phpunit -c $(pwd)/dev/tests/integration/phpunit.xml dev/tests/integration/testsuite/Magento/GraphQl/App/GraphQlStateTest.php.

ResetAfterRequestTest

ResetAfterRequestTest cerca tutte le classi che implementano ResetAfterRequestInterface e verifica che _resetState() il metodo restituisce lo stato di un oggetto allo stesso stato che aveva dopo essere stato costruito da ObjectManager.  Questo test crea un oggetto servizio con ObjectManager, quindi clona tale oggetto, chiama _resetState()e quindi confronta entrambi gli oggetti. Il test non chiama alcun metodo tra la creazione di istanze di oggetti e _resetState(), pertanto non conferma il ripristino di alcuno stato mutabile. Trova problemi quando un bug o un errore di battitura in _resetState() può impostare lo stato su un valore diverso da quello originale.

Errori ResetAfterRequestTest e potenziale correzione

  • La classe presenta valori di proprietà incoerenti. Se il test ha esito negativo, verificare se una classe è stata modificata con il risultato che l'oggetto dopo la costruzione ha valori di proprietà diversi rispetto a quelli dopo la _resetState() viene chiamato il metodo. Se la classe su cui stai lavorando non contiene _resetState() nella gerarchia di classi per individuare una superclasse che la implementa.

  • Impossibile accedere alla proprietà digitata $x prima del messaggio di inizializzazione. Questo problema si verifica anche con GraphQlStateTest.

    Esegui ResetAfterRequestTest eseguendo: vendor/bin/phpunit -c $(pwd)/dev/tests/integration/phpunit.xml dev/tests/integration/testsuite/Magento/Framework/ObjectManager/ResetAfterRequestTest.php.

Test funzionali

Durante la distribuzione di GraphQL Application Server, gli sviluppatori di estensioni devono eseguire test funzionali WebAPI per GraphQL, nonché eventuali test funzionali personalizzati automatizzati o manuali per GraphQL. Questi test funzionali aiutano gli sviluppatori a identificare potenziali errori o problemi di compatibilità.

Modalità di monitoraggio stato

Durante l'esecuzione dei test funzionali (o manuali), il server applicazioni può essere eseguito con --state-monitor mode è abilitata per aiutare a trovare le classi in cui lo stato viene riutilizzato involontariamente. Avviare l'Application Server normalmente, ad eccezione dell'aggiunta di --state-monitor parametro.

bin/magento server:run --state-monitor

Dopo l’elaborazione di ogni richiesta, viene aggiunto un nuovo file alla tmp ad esempio: var/tmp/StateMonitor-thread-output-50-6nmxiK. Al termine del test, questi file possono essere uniti con bin/magento server:state-monitor:aggregate-output che crea due file uniti, uno in XML e uno su JSON.

Esempi:

/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

Questi file possono essere esaminati con qualsiasi strumento utilizzato per visualizzare XML o JSON, che mostrerà le proprietà modificate degli oggetti di servizio come GraphQlStateTest. Il --state-monitor La modalità utilizza lo stesso elenco di salto e lo stesso elenco di filtri di GraphQlStateTest.

NOTE
Non utilizzare il --state-monitor in produzione. È progettato solo per lo sviluppo e il testing. Crea molti file di output e viene eseguito più lentamente del normale.
NOTE
--state-monitor non è compatibile con le versioni PHP 8.3.0 - 8.3.4 a causa di un bug nel Garbage Collector PHP. Se si utilizza PHP 8.3, è necessario eseguire l'aggiornamento a 8.3.5 o più recente per utilizzare questa funzione.
recommendation-more-help
c0c5bbed-4957-4162-81bc-120c837a1894