Lección 5 de 8: datos con Spring Data JPA. Tu catálogo deja de vivir en un mapa que se borra al reiniciar y pasa a una base de datos. Vas a crear una entidad, un repositorio que es solo una interfaz, consultas que salen del nombre de un método y transacciones que se deshacen si algo falla, mirando en cada paso el SQL real que genera Hibernate.
JPA, Hibernate y Spring Data: tres nombres, un trabajo
Hasta ahora los productos vivían en un mapa: al reiniciar la aplicación, se perdían. Para guardarlos de verdad hace falta una base de datos, y una base de datos habla SQL, no objetos de Java. Entre los dos mundos hay tres piezas que vas a oír nombrar juntas:
- JPA (Jakarta Persistence) es la especificación: un conjunto de anotaciones y reglas para decir «esta clase se guarda en esta tabla».
- Hibernate es la implementación de JPA que usa Spring Boot: el programa que de verdad genera el SQL, lo ejecuta y convierte las filas en objetos.
- Spring Data JPA va encima y te ahorra el resto: escribes una interfaz con nombres de métodos y Spring escribe la implementación.
Piénsalo así
Tú hablas español y la base de datos habla SQL. Hibernate es el intérprete que traduce cada frase. Spring Data es el asistente que, con solo oír «búscame los productos de pantallas ordenados por precio», le dicta al intérprete la frase exacta.
El proyecto
En start.spring.io elige tres dependencias: Spring Web, Spring Data JPA y H2 Database. H2 es una base de datos escrita en Java que puede vivir en la memoria de tu aplicación: no instalas nada y cada arranque empieza con la base vacía. Es perfecta para aprender y para las pruebas; en producción la cambiarás por PostgreSQL o MySQL. El pom.xml queda así:
<dependencies> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-webmvc</artifactId> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-data-jpa</artifactId> </dependency> <dependency> <groupId>com.h2database</groupId> <artifactId>h2</artifactId> <scope>runtime</scope> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-webmvc-test</artifactId> <scope>test</scope> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-data-jpa-test</artifactId> <scope>test</scope> </dependency> </dependencies>
Y en application.properties, dos ajustes que te convienen al aprender:
spring.application.name=catalogo spring.jpa.show-sql=true spring.jpa.open-in-view=false
spring.jpa.show-sql=true imprime cada sentencia SQL que ejecuta Hibernate, para que veas qué pasa por debajo. spring.jpa.open-in-view=false apaga un comportamiento que viene encendido de fábrica y que mantiene abierta la conexión a la base durante toda la petición web; Spring Boot mismo advierte en el registro cuando lo dejas encendido, y en las rarezas está por qué conviene apagarlo.
¿No configuraste la conexión a la base de datos? No hace falta: al ver H2 entre las dependencias, Spring Boot crea una base en memoria con un nombre al azar y se conecta solo. Es la autoconfiguración de la lección 1 en acción.
La entidad: una clase, una tabla
Una entidad es una clase cuyos objetos se guardan como filas de una tabla. Se marca con @Entity, y su llave primaria con @Id:
package com.ejemplo.catalogo;
import jakarta.persistence.Entity;
import jakarta.persistence.GeneratedValue;
import jakarta.persistence.GenerationType;
import jakarta.persistence.Id;
import java.math.BigDecimal;
@Entity
public class Producto {
@Id
@GeneratedValue(strategy = GenerationType.IDENTITY)
private Long id;
private String nombre;
private String categoria;
private BigDecimal precio;
private int existencias;
protected Producto() {
// JPA necesita un constructor sin argumentos
}
public Producto(String nombre, String categoria, BigDecimal precio, int existencias) {
this.nombre = nombre;
this.categoria = categoria;
this.precio = precio;
this.existencias = existencias;
}
public Long getId() { return id; }
public String getNombre() { return nombre; }
public String getCategoria() { return categoria; }
public BigDecimal getPrecio() { return precio; }
public int getExistencias() { return existencias; }
public void setExistencias(int existencias) { this.existencias = existencias; }
}@GeneratedValue(strategy = GenerationType.IDENTITY) deja que la base asigne el id al insertar. El constructor sin argumentos es obligatorio para JPA, porque Hibernate crea el objeto vacío y después le pone los valores; lo dejamos protected para que tu código use el otro. Una entidad no puede ser un record: Hibernate necesita poder cambiar sus campos.
¿Y la tabla? Con una base en memoria, Spring Boot le pide a Hibernate que la cree al arrancar y la borre al terminar. Con show-sql se ve la sentencia:
registro al arrancarHibernate: create table producto (existencias integer not null, precio numeric(38,2), id bigint generated by default as identity, categoria varchar(255), nombre varchar(255), primary key (id))
El repositorio: una interfaz y nada más
Aquí está la parte que parece magia. Esta interfaz no tiene ninguna clase que la implemente, y aun así funciona:
package com.ejemplo.catalogo;
import java.math.BigDecimal;
import java.util.List;
import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.data.jpa.repository.Query;
public interface ProductoRepository extends JpaRepository<Producto, Long> {
List<Producto> findByCategoriaOrderByPrecioAsc(String categoria);
List<Producto> findByNombreContainingIgnoreCase(String texto);
long countByExistenciasLessThan(int minimo);
@Query("select p from Producto p where p.precio <= :max and p.existencias > 0 order by p.precio desc")
List<Producto> disponiblesHasta(BigDecimal max);
}Al extender JpaRepository<Producto, Long> (la entidad y el tipo de su id), recibes gratis decenas de métodos: save, saveAll, findById, findAll, count, deleteById… Al arrancar, Spring Data crea un bean que implementa la interfaz, y lo inyectas como cualquier otro.
Consultas derivadas del nombre
Los demás métodos son consultas derivadas: Spring Data lee el nombre del método, lo parte en pedazos y arma la consulta. findByCategoriaOrderByPrecioAsc significa «busca por categoría, ordenado por precio de menor a mayor»; countByExistenciasLessThan, «cuenta los que tengan menos existencias que…». Las palabras clave más usadas son And, Or, Between, LessThan, GreaterThan, Containing, StartingWith, IgnoreCase, OrderBy e In.
Cuando el nombre se volvería larguísimo, como en disponiblesHasta, es mejor escribir la consulta con @Query. Va en JPQL, que se parece a SQL pero habla de clases y atributos (Producto, p.precio) en vez de tablas y columnas; el :max se llena con el parámetro del mismo nombre.
Datos para empezar
Para que la base no arranque vacía, un CommandLineRunner guarda cinco productos con saveAll:
package com.ejemplo.catalogo;
import java.math.BigDecimal;
import java.util.List;
import org.springframework.boot.CommandLineRunner;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
@Configuration
public class DatosIniciales {
@Bean
CommandLineRunner cargar(ProductoRepository repo) {
return args -> repo.saveAll(List.of(
new Producto("Teclado mecánico", "accesorios", new BigDecimal("1299.00"), 8),
new Producto("Mouse inalámbrico", "accesorios", new BigDecimal("349.50"), 25),
new Producto("Monitor 24 pulgadas", "pantallas", new BigDecimal("3299.00"), 4),
new Producto("Mouse vertical", "accesorios", new BigDecimal("689.00"), 0),
new Producto("Monitor 27 pulgadas 4K", "pantallas", new BigDecimal("7499.00"), 2)));
}
}Usarlo desde el controlador
El controlador recibe el repositorio por el constructor y llama a sus métodos. Es el mismo estilo de la lección 3, pero ahora los datos vienen de la base:
package com.ejemplo.catalogo;
import java.math.BigDecimal;
import java.util.List;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;
@RestController
@RequestMapping("/productos")
public class ProductoController {
private final ProductoRepository repo;
private final VentaService ventas;
public ProductoController(ProductoRepository repo, VentaService ventas) {
this.repo = repo;
this.ventas = ventas;
}
@GetMapping
public List<Producto> todos() {
return repo.findAll();
}
@GetMapping("/{id}")
public ResponseEntity<Producto> uno(@PathVariable long id) {
return ResponseEntity.of(repo.findById(id));
}
@GetMapping("/categoria/{categoria}")
public List<Producto> deCategoria(@PathVariable String categoria) {
return repo.findByCategoriaOrderByPrecioAsc(categoria);
}
@GetMapping("/buscar")
public List<Producto> buscar(@RequestParam String texto) {
return repo.findByNombreContainingIgnoreCase(texto);
}
@GetMapping("/por-surtir")
public long porSurtir() {
return repo.countByExistenciasLessThan(5);
}
@GetMapping("/disponibles")
public List<Producto> disponibles(@RequestParam BigDecimal max) {
return repo.disponiblesHasta(max);
}
@PostMapping("/{id}/vender")
public ResponseEntity<?> vender(@PathVariable long id, @RequestParam int cantidad) {
try {
return ResponseEntity.ok(ventas.vender(id, cantidad));
} catch (VentaService.SinExistenciasException e) {
return ResponseEntity.status(HttpStatus.CONFLICT).body(e.getMessage());
}
}
}terminal$ curl -s localhost:8080/productos/2
{"nombre":"Mouse inalámbrico","categoria":"accesorios","precio":349.50,"existencias":25,"id":2}
$ curl -s localhost:8080/productos/categoria/pantallas
[{"nombre":"Monitor 24 pulgadas","categoria":"pantallas","precio":3299.00,"existencias":4,"id":3},{"nombre":"Monitor 27 pulgadas 4K","categoria":"pantallas","precio":7499.00,"existencias":2,"id":5}]
$ curl -s "localhost:8080/productos/buscar?texto=MOUSE"
[{"nombre":"Mouse inalámbrico","categoria":"accesorios","precio":349.50,"existencias":25,"id":2},{"nombre":"Mouse vertical","categoria":"accesorios","precio":689.00,"existencias":0,"id":4}]
$ curl -s localhost:8080/productos/por-surtir
3
$ curl -s "localhost:8080/productos/disponibles?max=1000"
[{"nombre":"Mouse inalámbrico","categoria":"accesorios","precio":349.50,"existencias":25,"id":2}]Cada petición se tradujo en SQL. Estas son las sentencias que Hibernate imprimió para las consultas derivadas y la de @Query:
registro: el SQL que generó HibernateHibernate: select p1_0.id,p1_0.categoria,p1_0.existencias,p1_0.nombre,p1_0.precio from producto p1_0 where p1_0.categoria=? order by p1_0.precio Hibernate: select p1_0.id,p1_0.categoria,p1_0.existencias,p1_0.nombre,p1_0.precio from producto p1_0 where upper(p1_0.nombre) like upper(?) escape '\' Hibernate: select count(p1_0.id) from producto p1_0 where p1_0.existencias<? Hibernate: select p1_0.id,p1_0.categoria,p1_0.existencias,p1_0.nombre,p1_0.precio from producto p1_0 where p1_0.precio<=? and p1_0.existencias>0 order by p1_0.precio desc
Fíjate en like upper(?) escape '\': Spring Data agregó los % alrededor del texto y escapó los caracteres especiales por ti. Y el texto del cliente nunca se pega dentro del SQL: viaja aparte, en el ?. Eso evita la inyección SQL, uno de los ataques más comunes.
Transacciones: todo o nada
Vender un producto parece una sola operación, pero son varias: leer el producto, restar las existencias, revisar que no queden en negativo y guardar. Si algo falla a la mitad, no quieres que quede guardada la mitad. Para eso existen las transacciones: un grupo de cambios que se aplican todos juntos o no se aplica ninguno.
Piénsalo así
Una transferencia bancaria resta de una cuenta y suma a otra. Si el sistema se cae entre los dos pasos, el banco no puede dejar el dinero en el aire: o pasan los dos movimientos, o ninguno.
package com.ejemplo.catalogo;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;
@Service
public class VentaService {
private final ProductoRepository repo;
public VentaService(ProductoRepository repo) {
this.repo = repo;
}
@Transactional
public Producto vender(long id, int cantidad) {
Producto p = repo.findById(id).orElseThrow();
p.setExistencias(p.getExistencias() - cantidad); // Hibernate guardará el cambio al terminar
if (p.getExistencias() < 0) {
throw new SinExistenciasException(p.getNombre()); // ... salvo que algo falle: entonces se deshace
}
return p;
}
public static class SinExistenciasException extends RuntimeException {
public SinExistenciasException(String nombre) {
super("No hay suficientes existencias de " + nombre);
}
}
}@Transactional abre una transacción al entrar al método y la confirma al salir. Dentro, no hace falta llamar a save: Hibernate vigila la entidad que cargó y, al confirmar, guarda lo que cambió. Pero si el método lanza una excepción no verificada (una RuntimeException, como SinExistenciasException), la transacción se deshace: es un rollback. Compruébalo: el monitor de 24 pulgadas tiene 4 piezas.
terminal$ curl -s -X POST "localhost:8080/productos/3/vender?cantidad=3"
{"nombre":"Monitor 24 pulgadas","categoria":"pantallas","precio":3299.00,"existencias":1,"id":3}
$ curl -s -w " (código %{http_code})\n" -X POST "localhost:8080/productos/3/vender?cantidad=2"
No hay suficientes existencias de Monitor 24 pulgadas (código 409)
$ curl -s localhost:8080/productos/3
{"nombre":"Monitor 24 pulgadas","categoria":"pantallas","precio":3299.00,"existencias":1,"id":3}La primera venta dejó 1 pieza. La segunda restó 2, quedaron -1 en el objeto, se lanzó la excepción y el cambio nunca llegó a la base: la consulta final sigue diciendo 1. Ojo: con una excepción verificada (las que extienden Exception), Spring no deshace la transacción por omisión. Es una de las trampas más famosas, y la demostramos en las rarezas.
El error que te ahorra: un error de dedo en el nombre del método
Como la consulta sale del nombre, un error de dedo no lo detecta el compilador, sino Spring Data al arrancar. Escribimos findByNombrContainingIgnoreCase, sin la e:
registro: la aplicación no arranca (fragmento de la última línea Caused by)Caused by: org.springframework.beans.factory.BeanCreationException: Error creating bean with name 'productoRepository' … No property 'nombr' found for type 'Producto'; Did you mean 'nombre'
El mensaje dice qué propiedad no encontró y hasta sugiere la correcta. La buena noticia es que el error aparece al arrancar, no cuando un cliente usa la búsqueda: por eso conviene tener al menos una prueba que arranque la aplicación completa, como en la lección 7.
De H2 a una base de datos de verdad
Para usar PostgreSQL, cambias la dependencia de H2 por la del controlador de PostgreSQL y le dices a Spring Boot dónde está la base. Tu código, la entidad y el repositorio no cambian:
<dependency> <groupId>org.postgresql</groupId> <artifactId>postgresql</artifactId> <scope>runtime</scope> </dependency>
spring.datasource.url=jdbc:postgresql://localhost:5432/tienda
spring.datasource.username=tienda
spring.datasource.password=${DB_PASSWORD}
spring.jpa.hibernate.ddl-auto=validateCon una base real, no dejes que Hibernate cree ni borre tablas: ddl-auto=validate solo revisa que la tabla coincida con la entidad. Las tablas se crean con scripts de migración versionados, que es justo lo que hace Flyway; lo verás en el ejemplo de Flyway. Si nunca has usado PostgreSQL, tenemos una guía para principiantes.
Retos
Reto 1. Agrega al repositorio una consulta derivada que busque por categoría y un rango de precios, y un endpoint GET /productos/rango?categoria=...&desde=...&hasta=....
Ver la solución
List<Producto> findByCategoriaAndPrecioBetween(String categoria, BigDecimal desde, BigDecimal hasta);
terminal$ curl -s "localhost:8080/productos/rango?categoria=accesorios&desde=300&hasta=700"
[{"nombre":"Mouse inalámbrico","categoria":"accesorios","precio":349.50,"existencias":25,"id":2},{"nombre":"Mouse vertical","categoria":"accesorios","precio":689.00,"existencias":0,"id":4}]Between incluye los dos extremos. Los parámetros se llenan en el orden en que aparecen en el nombre: primero la categoría, después el inicio y el fin del rango. No hizo falta escribir SQL.
Reto 2. Sin ejecutarlo: ¿qué devuelve repo.findById(99) si no existe el producto 99? ¿Y repo.findByCategoriaOrderByPrecioAsc("muebles")?
Ver la solución
findById devuelve un Optional vacío, nunca null; por eso el controlador usa ResponseEntity.of para responder 404. La consulta derivada devuelve una lista vacía. Spring Data nunca te da null en lugar de una colección.
Reto 3. En VentaService, ¿qué pasaría si quitas @Transactional? Piensa en dos cosas: si el cambio se guarda, y si el rollback ocurre.
Ver la solución
Sin transacción alrededor del método, la entidad que devuelve findById queda «suelta» en cuanto termina esa llamada: cambiarle las existencias ya no se guarda solo, así que una venta correcta no restaría nada en la base. Habría que llamar a repo.save(p), y entonces el error contrario: si guardas antes de revisar, el negativo se queda guardado. @Transactional resuelve las dos cosas a la vez.
Cada proyecto de esta lección se compiló con Spring Boot 4.2.0, Java 25 (Temurin 25.0.5.1) y Maven 3.10.1 en un contenedor limpio y sin acceso a la red, se arrancó y se le hicieron las peticiones que ves con curl antes de publicar la lección; los registros, las respuestas y los errores están copiados de esa ejecución. Las horas de los registros son de la Ciudad de México.
