Artículo

GraphQL con Spring Boot: esquema, consultas y mutaciones

Cómo crear una API GraphQL con Spring Boot 4: esquema, @QueryMapping, @MutationMapping y @SchemaMapping, con peticiones y respuestas reales.

En resumen: con spring-boot-starter-graphql defines el contrato en un archivo schema.graphqls y lo implementas con controladores: @QueryMapping para lecturas, @MutationMapping para escrituras y @SchemaMapping para resolver campos anidados solo cuando el cliente los pide. Todo se sirve en un único endpoint POST /graphql, y el cliente elige exactamente qué campos quiere. Probado con Spring Boot 4.1.2 y Java 21, con peticiones HTTP reales.

Vídeo explicativo

GraphQL frente a REST

RESTGraphQL
EndpointsUno por recurso (/cursos, /cursos/1/lecciones)Uno solo (/graphql)
Qué datos lleganLos que decide el servidorLos que pide el cliente
Varias entidades a la vezVarias peticionesUna consulta
ContratoOpenAPI (opcional)Esquema tipado (obligatorio)
Caché HTTPSencilla (GET por URL)Más difícil (todo es POST)
ErroresCódigos HTTP200 con una lista errors

GraphQL brilla cuando hay varios clientes (web, móvil) que necesitan formas distintas de los mismos datos. Para una API sencilla, REST sigue siendo más simple.

Dependencias

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-graphql</artifactId>
</dependency>
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-webmvc</artifactId>
</dependency>

El esquema

src/main/resources/graphql/schema.graphqls:

type Query {
    cursos: [Curso!]!
    curso(id: ID!): Curso
}

type Mutation {
    crearCurso(titulo: String!, nivel: Nivel!): Curso!
}

type Curso {
    id: ID!
    titulo: String!
    nivel: Nivel!
    lecciones: [Leccion!]!
}

type Leccion {
    titulo: String!
    minutos: Int!
}

enum Nivel {
    BASICO
    INTERMEDIO
    AVANZADO
}

El ! indica que el campo no puede ser nulo.

El controlador

enum Nivel { BASICO, INTERMEDIO, AVANZADO }

record Curso(String id, String titulo, Nivel nivel) {}

record Leccion(String titulo, int minutos) {}

@Controller
class CursoController {
    private final Map<String, Curso> cursos = new ConcurrentHashMap<>();
    private final AtomicLong secuencia = new AtomicLong();
    private final Map<String, List<Leccion>> lecciones = Map.of(
            "1", List.of(new Leccion("Variables", 12), new Leccion("Bucles", 18)),
            "2", List.of(new Leccion("Crear un proyecto", 10)));

    CursoController() {
        crearCurso("Java desde cero", Nivel.BASICO);
        crearCurso("Spring Boot", Nivel.INTERMEDIO);
    }

    @QueryMapping
    List<Curso> cursos() {
        return List.copyOf(cursos.values());
    }

    @QueryMapping
    Curso curso(@Argument String id) {
        return cursos.get(id);
    }

    @MutationMapping
    Curso crearCurso(@Argument String titulo, @Argument Nivel nivel) {
        String id = String.valueOf(secuencia.incrementAndGet());
        Curso curso = new Curso(id, titulo, nivel);
        cursos.put(id, curso);
        return curso;
    }

    // Resuelve el campo "lecciones" de Curso solo si el cliente lo pide
    @SchemaMapping(typeName = "Curso", field = "lecciones")
    List<Leccion> lecciones(Curso curso) {
        System.out.println("  (resolviendo lecciones del curso " + curso.id() + ")");
        return lecciones.getOrDefault(curso.id(), List.of());
    }
}

El método se enlaza con el campo del esquema por su nombre: cursos() resuelve Query.cursos. El record Curso no tiene campo lecciones; lo aporta @SchemaMapping, que en un caso real podría consultar otra tabla u otro servicio.

Peticiones y respuestas reales

Arrancamos la aplicación y enviamos cada consulta con POST /graphql y el cuerpo {"query": "..."}:

> { cursos { titulo nivel } }
< 200 {"data":{"cursos":[{"titulo":"Java desde cero","nivel":"BASICO"},{"titulo":"Spring Boot","nivel":"INTERMEDIO"}]}}

> { curso(id: "1") { titulo lecciones { titulo minutos } } }
  (resolviendo lecciones del curso 1)
< 200 {"data":{"curso":{"titulo":"Java desde cero","lecciones":[{"titulo":"Variables","minutos":12},{"titulo":"Bucles","minutos":18}]}}}

> mutation { crearCurso(titulo: "Spring AI", nivel: AVANZADO) { id titulo } }
< 200 {"data":{"crearCurso":{"id":"3","titulo":"Spring AI"}}}

> { curso(id: "1") { precio } }
< 200 {"errors":[{"message":"Validation error (FieldUndefined@[curso/precio]) : Field 'precio' in type 'Curso' is undefined", ... "extensions":{"classification":"ValidationError"}}]}

Lo que muestran:

  • La primera consulta no pidió lecciones y el método de lecciones no se ejecutó. En la segunda sí.
  • La mutación devolvió solo los campos solicitados.
  • Pedir un campo que no existe da un error de validación antes de ejecutar nada, y con código HTTP 200: en GraphQL hay que mirar la lista errors, no solo el estado HTTP.

Para probar a mano, activa la interfaz web con spring.graphql.graphiql.enabled=true y abre /graphiql.

Problemas típicos

  • N+1: si pides 100 cursos con sus lecciones, el @SchemaMapping se ejecuta 100 veces. Spring for GraphQL tiene @BatchMapping, que recibe la lista de cursos y resuelve todas las lecciones de una vez.
  • Consultas abusivas: un cliente puede anidar campos hasta tumbar el servidor. Limita profundidad y complejidad.
  • Seguridad por campo: con un solo endpoint, la autorización se hace en los métodos (por ejemplo con @PreAuthorize), no por URL.

Preguntas frecuentes

¿GraphQL sustituye a REST?

No. Son herramientas distintas; muchas empresas usan REST para APIs públicas sencillas y GraphQL para el backend for frontend de sus aplicaciones.

¿Puedo usarlo con JPA?

Sí: los métodos llaman a tus servicios o repositorios como cualquier controlador. Cuidado con las relaciones perezosas y el N+1.

¿Hay suscripciones en tiempo real?

Sí, type Subscription con @SubscriptionMapping, sobre WebSocket. Para tiempo real sin GraphQL, tienes WebSockets con Spring Boot.

Sigue aprendiendo

El diseño de APIs, REST y sus alternativas se trabajan en el curso de Spring Boot Web. Para documentar una API REST, OpenAPI con Spring Boot.

graphql spring boot spring for graphql api java

Newsletter Semanal de Java

Cada viernes recibe lo más nuevo del ecosistema Java: frameworks, herramientas y mejores prácticas.

Sin spam. Cancela cuando quieras.

Compartir artículo