GraphQL Compose
Kit de herramientas para generar esquemas GraphQL en Drupal, proporcionando un esquema GraphQL extensible sin código para el módulo Drupal GraphQL.
graphql_compose
Overview
GraphQL Compose es un kit de herramientas integral para generar esquemas GraphQL en Drupal. Proporciona un esquema GraphQL extensible sin código para el módulo GraphQL 4.x/5.x de Drupal, con el objetivo de ofrecer un esquema fácil de usar y fácil de entender sin demasiados "Drupalismos".
El módulo genera automáticamente un esquema GraphQL a partir de Entity y Field de Drupal a través de una arquitectura basada en plugins. Admite más de 50 tipos de Field de forma nativa y proporciona soporte para Node, Media, Taxonomy Term, User, Paragraph y más a través de submódulos opcionales.
Las características arquitectónicas clave incluyen: configuración por servidor que permite que cada servidor GraphQL tenga ajustes independientes, paginación basada en cursor a través del submódulo Edges, enrutamiento y resolución de URL, soporte de menús, integración con Layout Builder y un extenso sistema de hooks para personalización.
Features
- Generación automática de esquemas GraphQL a partir de Entity de Drupal sin escribir código
- Arquitectura basada en plugins con más de 54 manejadores de tipos de Field, más de 8 manejadores de tipos de Entity y más de 30 definiciones de tipos de esquema
- Configuración por servidor: cada servidor GraphQL puede tener ajustes independientes de GraphQL Compose
- Soporte de paginación basada en cursor a través del patrón Connection/Edge (mediante el submódulo graphql_compose_edges)
- Enrutamiento de contenido y resolución de URL con soporte para alias de ruta y redirecciones
- Integración con el sistema de menús exponiendo los menús de Drupal como consultas GraphQL
- Soporte para Layout Builder y Layout Paragraphs para diseños de página complejos
- Soporte multilingüe con inflexión de idioma para singularización/pluralización en 7 idiomas
- Soporte de derivados de estilos de imagen para imágenes responsivas
- Exposición de contenido de Block incluyendo bloques personalizados y bloques de plugin
- Soporte de comentarios con mutación para crear comentarios
- Integración con Views para consultas GraphQL filtrables y ordenables
- Integración con el módulo Metatag para metadatos SEO
- Soporte para Entity Construction Kit (ECK) para tipos de Entity personalizados
- Exposición de información de User con roles y estado
- Extenso sistema de hooks que permite la personalización de la generación de esquemas, resolución de Field y definiciones de tipos
- Operación de copiar UUID añadida a los tipos de Entity habilitados para facilitar la referencia
Use Cases
Drupal Headless con React/Vue/Next.js
Usa GraphQL Compose para exponer tu contenido de Drupal a un framework frontend de JavaScript. Habilita los tipos de entidad y campos que necesites, usa el submódulo routes para resolver URLs a contenido, y el submódulo edges para listas paginadas. El esquema se actualiza automáticamente cuando agregas nuevos tipos de contenido o campos.
Backend para Aplicaciones Móviles
Expone contenido de Drupal a aplicaciones móviles nativas a través de GraphQL. Habilita la exposición de IDs de entidad para sincronización offline, usa estilos de imagen para imágenes optimizadas para móviles, y aprovecha el submódulo user para autenticación. La opción de consultas simples proporciona una API más limpia para desarrolladores móviles.
API de Contenido Multi-sitio
Usa la configuración por servidor para crear diferentes APIs GraphQL para diferentes consumidores. Crea servidores GraphQL separados con diferentes configuraciones de entidad/campo, rutas de endpoint y controles de acceso para cada aplicación cliente.
Sistema de Vista Previa de Contenido
Usa el submódulo routes con el buffer de vista previa de entidades para construir sistemas de vista previa de contenido. El módulo maneja la resolución de contenido en borrador y vistas previas específicas por idioma para flujos de trabajo editoriales.
Construcción de Páginas Complejas
Combina los submódulos Layout Builder o Layout Paragraphs para exponer estructuras de página complejas. El esquema representa secciones, regiones y componentes permitiendo a los frontends renderizar diseños de página flexibles definidos en Drupal.
Catálogo de Productos de Comercio Electrónico
Expone tipos de contenido de productos con sus campos, imágenes con múltiples estilos de imagen para diferentes contextos de visualización, y términos de taxonomía para categorías. Usa la integración con Views para listados de productos filtrados/ordenados con paginación.
Entrega de Contenido Multilingüe
Aprovecha el soporte de idiomas integrado para servir contenido en múltiples idiomas. El contexto de idioma fluye a través de todos los resolvers, y el servicio inflector maneja la pluralización correcta para idiomas distintos al inglés.
Tips
- Usa la operación 'Copy UUID' añadida a los dropbuttons de entidad para obtener fácilmente UUIDs de entidad para probar consultas
- Habilita 'Simple entity queries' para reducir la complejidad del esquema - en lugar de consultas separadas nodePage, nodeArticle, obtienes una única consulta node que devuelve una unión
- Usa el GraphQL Explorer en /admin/config/graphql/servers/{server}/explorer para probar consultas interactivamente
- La consulta info proporciona la versión del esquema y configuraciones personalizadas - úsala para invalidación de caché y feature flags
- Durante el desarrollo, revisa el parámetro 'development' en graphql_compose.services.yml para opciones de depuración
- Las configuraciones personalizadas en el formulario Information soportan tokens de Drupal cuando el módulo Token está instalado
- El inflector soporta 7 idiomas - configura el idioma apropiado para tu idioma de contenido principal para obtener pluralización correcta
- Usa hook_graphql_compose_field_results_alter() para transformar valores de campo antes de que lleguen al cliente
- Cada servidor GraphQL puede tener configuración independiente de GraphQL Compose - usa esto para APIs versionadas o diferentes necesidades de cliente
Technical Details
Admin Pages 3
/admin/config/graphql/servers/manage/{graphql_server}/graphql_compose
Configura qué tipos de entidad, bundles y campos de Drupal se exponen a través de GraphQL. Esta es la página de configuración principal donde habilitas/deshabilitas tipos de contenido específicos, vocabularios de taxonomía, tipos de medios y sus campos individuales para la exposición en GraphQL.
/admin/config/graphql/servers/manage/{graphql_server}/graphql_compose/info
Configura los metadatos del esquema y la información del sitio que se expone a través de la consulta 'info' de GraphQL. Esto incluye información de versión, nombre del sitio, eslogan y pares clave-valor personalizados.
/admin/config/graphql/servers/manage/{graphql_server}/graphql_compose/settings
Configura los ajustes generales de comportamiento para GraphQL Compose, incluyendo el manejo de entidades, opciones de campo y reglas de inflexión de cadenas.
Hooks 18
hook_graphql_compose_print_types
Añade tipos GraphQL personalizados al esquema. Se llama durante la generación del esquema para registrar nuevas definiciones de ObjectType, InterfaceType, EnumType u otros tipos GraphQL.
hook_graphql_compose_print_extensions
Añade extensiones a tipos GraphQL existentes. Úsalo para agregar nuevos campos a Query, Mutation o cualquier tipo existente en el esquema.
hook_graphql_compose_singularize_alter
Altera el resultado de la singularización del lenguaje. Personaliza cómo los nombres de bundles se convierten a forma singular para el nombrado de tipos GraphQL.
hook_graphql_compose_pluralize_alter
Altera el resultado de la pluralización del lenguaje. Personaliza cómo los nombres de tipos se convierten a forma plural para consultas de colecciones.
hook_graphql_compose_field_enabled_alter
Cambia el estado habilitado de un campo. Úsalo para ocultar o mostrar campos programáticamente en el esquema GraphQL independientemente de la configuración del administrador.
hook_graphql_compose_field_results_alter
Altera los resultados de la resolución de campos. Modifica, filtra o reemplaza completamente los datos devueltos para un campo específico.
hook_graphql_compose_entity_interfaces_alter
Añade interfaces personalizadas a tipos de entidad. Úsalo para agregar interfaces compartidas entre tipos de entidad basándose en campos o comportamientos comunes.
hook_graphql_compose_entity_bundle_enabled_alter
Cambia el estado habilitado de un bundle de entidad. Úsalo para incluir o excluir programáticamente bundles de entidad del esquema GraphQL.
hook_graphql_compose_entity_base_fields_alter
Modifica los campos base disponibles para un tipo de entidad. Añade o elimina campos base antes de que sean procesados para la exposición GraphQL.
hook_graphql_compose_entity_type_form_alter
Altera el formulario de configuración del tipo de entidad. Añade configuraciones personalizadas al formulario GraphQL Compose Schema para bundles de entidad.
hook_graphql_compose_field_type_form_alter
Altera el formulario de configuración del tipo de campo. Añade configuraciones personalizadas al formulario GraphQL Compose Schema para campos individuales.
hook_graphql_compose_entity_translate_alter
Sobrescribe el comportamiento de traducción de entidades. Personaliza cómo las entidades son traducidas cuando se resuelven en un contexto de idioma específico.
hook_graphql_compose_current_language_alter
Sobrescribe la resolución de idioma para el contexto del campo. Personaliza qué idioma se usa al resolver contenido multilingüe.
hook_graphql_compose_routes_incoming_alter
Modifica las rutas URL antes de la resolución de rutas. Transforma o normaliza las rutas antes de que sean resueltas a entidades.
hook_graphql_compose_routes_union_alter
Resuelve tipos de ruta personalizados. Mapea valores de ruta a tipos GraphQL específicos para el RouteUnion.
hook_graphql_compose_edges_alter
Modifica las conexiones edge para entidades. Personaliza la paginación, filtrado u ordenación de colecciones de entidades.
hook_graphql_compose_blocks_union_alter
Resuelve tipos de bloque personalizados. Mapea valores de plugins de bloque a tipos GraphQL específicos para el BlockUnion.
hook_graphql_compose_metatags_union_alter
Resuelve tipos de metatag personalizados. Mapea valores de metatag a tipos GraphQL específicos para el MetaTagUnion.
Troubleshooting 7
Limpia las cachés de GraphQL haciendo clic en 'Guardar configuración' en cualquier formulario de GraphQL Compose, o ejecuta 'drush cr'. El módulo limpia automáticamente las cachés cuando cambia la configuración.
Asegúrate de que el tipo de entidad tenga un plugin de tipo de entidad GraphQL Compose. Los tipos del núcleo (node, media, taxonomy_term, user, paragraph) están soportados. Para otros tipos, habilita los submódulos apropiados (graphql_compose_blocks para block_content, graphql_compose_eck para entidades ECK).
Verifica si existe un plugin de tipo de campo para tu campo. El módulo soporta más de 54 tipos de campo. Para campos no soportados, implementa hook_graphql_compose_print_types() y hook_graphql_compose_print_extensions() para agregar manejo personalizado.
GraphQL Compose respeta el control de acceso de Drupal. Verifica los permisos de acceso a entidades, asegúrate de que la configuración 'exclude_unpublished' coincida con tus necesidades, y verifica que el usuario que consulta tenga los permisos apropiados.
Asegúrate de que las entidades referenciadas estén publicadas (si exclude_unpublished está habilitado), el tipo/bundle de entidad referenciada esté habilitado en GraphQL Compose, y el usuario tenga acceso para ver las entidades referenciadas.
Habilita el submódulo graphql_compose_edges para paginación basada en cursor. Sin él, los campos de referencia de entidad devuelven arrays planos sin soporte de paginación.
Habilita el submódulo graphql_compose_routes y asegúrate de que el bundle de entidad tenga marcado 'Enable route loading' en el formulario Schema. Verifica que los alias de ruta estén configurados correctamente en Drupal.
Security Notes 7
- Por defecto, los IDs de entidad no se exponen para prevenir ataques de enumeración. Solo habilita 'Expose entity IDs' si tu aplicación requiere IDs numéricos.
- El módulo respeta el sistema de acceso a entidades de Drupal. Los usuarios solo pueden consultar contenido para el cual tienen permiso de visualización.
- Cuando uses el submódulo comments con mutations, la entrada se sanitiza contra XSS pero asegúrate de que tu aplicación valide apropiadamente la entrada del usuario.
- La configuración 'Exclude unpublished entities' proporciona defensa en profundidad ocultando contenido no publicado incluso de usuarios que podrían tener permisos de visualización.
- La incrustación de SVG tiene un límite de tamaño de archivo para prevenir denegación de servicio por archivos SVG grandes. Ajusta el límite según tus necesidades.
- La introspección de GraphQL está habilitada por defecto. Deshabilítala en producción si no quieres exposición del esquema.
- El submódulo routes normaliza las rutas entrantes - implementa hook_graphql_compose_routes_incoming_alter() para agregar validación adicional de rutas si es necesario.