DocumentaciónCommercePrácticas recomendadas de rendimiento

GraphQL Application Server

Last update: Tue Nov 12 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

Creado para:

  • Experimentado
  • Administrador
  • Desarrollador

Commerce GraphQL Application Server permite a Adobe Commerce mantener el estado entre las solicitudes de API de Commerce GraphQL. GraphQL Application Server, que se basa en la extensión Swoole, funciona como un proceso con subprocesos de trabajo que administran el procesamiento de solicitudes. Al preservar un estado de aplicación de arranque entre las solicitudes de API de GraphQL, GraphQL Application Server mejora la gestión de solicitudes y el rendimiento general del producto. Las solicitudes de API son mucho más eficientes.

GraphQL Application Server solo está disponible para Adobe Commerce. No está disponible para el Magento Open Source. Para los proyectos de Cloud Pro, debe enviar un vale de soporte técnico de Adobe Commerce para habilitar el servidor de aplicaciones de GraphQL.

NOTE
GraphQL Application Server no es compatible actualmente con Amazon Simple Storage Service (AWS S3). Los clientes de Adobe Commerce en la infraestructura en la nube que actualmente usan AWS S3 para almacenamiento remoto no pueden usar GraphQL Application Server hasta que Adobe publique una revisión más adelante en 2024.

Arquitectura

El servidor de aplicaciones de GraphQL mantiene el estado entre las solicitudes de API de GraphQL de Commerce y elimina la necesidad del arranque. Al compartir el estado de la aplicación entre procesos, las solicitudes de GraphQL se vuelven considerablemente más eficientes, lo que reduce los tiempos de respuesta en hasta un 30 %.

El modelo de ejecución de PHP que no comparte nada proporciona un desafío desde la perspectiva de la latencia porque cada solicitud requiere el arranque del marco de trabajo. Este proceso de arranque incluye tareas que llevan mucho tiempo, como leer la configuración, configurar el proceso de arranque y crear objetos de clase de servicio.

La transición de la lógica de gestión de solicitudes a un bucle de eventos de nivel de aplicación parece abordar el desafío de racionalizar el procesamiento de solicitudes a nivel empresarial. Este método elimina la necesidad del arranque durante el ciclo de vida de la ejecución de la solicitud.

Ventajas

El servidor de aplicaciones de GraphQL permite que Adobe Commerce mantenga el estado entre solicitudes consecutivas de la API de Commerce GraphQL. Compartir el estado de la aplicación entre solicitudes mejora la eficacia de las solicitudes de API al minimizar la sobrecarga de procesamiento y optimizar la administración de solicitudes. Como resultado, el tiempo de respuesta de las solicitudes de GraphQL se puede reducir hasta en un 30 %.

Requisitos del sistema

La ejecución de GraphQL Application Server requiere lo siguiente:

  • Commerce versión 2.4.7+
  • PHP 8.2 o superior
  • Instalación de la extensión PHP v5+
  • RAM y CPU adecuadas en función de la carga esperada

Habilitar e implementar en la infraestructura en la nube

El módulo ApplicationServer (Magento/ApplicationServer/) habilita GraphQL Application Server.

Activar proyectos Pro

NOTE
El servidor de aplicaciones es una función de inclusión en instancias de Cloud Pro. Para habilitarlo, envíe una solicitud de asistencia.

Una vez habilitada la función Servidor de aplicaciones en el proyecto Pro, complete los siguientes pasos antes de implementar GraphQL Application Server:

  1. Implemente Adobe Commerce en la infraestructura de la nube mediante la plantilla de la nube desde la rama 2.4.7-appserver.

  2. Asegúrese de que todas las personalizaciones y extensiones de Commerce sean compatibles con GraphQL Application Server.

  3. Clone el proyecto de Commerce Cloud.

  4. Ajuste la configuración en el archivo "application-server/nginx.conf.sample" si es necesario.

  5. Comente completamente la sección "web" activa en el archivo project_root/.magento.app.yaml.

  6. Elimine los comentarios de la siguiente configuración de sección "web" en el archivo project_root/.magento.app.yaml que incluye el comando start del servidor de aplicaciones de GraphQL.

    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. Asegúrese de que /application-server/start.sh sea ejecutable ejecutando el siguiente comando:

    code language-bash 
    chmod +x application-server/start.sh

  8. Añada archivos actualizados al índice de Git con este comando:

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

  9. Confirme los cambios con este comando:

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

Implementación de proyectos Pro

