GraphQL con Spring Boot en un vistazo

GraphQL es un protocolo de comunicación que se considera ideal cuando el cliente necesita controlar qué datos obtiene, evitando cargas innecesarias. Consultas flexibles y un solo endpoint para múltiples recursos.

Está basado en consultas declarativas; puesto que el cliente define qué datos necesita.

Emplea JSON como formato de datos. El cual es fácil de leer.

Se recomienda para aplicaciones web y móviles que requieren flexibilidad en datos.

Veremos un ejemplo de uso con ayuda de Spring Boot.

Para ello requerimos crear un proyecto: https://start.spring.io/

Las dependencias necesarias son las siguientes:

pom.xml

<dependencies>
    <!-- Starter básico de Spring Boot -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter</artifactId>
    </dependency>

    <!-- Starter Web (para exponer endpoints si lo necesitas) -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>

    <!-- GraphQL para Spring Boot -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-graphql</artifactId>
    </dependency>

    <!-- Herramientas de desarrollo -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-devtools</artifactId>
        <scope>runtime</scope>
    </dependency>

    <!-- Testing -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-test</artifactId>
        <scope>test</scope>
    </dependency>
</dependencies>

Ahora agregaremos este archivo src/main/resources/graphql/schema.graphqls con el siguiente contenido:

type Query {
    hello: String
    userById(id: ID!): User
}

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

El cual es un esquema GraphQL que nos sirve como el contrato fundamental que define qué datos están disponibles en una API, sus tipos, relaciones y las operaciones (consultas o mutaciones) que los clientes pueden realizar.

Este esquema define tres propiedades: id, name y email.

Ahora crearemos la clase Java llamada User.java. Como trabajaremos bajo un esquema modular deberá estar dentro de la carpeta model.

User.java

package com.inforhomex.demo.model;

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

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

  
    public String getId() { 
	   return id; 
	}
	
	public void setId(String id){
		this.id = id;
	}
    
	public String getName() { 
	   return name; 
	}

    public void setName(String name){
		this.name = name;
	}
	
    
	public String getEmail() { 
	   return email; 
	}
	
	public void setEmail(String email){
		this.email = email;
	}
	
}

Ahora dentro de una carpeta llamada controller crearemos una clase tipo controller.

UserController.java

package com.inforhomex.demo.controller;

import org.springframework.graphql.data.method.annotation.QueryMapping;
import org.springframework.graphql.data.method.annotation.Argument;
import org.springframework.stereotype.Controller;
import com.inforhomex.demo.model.User;

@Controller
public class UserController {

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

    @QueryMapping
    public User userById(@Argument String id) {
        return new User(id, "Thomas Muller", "thomas.muller@alquimista.com");
    }
}

Como se puede ver estamos usando anotaciones tipo @QueryMapping . Las cuales en Spring GraphQL nos sirven para vincular (mapear) automáticamente un método dentro de un controlador a una consulta específica (query) definida en tu esquema GraphQL.

La anotación @Argument en Spring for GraphQL se utiliza para vincular un argumento GraphQL con nombre a un parámetro de método en un controlador o componente de servicio.

También será necesario hacer ajustes a nuestro archivo application.yaml.

spring:
  application:
    name: demo grapql
  graphql:
    graphiql:
      enabled: true
    path: /graphql

server:
  port: 8083

Aquí definimos el nombre del proyecto, el puerto a usar, asignar la url y habilitar la interfaz gráfica de GraphiQL.

Para ejecutar el proyecto podemos abrir una terminal y teclear lo siguiente:

$ mvn clean install 
$ mvn spring-boot:run

Lo cual nos descargará las dependencias y construirá el proyecto. Para después ejecutarlo.

Abrimos un navegador en la siguiente url: http://localhost:8083/graphiql?path=/graphql

Pegamos la siguiente consulta:

query {
  hello
  userById(id:"3"){
    name
    id
  }
}

Obteniendo como resultado lo siguiente:

{
  "data": {
    "hello": "Hola desde GraphQL con Spring Boot!",
    "userById": {
      "name": "Thomas Muller",
      "id": "3"
    }
  }
}

Hasta el momento no hemos creado ningún objeto. Para ello usaremos el concepto de Mutation (mutación) en GraphQL. La cual es una operación utilizada para modificar datos en el servidor, permitiendo crear, actualizar o eliminar registros (equivalente a POST, PUT, PATCH o DELETE en REST).

Editaremos el archivo src/main/resources/graphql/schema.graphqls para agregar el Mutation.

type Query {
    hello: String
    userById(id: ID!): User
}

type Mutation {
    createUser(id: ID!, name: String!, email: String!): User
}

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

Editamos la clase tipo controller UserController.java para manejar tanto queries como mutations.

package com.inforhomex.demo.controller;

import org.springframework.graphql.data.method.annotation.QueryMapping;
import org.springframework.graphql.data.method.annotation.MutationMapping;
import org.springframework.graphql.data.method.annotation.Argument;
import org.springframework.stereotype.Controller;
import com.inforhomex.demo.model.User;

import java.util.HashMap;
import java.util.Map;

@Controller
public class UserController {

    
    private Map<String, User> users = new HashMap<>();

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

    @QueryMapping
    public User userById(@Argument String id) {
        return users.get(id);
    }
	

    @MutationMapping
    public User createUser(@Argument String id, @Argument String name, @Argument String email) {
        User user = new User(id, name, email);
        users.put(id, user);
        return user;
    }
}

Ejecutamos la aplicación. Entramos a la Url del proyecto y escribimos esta consulta:

mutation {
  createUser(id: "1", name: "Juan Pérez", email: "juan@example.com") {
    id
    name
    email
  }
}

Con esto hemos creado un nuevo usuario. Salida:

{
  "data": {
    "createUser": {
      "id": "1",
      "name": "Juan Pérez",
      "email": "juan@example.com"
    }
  }
}

Consultamos:

query {
  userById(id: "1") {
    id
    name
    email
  }
}

Obtendremos lo siguiente:

{
  "data": {
    "userById": {
      "id": "1",
      "name": "Juan Pérez",
      "email": "juan@example.com"
    }
  }
}

Trabajar con GraphQL y Spring Boot es habitual en aplicaciones modernas, puesto que es una combinación muy efectiva.

Este solo es un ejemplo. Se puede extender para uso de alguna base de datos como PostgreSQL o H2, pero será en otra ocasión.

Enlaces:

https://graphql.org/
https://codemonkeyjunior.blogspot.com/2026/01/grpc-y-graphql-en-una-comparativa.html
https://alquimistadecodigo.blogspot.com/2024/05/graphql-en-un-vistazo.html