Lección 284: Creando la primera consulta en GraphQL

Hoy vamos a dar un paso adelante y crear nuestra primera consulta GraphQL. Mano en el ratón, café cerca — ¡empezamos!

Creando la primera consulta en GraphQL

Las consultas GraphQL son la forma de obtener datos del servidor. A diferencia de REST, donde cada endpoint devuelve un conjunto fijo de datos, en GraphQL tú describes la estructura de la respuesta. Por ejemplo, imagina que necesitas la lista de usuarios, pero solo sus nombres y emails. GraphQL te permite solicitar solo esos campos, lo que hace que tu API sea más flexible.

1. Ejemplo de consulta GraphQL

query {
  users {
    name
    email
  }
}

El servidor devolverá solo estos datos:

{
  "data": {
    "users": [
      { "name": "Iván", "email": "ivan@example.com" },
      { "name": "Ana", "email": "anna@example.com" }
    ]
  }
}

2. Definición del esquema GraphQL

Para que el servidor sepa qué campos debe procesar, necesitas crear un esquema GraphQL. El esquema define:

• Qué queries se soportan.
• Qué datos se devuelven.
• Qué tipos de datos existen.

Ejemplo de esquema GraphQL

Crea el archivo schema.graphqls en la carpeta src/main/resources/graphql/. En ese archivo indica el esquema:

type Query {
    hello: String
    users: [User!]!
}

type User {
    id: ID!
    name: String!
    email: String!
}

• Query — tipo especial que describe todas las consultas soportadas.
• hello — consulta simple que devuelve una cadena.
• users — consulta que devuelve una lista de objetos tipo User.
• User — objeto que representa a un usuario.

3. Añadir datos. Implementación de los Query Resolvers.

Para procesar las consultas GraphQL el servidor necesita Query Resolvers. Estos describen cómo obtener los datos para cada consulta del esquema.

Implementación del Query Resolver en Spring Boot

Crea una clase Java para manejar las consultas. Por ejemplo, QueryResolver:

package com.example.graphql.resolver;

import org.springframework.stereotype.Component;
import com.example.graphql.model.User;

import java.util.List;

@Component
public class QueryResolver {

    // Manejador de la consulta "hello"
    public String hello() {
        return "¡Hola, GraphQL!";
    }

    // Manejador de la consulta "users"
    public List<User> users() {
        return List.of(
            new User(1L, "Iván", "ivan@example.com"),
            new User(2L, "Ana", "anna@example.com")
        );
    }
}

Modelo User para los datos

package com.example.graphql.model;

public class User {
    private Long id;
    private String name;
    private String email;

    public User(Long id, String name, String email) {
        this.id = id;
        this.name = name;
        this.email = email;
    }

    // Getters
    public Long getId() {
        return id;
    }

    public String getName() {
        return name;
    }

    public String getEmail() {
        return email;
    }
}

Hemos creado dos manejadores (hello y users) que responden a las consultas definidas en nuestro esquema GraphQL.

4. Probando la primera consulta

Es hora de comprobar cómo funciona nuestra consulta. Para ello puedes usar herramientas como GraphQL Playground, Postman o los plugins integrados en tu IDE.

Configuración de GraphQL Playground

Añade la siguiente dependencia en pom.xml para conectar la interfaz de GraphQL Playground:

<dependency>
    <groupId>com.graphql-java-kickstart</groupId>
    <artifactId>graphql-spring-boot-starter-playground</artifactId>
    <version>11.1.0</version>
</dependency>

Arranca tu servidor Spring Boot y ve a la dirección:

http://localhost:8080/playground

Ahí podrás ejecutar consultas y ver el resultado.

Verificación de la consulta básica

Prueba a hacer la consulta hello:

query {
  hello
}

Deberías obtener la respuesta:

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

Ahora prueba la consulta de usuarios users:

query {
  users {
    id
    name
    email
  }
}

Resultado:

{
  "data": {
    "users": [
      { "id": "1", "name": "Iván", "email": "ivan@example.com" },
      { "id": "2", "name": "Ana", "email": "anna@example.com" }
    ]
  }
}

5. Mejorar la estructura usando GraphQL Resolver

Para hacer el código más estructurado puedes usar la interfaz GraphQLQueryResolver. Esto permite que Spring vincule automáticamente las consultas GraphQL con los métodos Java.

Query Resolver actualizado

package com.example.graphql.resolver;

import org.springframework.stereotype.Component;
import com.example.graphql.model.User;
import com.coxautodev.graphql.tools.GraphQLQueryResolver;

import java.util.List;

@Component
public class QueryResolver implements GraphQLQueryResolver {

    public String hello() {
        return "¡Hola, GraphQL!";
    }

    public List<User> users() {
        return List.of(
            new User(1L, "Iván", "ivan@example.com"),
            new User(2L, "Ana", "anna@example.com")
        );
    }
}

Ahora Spring enlaza automáticamente los métodos hello y users con las consultas descritas en el esquema schema.graphqls.

6. Errores típicos y cómo arreglarlos

• Error "Field 'X' in type 'Query' is undefined"
  • Asegúrate de que el archivo schema.graphqls está definido correctamente y coincide con tus métodos en QueryResolver.
• Error "No resolver found"
  • Revisa que tu clase manejadora esté anotada con @Component y esté en el contexto de Spring.
• El servidor no responde a las consultas
  • Comprueba que las dependencias y la configuración de GraphQL estén añadidas.

7. Aplicación práctica

Ahora podrás crear consultas potentes para cualquier dato en tu aplicación. Las consultas GraphQL son especialmente útiles en aplicaciones cliente-servidor, donde los desarrolladores de frontend pueden pedir solo los datos que necesitan. Por ejemplo, las apps móviles, donde el tiempo de transferencia es crítico, se benefician mucho de GraphQL.

En resumen:

1. Has configurado el esquema GraphQL.
2. Has creado un Query Resolver para manejar las consultas.
3. Has probado tus primeras consultas.

En la próxima lección veremos cómo implementar mutaciones (Mutations) para gestionar datos en el servidor.