Después de completar los pasos de activación, inserte los cambios en el repositorio de Git para implementar GraphQL Application Server:

git push

Habilitar proyectos iniciales

Complete los siguientes pasos antes de implementar GraphQL Application Server en proyectos iniciales:

  1. Implemente Adobe Commerce en la infraestructura de la nube mediante la plantilla de la nube desde la rama 2.4.7-appserver.

  2. Asegúrese de que todas las personalizaciones y extensiones de Commerce sean compatibles con GraphQL Application Server.

  3. Confirme que la variable de entorno CRYPT_KEY esté configurada para su instancia. Puede comprobar el estado de esta variable en la consola de Cloud.

  4. Clone el proyecto de Commerce Cloud.

  5. Cambie el nombre de application-server/.magento/.magento.app.yaml.sample a application-server/.magento/.magento.app.yaml y ajuste la configuración en .magento.app.yaml si es necesario.

  6. Elimine los comentarios de la configuración de la siguiente ruta en el archivo project_root/.magento/routes.yaml para redirigir el tráfico de /graphql a GraphQL Application Server.

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

  7. Añada archivos actualizados al índice de Git:

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

  8. Confirme los cambios:

    code language-bash 
    git commit -m "AppServer Enabled"
NOTE
Asegúrese de que todas las configuraciones personalizadas del archivo raíz .magento.app.yaml se migren correctamente al archivo application-server/.magento/.magento.app.yaml. Una vez agregado el archivo application-server/.magento/.magento.app.yaml al proyecto, debe mantenerlo además del archivo raíz .magento.app.yaml. Por ejemplo, si necesita configurar el servicio RabbitMQ o administrar propiedades web, también debe agregar la misma configuración a application-server/.magento/.magento.app.yaml.

Implementar proyectos iniciales

Después de completar los pasos de habilitación, inserte los cambios en el repositorio Git para implementar GraphQL Application Server:

git push

Verificar la habilitación en proyectos en la nube

  1. Realice una consulta o mutación de GraphQL en la instancia para confirmar que el extremo graphql es accesible. Por ejemplo:

    code language-none 
    mutation {
 createEmptyCart
}

    La respuesta esperada debe ser similar a este ejemplo:

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

  2. Utilice SSH para acceder a su instancia de Cloud. project_root/var/log/application-server.log debe contener un nuevo registro para cada solicitud de GraphQL.

  3. También puede comprobar si GraphQL Application Server se está ejecutando ejecutando el siguiente comando:

    code language-bash 
    ps aux|grep php

    Debería ver un proceso bin/magento server:run con varios subprocesos.

Si estos pasos de comprobación se realizan correctamente, GraphQL Application Server se está ejecutando y está sirviendo /graphql solicitudes.

Habilitar proyectos locales

El módulo ApplicationServer (Magento/ApplicationServer/) habilita GraphQL Application Server para las API de GraphQL.

La ejecución de GraphQL Application Server localmente requiere la instalación de la extensión Swoole y un cambio menor en el archivo de configuración Nginx de la implementación.

Requisitos previos

Complete los siguientes pasos antes de habilitar el módulo ApplicationServer:

  • Configuración De Nginx
  • Instale y configure la extensión de Swoole v5+

Configuración De Nginx

Su implementación específica de Commerce determina cómo configurar Nginx. En general, el archivo de configuración Nginx se denomina de forma predeterminada nginx.conf y se coloca en uno de estos directorios: /usr/local/nginx/conf, /etc/nginx o /usr/local/etc/nginx. Consulte la Guía para principiantes para obtener más información sobre cómo configurar Nginx.

Ejemplo de configuración de 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;
}

Instalar y configurar Swoole

Para ejecutar GraphQL Application Server localmente, instale la extensión Swoole (v5.0 o superior). Existen varias formas de instalar esta extensión.

El siguiente procedimiento describe cómo instalar la extensión Swoole para PHP 8.2 en sistemas basados en OSX. Es una de las varias formas de instalar la extensión Swoole.

pecl install swoole

Durante la instalación, Adobe Commerce muestra mensajes para habilitar la compatibilidad con openssl, mysqlnd, sockets, http2 y postgres. Escriba yes para todas las opciones excepto postgres.

Verificar instalación de Swoole

Confirme que la extensión se ha habilitado correctamente:

php -m | grep swoole

Errores comunes con la instalación de Swoole

Los errores que se producen durante la instalación de Swoole suelen producirse durante la fase de instalación de pecl. Los errores habituales incluyen la falta de openssl.h y pcre2.h archivos. Para resolver estos errores, asegúrese de que estos dos paquetes estén instalados en el sistema local.

  • Compruebe la ubicación de openssl ejecutando:
