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-graphqldefines el contrato en un archivoschema.graphqlsy lo implementas con controladores:@QueryMappingpara lecturas,@MutationMappingpara escrituras y@SchemaMappingpara resolver campos anidados solo cuando el cliente los pide. Todo se sirve en un único endpointPOST /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
| REST | GraphQL | |
|---|---|---|
| Endpoints | Uno por recurso (/cursos, /cursos/1/lecciones) | Uno solo (/graphql) |
| Qué datos llegan | Los que decide el servidor | Los que pide el cliente |
| Varias entidades a la vez | Varias peticiones | Una consulta |
| Contrato | OpenAPI (opcional) | Esquema tipado (obligatorio) |
| Caché HTTP | Sencilla (GET por URL) | Más difícil (todo es POST) |
| Errores | Códigos HTTP | 200 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
@SchemaMappingse 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.
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.