Lección 283: Instalación y configuración de Spring GraphQL

Spring y su ecosistema hacen el desarrollo de aplicaciones muy eficiente, y la integración con GraphQL permite usar una manera moderna, flexible y potente de trabajar con datos. GraphQL ofrece un único endpoint para todas las operaciones (queries y mutations), facilitando la interacción entre cliente y servidor. Combinado con Spring obtenemos una herramienta potente para desarrollar APIs que puede reemplazar o complementar REST con facilidad.

1. Instalación de Spring GraphQL: vamos a crear el proyecto

Empecemos configurando un nuevo proyecto Spring Boot que soporte GraphQL. Usaremos Spring Initializr, que permite crear rápidamente una plantilla de proyecto adecuada.

Usar Spring Initializr

1. Abre Spring Initializr.
2. Indica:
   • Project: Maven (también puedes usar Gradle si lo prefieres).
   • Language: Java.
   • Spring Boot: versión 2.7.0 o superior (GraphQL está soportado a partir de 2.7.0).
3. Añade las dependencias necesarias:
   • Spring Web
   • Spring Boot Starter GraphQL
   • Spring Boot DevTools (para recarga rápida de la aplicación — muy útil durante el desarrollo).
4. Descarga la plantilla del proyecto e impórtala en tu IDE favorito (IntelliJ IDEA, Eclipse, etc.).

Ejemplo de pom.xml

Tu archivo pom.xml debería verse aproximadamente así:

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
        <groupId>com.graphql-java-kickstart</groupId>
        <artifactId>graphql-spring-boot-starter</artifactId>
        <version>12.0.0</version>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-graphql</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-devtools</artifactId>
        <scope>runtime</scope>
        <optional>true</optional>
    </dependency>
</dependencies>

¡Todo listo para empezar! Ahora vamos a configurar el servidor GraphQL.

2. Configuración del servidor GraphQL

GraphQL requiere la definición del esquema y de los endpoints. Spring Boot simplifica este proceso y conecta automáticamente el esquema y el punto de entrada para GraphQL.

Carpeta para el esquema

Crea la carpeta graphql en src/main/resources. En esa carpeta guardaremos los esquemas de GraphQL.

Definimos el primer esquema

Crea el archivo schema.graphqls dentro de la carpeta graphql. En ese archivo describiremos los tipos y las operaciones disponibles. Esto es un ejemplo mínimo:

type Query {
    hello: String
}

Aquí tienes una operación simple hello que devuelve una String. Cuando el esquema esté listo, configuraremos el manejador de la consulta.

Configuración del endpoint

Por defecto Spring Boot GraphQL configura el endpoint /graphql para manejar todas las peticiones GraphQL. Para comprobarlo, arranca tu aplicación y abre en el navegador http://localhost:8080/graphql.

En este punto verás que el servidor ya está listo para recibir peticiones. Ahora pasemos a manejar nuestra primera consulta.

3. Creación de resolvers para Query

GraphQL usa "resolvers" para mapear las operaciones (queries, mutations) a la lógica en Java. Para nuestra primera query hello crearemos un resolver.

Creamos el resolver

Añade una nueva clase a tu proyecto:

package com.example.graphql;

import org.springframework.graphql.data.method.annotation.QueryMapping;
import org.springframework.stereotype.Controller;

@Controller
public class GreetingController {

    @QueryMapping
    public String hello() {
        return "¡Hola desde GraphQL!";
    }
}

Aquí:

1. @Controller — indica a Spring que esta clase manejará las peticiones.
2. @QueryMapping — enlaza el método con nuestra query hello definida en el esquema.

4. Probando queries de GraphQL

Podemos probar las consultas usando la herramienta integrada GraphQL — GraphiQL, que viene integrada en Spring Boot.

1. Arranca la aplicación.
2. En el navegador ve a: http://localhost:8080/graphiql.
3. Pega la siguiente consulta:

   query {
       hello
   }
   

Si todo está bien configurado verás:

{
  "data": {
    "hello": "¡Hola desde GraphQL!"
  }
}

¡Enhorabuena! Acabas de crear tu primera aplicación con GraphQL.

5. Configuración del IDE para trabajar con GraphQL

Plugin para IntelliJ IDEA

Si usas IntelliJ IDEA, una herramienta muy útil para trabajar con GraphQL es el plugin GraphQL disponible en JetBrains Marketplace. Te ayuda a:

• Validar automáticamente tu esquema de GraphQL.
• Resaltar errores y autocompletar consultas.
• Probar queries directamente desde el IDE.

Instalación:

1. Abre la configuración de IntelliJ IDEA: File > Settings > Plugins.
2. Busca el plugin GraphQL y instálalo.
3. Reinicia el IDE.

Ahora puedes editar y probar tus esquemas y consultas con mayor facilidad.

6. Configuración avanzada del servidor GraphQL

El servidor GraphQL de Spring Boot soporta configuración mediante application.properties o application.yml. Por ejemplo:

spring.graphql.graphiql.enabled=true
spring.graphql.schema.printer.enabled=true

Aquí:

• spring.graphql.graphiql.enabled=true activa la interfaz integrada GraphiQL (habitualmente activada por defecto).
• spring.graphql.schema.printer.enabled=true permite imprimir tu esquema en los logs al arrancar la aplicación (útil para comprobarlo).

7. Errores comunes y cómo solucionarlos

• Error: "No schema found". Asegúrate de que el archivo de esquema schema.graphqls está en src/main/resources/graphql — esta es la ruta estándar para esquemas GraphQL en Spring Boot.
• Error: "Query [name] not found". Si una query del esquema no encuentra su resolver, verifica que los nombres coincidan y que el método esté anotado con @QueryMapping.
• Error: "Circular dependency". Esto puede ocurrir si tienes varios beans con dependencias complejas entre sí. Para solucionarlo prueba a usar la anotación @Lazy o revisa la arquitectura para romper el ciclo.

Ahora estás listo para trabajar con esquemas, queries y mutations más complejos. Hemos dado el primer paso en la integración de GraphQL con Spring Boot. En las siguientes lecciones profundizaremos en la creación de queries y mutations más avanzadas, y en subscriptions.