openssl version -d

Este comando muestra la ruta de acceso donde está instalado openssl.

  • Compruebe la ubicación de pcre2 ejecutando:
pcre2-config --prefix

Utilice Homebrew para instalar los paquetes que faltan si la salida del comando indica que faltan archivos:

brew install openssl

brew install pcre2

Resolver problemas con openssl

Para resolver problemas relacionados con openssl, ejecute:

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

Confirme que está utilizando la ruta de acceso desde el entorno local dev.

Confirmar la resolución de los problemas relacionados con openssl

Puede ejecutar de nuevo el siguiente comando para comprobar si se han resuelto los problemas relacionados con openssl:

pecl install swoole

Solución de problemas con pcre2.h

Para resolver problemas relacionados con pcre2.h, vincule simbólicamente la ruta de acceso pcre2.h al directorio de extensión PHP instalado. Su versión instalada específica de PHP y pcr2.h determina la versión concreta del comando que debe utilizar.

Ejecutar GraphQL Application Server

Inicie GraphQL Application Server:

bin/magento server:run

Este comando inicia un puerto HTTP en 9501. Una vez que se inicia GraphQL Application Server, el puerto 9501 se convierte en un servidor proxy HTTP para todas las consultas de GraphQL.

Para confirmar que GraphQL Application Server se está ejecutando en la implementación:

ps aux | grep php

Formas adicionales de confirmar que GraphQL Application Server se está ejecutando incluyen:

  • Compruebe en el archivo /var/log/application-server.log las entradas que estén relacionadas con las solicitudes de GraphQL procesadas.
  • Intente conectarse al puerto HTTP en el que se ejecuta GraphQL Application Server. Por ejemplo: curl -g 'http://localhost:9501/graph.

Confirmar que se están procesando las solicitudes de GraphQL.

GraphQL Application Server agrega el encabezado de respuesta X-Backend con el valor graphql_server a cada solicitud que procesa. Para comprobar si GraphQL Application Server ha gestionado una solicitud, compruebe este encabezado de respuesta.

Confirmar la compatibilidad de extensiones y personalizaciones

Los desarrolladores y comerciantes de extensiones deben comprobar primero que su código de personalización y extensión cumple las directrices descritas en Directrices técnicas.

Tenga en cuenta estas directrices durante la evaluación del código:

  • Las clases de servicio (es decir, las clases que proporcionan comportamiento pero no datos, como EventManager) no deben tener un estado mutable.
  • Evite el acoplamiento temporal.

Deshabilitar GraphQL Application Server

Los procedimientos para desactivar GraphQL Application Server varían en función de si el servidor se está ejecutando en una implementación local o en la nube.

Deshabilitar GraphQL Application Server (nube)

  1. Elimine los nuevos archivos y cualquier otro cambio de código que se haya incluido en la confirmación de AppServer Enabled durante los preparativos para la implementación.

  2. Confirme los cambios con este comando:

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

  3. Implemente estos cambios con este comando:

    code language-bash 
    git push

Deshabilitar GraphQL Application Server (local)

  1. Convierta en comentario la sección /graphql del archivo nginx.conf que agregó al habilitar GraphQL Application Server.
  2. Reinicie nginx.

Este método de deshabilitar GraphQL Application Server puede resultar útil para probar o comparar el rendimiento rápidamente.

Confirme que GraphQL Application Server está desactivado.

Para confirmar que php-fpm está procesando solicitudes de GraphQL en lugar de GraphQL Application Server, escriba este comando: ps aux | grep php.

Después de deshabilitar GraphQL Application Server:

  • bin/magento server:run está inactivo.
  • var/log/application-server.log no contiene entradas después de las solicitudes de GraphQL.

Pruebas funcionales e integraciones para GraphQL Application Server

Los desarrolladores de extensiones pueden ejecutar dos pruebas de integración para comprobar la compatibilidad de la extensión con GraphQL Application Server: GraphQlStateTest y ResetAfterRequestTest.

GraphQlStateTest

GraphQlStateTest detecta el estado en objetos compartidos que no deben reutilizarse para varias solicitudes.

Esta prueba está diseñada para detectar cambios de estado en los objetos de servicio que produce ObjectManager. La prueba ejecuta consultas de GraphQL idénticas dos veces y compara el estado del objeto de servicio antes y después de la segunda consulta.

Errores de GraphQlStateTest y posible corrección

  • No se puede agregar, omitir ni filtrar una lista. Si ve un error acerca de agregar, omitir o filtrar una lista, considere si puede refactorizar la clase de una manera compatible con versiones anteriores para utilizar las fábricas de clases de servicio que tienen estado mutable.

  • La clase muestra un estado mutable. Si la propia clase muestra un estado mutable, intente reescribir el código para evitar este estado. Si el estado mutable es necesario por motivos de rendimiento, implemente ResetAfterRequestInterface y use _resetState() para restablecer el objeto a su estado construido inicial.

  • No se debe tener acceso a la propiedad $x escrita antes del mensaje de inicialización. Los errores con este tipo de mensaje sugieren que el constructor no ha inicializado la propiedad especificada. Se trata de una forma de acoplamiento temporal que se produce porque el objeto no se puede utilizar después de construirse inicialmente. Este acoplamiento se produce incluso si la propiedad es privada porque el recolector que recupera los datos de las propiedades está utilizando la función de reflexión PHP. En este caso, intente refactorizar la clase para evitar el acoplamiento temporal y el estado mutable. Si esa refactorización no resuelve el error, puede cambiar el tipo de propiedad a un tipo que admita valores NULL para que se pueda inicializar en NULL.  Si la propiedad es una matriz, intente inicializar la propiedad como una matriz vacía.

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

ResetAfterRequestTest

ResetAfterRequestTest busca todas las clases que implementan ResetAfterRequestInterface y comprueba que el método _resetState() devuelve el estado de un objeto al mismo estado que tenía después de ser construido por ObjectManager.  Esta prueba crea un objeto de servicio con ObjectManager, después clona ese objeto, llama a _resetState() y, a continuación, compara ambos objetos. La prueba no llama a ningún método entre la creación de instancias del objeto y _resetState(), por lo que no confirma el restablecimiento de ningún estado mutable. Encuentra problemas en los que un error tipográfico o de error tipográfico en _resetState() puede establecer el estado en algo diferente de lo que era originalmente.

Errores de ResetAfterRequestTest y posibles correcciones

  • La clase tiene valores de propiedad incoherentes. Si esta prueba falla, compruebe si una clase ha cambiado con el resultado de que el objeto después de la construcción tiene valores de propiedad diferentes de los que tiene después de llamar al método _resetState(). Si la clase en la que está trabajando no contiene el método _resetState() en sí, compruebe la jerarquía de clases de una superclase que lo implemente.

  • No se debe tener acceso a la propiedad $x escrita antes del mensaje de inicialización. Este problema también ocurre con GraphQlStateTest.

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

Pruebas funcionales

Al implementar GraphQL Application Server, los desarrolladores de extensiones deben ejecutar pruebas funcionales de WebAPI y cualquier prueba funcional automática o manual personalizada para GraphQL. Estas pruebas funcionales ayudan a los desarrolladores a identificar posibles errores o problemas de compatibilidad.

Modo de monitor de estado

Al ejecutar pruebas funcionales (o pruebas manuales), GraphQL Application Server puede ejecutarse con --state-monitor mode habilitado para ayudar a encontrar clases en las que el estado se esté reutilizando de forma involuntaria. Inicie Application Server normalmente, excepto si agrega el parámetro --state-monitor.

bin/magento server:run --state-monitor

Después de procesar cada solicitud, se agrega un nuevo archivo al directorio tmp, por ejemplo: var/tmp/StateMonitor-thread-output-50-6nmxiK. Una vez finalizada la prueba, estos archivos se pueden combinar con el comando bin/magento server:state-monitor:aggregate-output, que crea dos archivos combinados, uno en XML y uno en JSON.

Ejemplos:

/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

Estos archivos se pueden inspeccionar con cualquier herramienta que utilice para ver XML o JSON que muestre las propiedades modificadas de los objetos de servicio, como hace GraphQlStateTest. El modo --state-monitor utiliza la misma lista de omisión y lista de filtros que GraphQlStateTest.

NOTE
No utilice el modo --state-monitor en la producción. Solo está diseñado para desarrollo y pruebas. Crea muchos archivos de salida y se ejecuta más lentamente de lo normal.
NOTE
--state-monitor no es compatible con las versiones de PHP 8.3.0 - 8.3.4 debido a un error en el recolector de elementos no utilizados de PHP. Si usa PHP 8.3, debe actualizar a 8.3.5 o posterior para usar esta característica.
recommendation-more-help
c0c5bbed-4957-4162-81bc-120c837a1894