05 - Persistencia: JPA con EntityManager
En 1.º DAW la persistencia se implementó con JDBC: SQL explícito, PreparedStatement y mapeo manual de ResultSet a objetos. JPA (Jakarta Persistence API) define una forma de relacionar objetos Java con datos persistentes. Un proveedor como Hibernate interpreta ese mapeo y ejecuta las operaciones necesarias sobre la base de datos.
En Spring podemos utilizar directamente el EntityManager o apoyarnos en Spring Data JPA, que simplifica operaciones frecuentes. JPA es una especificación; Hibernate es una de sus implementaciones. Usar JPA no elimina la necesidad de comprender el esquema, las consultas ni las transacciones.
| Aspecto | JDBC | JPA |
|---|---|---|
| SQL | Habitualmente se escribe para cada operación | El proveedor genera SQL a partir del mapeo; también admite consultas explícitas |
| Conversión de filas | Manual, desde ResultSet | El proveedor reconstruye entidades a partir de los datos |
| Modificaciones | Se ejecuta un UPDATE explícito | El contexto de persistencia detecta cambios en entidades gestionadas |
| Acceso | API JDBC | EntityManager u otra abstracción basada en JPA |
1. Configuración de la persistencia
Una aplicación necesita un proveedor JPA, un controlador para la base de datos y un esquema compatible con las entidades.
1.1 Dependencias
En una aplicación Spring Boot con Maven, estas dependencias permiten trabajar con JPA, MariaDB y migraciones Flyway:
<dependencies> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-data-jpa</artifactId> </dependency> <dependency> <groupId>org.mariadb.jdbc</groupId> <artifactId>mariadb-java-client</artifactId> <scope>runtime</scope> </dependency> <dependency> <groupId>org.flywaydb</groupId> <artifactId>flyway-core</artifactId> </dependency> <dependency> <groupId>org.flywaydb</groupId> <artifactId>flyway-mysql</artifactId> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-test</artifactId> <scope>test</scope> </dependency> </dependencies>
El proyecto debe utilizar una versión de Spring Boot que gestione las versiones de estas dependencias. En versiones recientes de Flyway, el soporte para MariaDB se proporciona mediante flyway-mysql; comprueba las dependencias necesarias si trabajas con otra versión. Aunque usemos EntityManager directamente, el starter aporta la integración JPA de Spring Boot y Hibernate.
1.2 Conexión y esquema
spring.datasource.url=jdbc:mariadb://localhost:3306/app spring.datasource.username=${DB_USER} spring.datasource.password=${DB_PASSWORD} spring.jpa.hibernate.ddl-auto=validate spring.jpa.open-in-view=false
DB_USERyDB_PASSWORDse suministran mediante variables de entorno; no se incluyen contraseñas en el código.- Flyway aplica migraciones versionadas para crear y modificar el esquema.
ddl-auto=validatecomprueba la compatibilidad básica del mapeo con el esquema; no crea ni actualiza las tablas. No sustituye a las pruebas de restricciones y consultas.open-in-view=falseevita mantener abierto el contexto de persistencia durante toda la petición web. Las relaciones necesarias deben cargarse y convertirse dentro de la transacción.
Para el ejemplo de pedidos, una primera migración podría guardarse en src/main/resources/db/migration/V1__create_orders.sql:
CREATE TABLE orders ( id BIGINT NOT NULL AUTO_INCREMENT, customer_id VARCHAR(100) NOT NULL, STATUS VARCHAR(20) NOT NULL, PRIMARY KEY (id) ); CREATE TABLE order_lines ( id BIGINT NOT NULL AUTO_INCREMENT, order_id BIGINT NOT NULL, product_id VARCHAR(100) NOT NULL, quantity INT NOT NULL, PRIMARY KEY (id), CONSTRAINT fk_order_lines_order FOREIGN KEY (order_id) REFERENCES orders (id) );
La base de datos y el usuario deben existir antes de arrancar la aplicación, y el usuario debe tener permisos para aplicar las migraciones.
2. Entidades y mapeo
Una entidad JPA es un objeto cuya identidad y persistencia gestiona el proveedor. En nuestra arquitectura, las entidades pertenecen a persistence: describen cómo se almacenan los datos. El modelo de domain representa los conceptos y reglas del negocio. Aunque ambos representen un mismo pedido, no son el mismo objeto: un mapper convierte entre ambas representaciones.
2.1 Anotaciones principales
| Anotación | Función |
|---|---|
@Entity | Declara una clase como entidad JPA |
@Table(name = “…”) | Indica la tabla asociada |
@Id | Marca el identificador de la entidad |
@GeneratedValue | Indica cómo se genera el identificador |
@Column | Configura la columna: nombre, nulabilidad, longitud y otras propiedades |
@Enumerated(EnumType.STRING) | Almacena el nombre de una constante de un enum |
@Embedded | Incluye en la entidad los atributos de un tipo embebido |
@Embeddable | Declara un tipo cuyos atributos pueden formar parte de una entidad |
@Transient | Excluye un atributo del mapeo persistente |
@Version | Marca una versión para detectar conflictos de concurrencia optimista |
Una entidad necesita un constructor sin argumentos public o protected para que JPA pueda instanciarla. La clase y los elementos persistentes no deben ser final. En los ejemplos se usa acceso por campos: como @Id está sobre un campo, JPA accede a los campos persistentes. También existe acceso por propiedades, con las anotaciones en los getters; evita mezclar ambos sin configurar explícitamente el acceso.
GenerationType.IDENTITY delega la generación del identificador en una columna autoincremental de la base de datos. El proveedor puede tener que ejecutar el INSERT antes del flush para obtenerlo. Con EnumType.STRING, PENDING se almacena como texto: es legible, pero cambiar el nombre de una constante requiere tratar los datos existentes mediante una migración.
También existen otras estrategias de identificador: SEQUENCE utiliza una secuencia de la base de datos, TABLE una tabla de generación y AUTO deja la elección al proveedor. Su disponibilidad y comportamiento dependen de la base de datos y su configuración. Sin @GeneratedValue, la aplicación asigna el identificador.
En @Column, name establece el nombre de la columna, nullable y unique describen restricciones, length se usa para columnas de texto y precision/scale para decimales. insertable y updatable controlan si el proveedor incluye la columna en esas sentencias. Estas opciones no reemplazan las restricciones reales del esquema: cuando Flyway gestiona las tablas, hay que definirlas en las migraciones.
2.2 Tipos embebidos
Un tipo embebido agrupa atributos que pertenecen a una entidad, pero no tiene identidad propia como entidad:
@Embeddable public class AddressEntity { @Column(name = "street", nullable = false) private String street; @Column(name = "city", nullable = false) private String city; protected AddressEntity() { } public AddressEntity(String street, String city) { this.street = street; this.city = city; } }
Una entidad podría incorporarlo con @Embedded private AddressEntity address;. Sus columnas formarían parte de la tabla de esa entidad. Un value object del dominio puede transformarse a este tipo mediante el mapper, sin convertir el propio value object en una entidad JPA.
3. Relaciones entre entidades
Las anotaciones deben corresponderse con las claves externas o tablas intermedias del esquema:
| Relación | Anotaciones habituales | Representación frecuente |
|---|---|---|
| Uno a muchos | @OneToMany y @ManyToOne | Clave externa en el lado «muchos» |
| Uno a uno | @OneToOne | Clave externa o clave primaria compartida |
| Muchos a muchos | @ManyToMany | Tabla intermedia con claves externas |
En el ejemplo, un pedido tiene varias líneas y cada línea pertenece a un pedido. La columna order_lines.order_id contiene la clave externa; las clases completas aparecen en el apartado 5.
3.1 Propietario de la relación
En una relación bidireccional, el lado propietario es el que JPA utiliza para actualizar la relación en la base de datos.
OrderLineEntity.order, anotado con@ManyToOne, es el propietario: su@JoinColumn(name = “order_id”)representa la clave externa.OrderEntity.lineses el lado inverso:mappedBy = “order”señala el nombre del atributo Java que posee la relación, no el nombre de la columna.- Hay que mantener coherentes ambos lados en memoria. Añadir una línea solo a la lista del pedido no establece por sí solo
line.order.
Si la relación solo se recorriera en un sentido, podría modelarse como unidireccional. La bidireccionalidad es útil cuando se necesitan ambos recorridos, pero exige mantenerlos sincronizados.
En una relación uno a uno, el lado con @JoinColumn suele contener la clave externa; el esquema debe imponer unicidad sobre esa columna si se quiere garantizar la cardinalidad. En una relación muchos a muchos, el propietario puede declarar @JoinTable para describir la tabla intermedia y sus dos claves externas; el lado inverso usa mappedBy. Si la asociación necesita atributos propios, como fecha o cantidad, suele representarse con una entidad intermedia en lugar de @ManyToMany. Evita propagar REMOVE a entidades compartidas que pueden seguir relacionadas con otros objetos.
3.2 Cascada y eliminación de huérfanos
Cascada significa propagar determinadas operaciones de una entidad a sus entidades relacionadas:
PERSIST: propagapersist.MERGE: propagamerge.REMOVE: propagaremove.ALL: incluye las anteriores y tambiénREFRESHyDETACH.
La cascada no define la clave externa ni cambia el lado propietario. Tampoco equivale a una cláusula SQL ON DELETE CASCADE. Con orphanRemoval = true, al retirar una línea de la colección de un pedido gestionado, JPA programa su eliminación. Es apropiado cuando la línea pertenece exclusivamente a ese pedido; no debe aplicarse automáticamente a entidades compartidas.
3.3 Carga de relaciones y problema N+1
Carga perezosa (LAZY) significa que la relación puede cargarse cuando se accede a ella. Carga ansiosa (EAGER) solicita que esté disponible al recuperar la entidad. Según JPA, los valores predeterminados son:
| Anotación | Fetch predeterminado |
|---|---|
@OneToMany, @ManyToMany | LAZY |
@ManyToOne, @OneToOne | EAGER |
EAGER no garantiza una sola consulta: el proveedor puede usar consultas adicionales. LAZY expresa una estrategia de carga perezosa, pero JPA la define como una indicación al proveedor, no como una garantía absoluta en todos los casos.
LAZY evita cargar relaciones que no se usan, pero no elimina por sí solo este problema.
Para un caso de uso concreto se puede preparar una consulta con join fetch o un @EntityGraph. Hay que comprobar el SQL generado y tener cuidado con la paginación de colecciones obtenidas mediante fetch join, pues puede producir resultados o rendimiento inesperados. Con open-in-view=false, acceder a una relación aún no cargada después de cerrar el contexto puede fallar. El adaptador debe obtener y convertir los datos necesarios dentro de la transacción.
En una arquitectura modular, una entidad de un módulo no debería depender directamente de las entidades internas de otro. Puede guardar el identificador del recurso externo y consultar al otro módulo mediante sus contratos.
4. EntityManager y ciclo de vida
El EntityManager es la API principal de JPA para gestionar entidades y consultas. En Spring se puede obtener mediante @PersistenceContext. El contexto de persistencia mantiene las entidades gestionadas durante una unidad de trabajo y garantiza, dentro de ese contexto, una identidad gestionada para cada entidad de un tipo e identificador.
4.1 Operaciones principales
| Operación | Uso |
|---|---|
persist(entity) | Hace gestionada una entidad nueva y programa su inserción |
find(Entity.class, id) | Busca por tipo e identificador; devuelve null si no existe |
merge(entity) | Copia el estado al contexto y devuelve la instancia gestionada |
remove(entity) | Marca una entidad gestionada para su eliminación |
flush() | Sincroniza los cambios pendientes con la base de datos |
clear() | Separa todas las entidades del contexto |
detach(entity) | Separa una entidad concreta |
Una entidad puede encontrarse en estos estados:
- Nueva: se ha creado en Java, pero aún no pertenece a un contexto de persistencia.
- Gestionada: pertenece al contexto; JPA detecta cambios en sus atributos persistentes.
- Separada: representa una entidad persistente, pero ya no está gestionada por ese contexto.
- Eliminada: se ha marcado para borrar dentro del contexto; el borrado se sincroniza con la base de datos.
4.2 Cambios gestionados y merge
Si una entidad gestionada cambia dentro de una transacción, el proveedor detecta la diferencia y puede generar un UPDATE al sincronizar. Este mecanismo se conoce como dirty checking.
OrderEntity entity = entityManager.find(OrderEntity.class, orderId); entity.status = OrderStatus.CANCELLED; // Si la entidad sigue gestionada, JPA detecta el cambio.
El fragmento presupone una transacción activa y que el pedido existe. merge funciona de otra manera:
OrderEntity managed = entityManager.merge(detached); managed.status = OrderStatus.CANCELLED;
detached estaba separada, no se vuelve gestionada por llamar a merge. JPA copia su estado y devuelve la instancia gestionada, que puede ser distinta. Hay que continuar trabajando con el valor devuelto.
Copiar un grafo separado incompleto puede sobrescribir asociaciones o provocar eliminaciones no deseadas. Para modificar un pedido existente, el ejemplo de este tema carga la entidad gestionada y actualiza sus líneas explícitamente. El dirty checking afecta a entidades gestionadas, no a los objetos del dominio convertidos por un mapper. Si cambiamos un objeto Order del dominio, debemos comunicar ese cambio al repositorio; JPA no observa ese objeto.
4.3 Flush no es commit
flush() envía a la base de datos las inserciones, actualizaciones y eliminaciones pendientes. Permite, por ejemplo, detectar algunas violaciones de restricciones antes de que termine el método.
flushno confirma la transacción; unrollbackposterior revierte los cambios transaccionales ya sincronizados.- El proveedor puede sincronizar antes de un
flushexplícito, por ejemplo antes de algunas consultas o para obtener un identificador. - El
commitconfirma la transacción; normalmente incluye la sincronización necesaria de los cambios pendientes.
5. Ejemplo: pedido y líneas
El ejemplo utiliza estas responsabilidades:
domaincontiene el modelo y el contratoOrderRepository.persistence.dao.entitycontiene las entidades anotadas.persistence.daodefine la interfazOrderDao.persistence.dao.impl.jpaimplementa el DAO conEntityManager.persistence.repository.mapperconvierte entre entidades y modelo.persistence.repository.implimplementa el repositorio del dominio utilizando el DAO y el mapper.
OrderEntity, pero esa dependencia queda dentro de persistence. El dominio sigue siendo independiente de JPA. Una abstracción DAO que tampoco conociera entidades JPA necesitaría otros tipos en su contrato y una conversión adicional.
En los bloques Java siguientes, cada clase o interfaz pública va en su propio archivo, en el paquete indicado. Se omiten algunos import para centrarse en la implementación; las anotaciones JPA pertenecen a jakarta.persistence y las de Spring a sus paquetes correspondientes.
Los nombres de paquetes son abreviados para mostrar las responsabilidades. En una aplicación real, sitúa domain y persistence bajo un paquete raíz común al de la aplicación Spring Boot, o configura explícitamente el escaneo de componentes, entidades y repositorios. Adapta también el nombre completo del constructor JPQL del apartado 6 al paquete real.
5.1 Modelo y contrato del dominio
// domain/model/OrderStatus.java package domain.model; public enum OrderStatus { PENDING, CANCELLED }
// domain/model/OrderLine.java package domain.model; public record OrderLine(Long id, String productId, int quantity) { public OrderLine { if (productId == null || productId.isBlank() || quantity <= 0) { throw new IllegalArgumentException("Invalid order line"); } } }
// domain/model/Order.java package domain.model; import java.util.List; public record Order(Long id, String customerId, OrderStatus status, List<OrderLine> lines) { public Order { if (customerId == null || customerId.isBlank() || status == null) { throw new IllegalArgumentException("Invalid order"); } lines = List.copyOf(lines); } public Order cancel() { if (status != OrderStatus.PENDING) { throw new IllegalStateException("Only pending orders can be cancelled"); } return new Order(id, customerId, OrderStatus.CANCELLED, lines); } }
// domain/repository/OrderRepository.java package domain.repository; import domain.model.Order; import java.util.Optional; public interface OrderRepository { Optional<Order> findById(long id); Order save(Order order); }
Los registros son inmutables: cancel() devuelve un pedido nuevo. Un pedido o una línea sin persistir tienen id == null.
5.2 Entidades JPA
Para mantener el ejemplo pequeño, sus campos son públicos. En una aplicación real se pueden encapsular con getters y métodos de modificación; JPA sigue pudiendo usar acceso por campos.
// persistence/dao/entity/OrderEntity.java package persistence.dao.entity; import domain.model.OrderStatus; import java.util.ArrayList; import java.util.List; @Entity @Table(name = "orders") public class OrderEntity { @Id @GeneratedValue(strategy = GenerationType.IDENTITY) public Long id; @Column(name = "customer_id", nullable = false, length = 100) public String customerId; @Enumerated(EnumType.STRING) @Column(name = "status", nullable = false, length = 20) public OrderStatus status; @OneToMany(mappedBy = "order", cascade = CascadeType.ALL, orphanRemoval = true, fetch = FetchType.LAZY) public List<OrderLineEntity> lines = new ArrayList<>(); protected OrderEntity() { } public OrderEntity(String customerId, OrderStatus status) { this.customerId = customerId; this.status = status; } public void addLine(OrderLineEntity line) { lines.add(line); line.order = this; } public void removeLine(OrderLineEntity line) { lines.remove(line); line.order = null; } }
// persistence/dao/entity/OrderLineEntity.java package persistence.dao.entity; @Entity @Table(name = "order_lines") public class OrderLineEntity { @Id @GeneratedValue(strategy = GenerationType.IDENTITY) public Long id; @ManyToOne(fetch = FetchType.LAZY, optional = false) @JoinColumn(name = "order_id", nullable = false) public OrderEntity order; @Column(name = "product_id", nullable = false, length = 100) public String productId; @Column(name = "quantity", nullable = false) public int quantity; protected OrderLineEntity() { } public OrderLineEntity(String productId, int quantity) { this.productId = productId; this.quantity = quantity; } }
addLine y removeLine mantienen los dos lados de la relación. En la eliminación, orphanRemoval programa el borrado de la línea; no se pretende conservarla con order_id nulo. Aquí la entidad reutiliza OrderStatus, un tipo del dominio. La dependencia va de persistence hacia domain, no al contrario.
5.3 DAO con EntityManager
// persistence/dao/OrderDao.java package persistence.dao; import java.util.Optional; import persistence.dao.entity.OrderEntity; public interface OrderDao { Optional<OrderEntity> findById(long id); OrderEntity save(OrderEntity entity); void flush(); }
// persistence/dao/impl/jpa/OrderDaoJpa.java package persistence.dao.impl.jpa; import java.util.Optional; import persistence.dao.OrderDao; import persistence.dao.entity.OrderEntity; @Repository public class OrderDaoJpa implements OrderDao { @PersistenceContext private EntityManager entityManager; @Override public Optional<OrderEntity> findById(long id) { return Optional.ofNullable(entityManager.find(OrderEntity.class, id)); } @Override public OrderEntity save(OrderEntity entity) { if (entity.id == null) { entityManager.persist(entity); return entity; } if (entityManager.contains(entity)) { return entity; } return entityManager.merge(entity); } @Override public void flush() { entityManager.flush(); } }
El DAO presupone que se ejecuta dentro de una transacción para las operaciones de escritura. Para una entidad nueva utiliza persist; para una separada devuelve el resultado de merge. Si ya está gestionada, no necesita volver a guardarla para que JPA detecte sus cambios.
La rama de merge es parte del contrato de este DAO, pero el adaptador siguiente no construye un grafo separado para actualizar pedidos existentes: primero carga la entidad y modifica su colección gestionada. Así evita reemplazarla accidentalmente por una colección parcial.
5.4 Mapper manual
El mapper convierte datos y sincroniza la representación persistente; no decide si una operación de negocio, como cancelar un pedido, está permitida.
// persistence/repository/mapper/OrderPersistenceMapper.java package persistence.repository.mapper; import domain.model.Order; import domain.model.OrderLine; import java.util.ArrayList; import java.util.HashMap; import java.util.HashSet; import java.util.Map; import java.util.Set; import persistence.dao.entity.OrderEntity; import persistence.dao.entity.OrderLineEntity; @Component public class OrderPersistenceMapper { public Order toModel(OrderEntity entity) { return new Order(entity.id, entity.customerId, entity.status, entity.lines.stream() .map(line -> new OrderLine( line.id, line.productId, line.quantity)) .toList()); } public OrderEntity toNewEntity(Order order) { if (order.id() != null || order.lines().stream().anyMatch(line -> line.id() != null)) { throw new IllegalArgumentException("A new order cannot contain existing IDs"); } OrderEntity entity = new OrderEntity(order.customerId(), order.status()); for (OrderLine line : order.lines()) { entity.addLine(new OrderLineEntity(line.productId(), line.quantity())); } return entity; } public void updateManagedEntity(Order order, OrderEntity entity) { Map<Long, OrderLineEntity> existing = new HashMap<>(); for (OrderLineEntity line : entity.lines) { existing.put(line.id, line); } // Validar antes de modificar el grafo gestionado. Set<Long> retainedIds = new HashSet<>(); for (OrderLine line : order.lines()) { if (line.id() != null && (!existing.containsKey(line.id()) || !retainedIds.add(line.id()))) { throw new IllegalArgumentException("Unknown or duplicate order line ID"); } } entity.customerId = order.customerId(); entity.status = order.status(); for (OrderLineEntity line : new ArrayList<>(entity.lines)) { if (!retainedIds.contains(line.id)) { entity.removeLine(line); } } for (OrderLine line : order.lines()) { if (line.id() == null) { entity.addLine(new OrderLineEntity(line.productId(), line.quantity())); } else { OrderLineEntity managedLine = existing.get(line.id()); managedLine.productId = line.productId(); managedLine.quantity = line.quantity(); } } } }
Para actualizar, el método identifica las líneas que ya pertenecen al pedido, rechaza identificadores ajenos o duplicados, retira las que no aparecen en el modelo, actualiza las conservadas y añade las nuevas mediante addLine. orphanRemoval elimina las retiradas.
El ejemplo trata la lista recibida como la colección completa deseada, no como una actualización parcial. Para una operación parcial haría falta otro contrato. Tampoco persiste el orden de la lista: si el orden es una regla de negocio, hay que modelarlo y almacenarlo explícitamente. MapStruct puede generar conversiones sencillas durante la compilación, pero no elimina la necesidad de diseñar la sincronización de relaciones gestionadas. Aquí se usa un mapper manual para hacer explícito ese comportamiento.
5.5 Adaptador del repositorio
// persistence/repository/impl/OrderRepositoryImpl.java package persistence.repository.impl; import domain.model.Order; import domain.repository.OrderRepository; import java.util.Optional; import persistence.dao.OrderDao; import persistence.dao.entity.OrderEntity; import persistence.repository.mapper.OrderPersistenceMapper; @Repository public class OrderRepositoryImpl implements OrderRepository { private final OrderDao dao; private final OrderPersistenceMapper mapper; public OrderRepositoryImpl(OrderDao dao, OrderPersistenceMapper mapper) { this.dao = dao; this.mapper = mapper; } @Override public Optional<Order> findById(long id) { return dao.findById(id).map(mapper::toModel); } @Override public Order save(Order order) { OrderEntity entity; if (order.id() == null) { entity = mapper.toNewEntity(order); } else { entity = dao.findById(order.id()) .orElseThrow(() -> new IllegalArgumentException("Order not found")); mapper.updateManagedEntity(order, entity); } OrderEntity managed = dao.save(entity); dao.flush(); return mapper.toModel(managed); } }
El adaptador se usa dentro de una transacción. findById transforma las líneas mientras el contexto está disponible. save hace flush para sincronizar la operación y disponer de los identificadores generados antes de devolver el modelo; esto no confirma la transacción.
Para simplificar, el ejemplo no implementa control de concurrencia. En una aplicación real, dos modificaciones simultáneas pueden sobrescribirse; una versión con @Version permite detectar conflictos mediante bloqueo optimista.
6. Consultas y proyecciones
6.1 JPQL
JPQL consulta entidades y atributos Java, no tablas ni columnas SQL. Este fragmento, dentro de un componente con entityManager, busca pedidos de un estado y carga sus líneas:
List<OrderEntity> orders = entityManager.createQuery( "select distinct o from OrderEntity o " + "left join fetch o.lines " + "where o.status = :status", OrderEntity.class) .setParameter("status", OrderStatus.PENDING) .getResultList();
OrderEntity,statusylinesson nombres del modelo JPA.left join fetchtambién conserva pedidos sin líneas;distinctsolicita resultados de pedidos sin duplicados.- Los valores se pasan mediante parámetros; no se concatenan datos recibidos en la consulta.
Una consulta preparada para un caso de uso evita cargar colecciones una por una. Para una lista paginada de pedidos con líneas, conviene estudiar una estrategia específica, como paginar primero identificadores y cargar después sus relaciones.
6.2 Proyección mediante constructor JPQL
Una proyección recupera únicamente los datos necesarios. JPA permite construir un objeto de resultados en JPQL:
// persistence/projection/OrderSummary.java package persistence.projection; import domain.model.OrderStatus; public record OrderSummary(Long id, String customerId, OrderStatus status) { }
List<OrderSummary> summaries = entityManager.createQuery( "select new persistence.projection.OrderSummary(" + "o.id, o.customerId, o.status) " + "from OrderEntity o where o.status = :status", OrderSummary.class) .setParameter("status", OrderStatus.PENDING) .getResultList();
JPQL requiere el nombre completo de la clase y un constructor compatible con los valores seleccionados. Los resultados son objetos normales, no entidades gestionadas: modificarlos no activa dirty checking. OrderSummary pertenece a persistencia. Si un caso de uso necesita esos datos, el adaptador los transforma a un tipo definido por la capa correspondiente; no expone esta proyección interna al dominio.
7. Transacciones
Una transacción agrupa operaciones que deben completarse juntas. commit confirma los cambios y rollback los revierte. En Spring, @Transactional permite delimitar la unidad de trabajo alrededor de un caso de uso.
@Service public class CancelOrder { private final OrderRepository orderRepository; public CancelOrder(OrderRepository orderRepository) { this.orderRepository = orderRepository; } @Transactional public void cancel(long orderId) { Order order = orderRepository.findById(orderId) .orElseThrow(() -> new IllegalArgumentException("Order not found")); Order cancelled = order.cancel(); orderRepository.save(cancelled); } }
Order es un objeto de dominio separado de OrderEntity. Por eso cancel() no modifica directamente ninguna entidad gestionada: save comunica el nuevo estado al adaptador, que actualiza la entidad. La transacción engloba tanto la lectura como la escritura. Si el método termina correctamente, Spring intenta confirmar; ante una excepción no comprobada, por defecto marca la transacción para rollback. Las excepciones comprobadas no provocan rollback por defecto, salvo configuración.
En la configuración habitual basada en proxies de Spring, la llamada debe atravesar el proxy: una llamada interna de un método a otro método @Transactional del mismo objeto no inicia por sí sola la interceptación. Mantén las transacciones suficientemente cortas para no retener recursos y bloqueos innecesariamente.
8. Spring Data JPA como alternativa
Spring Data JPA puede proporcionar las operaciones habituales de acceso a entidades sin escribir un DAO con EntityManager para cada caso. Funcionalmente cubre buena parte del papel del DAO; no genera automáticamente nuestra interfaz OrderDao.
Una interfaz interna de persistencia puede extender JpaRepository:
// persistence/dao/impl/jpa/OrderSpringDataRepository.java package persistence.dao.impl.jpa; import domain.model.OrderStatus; import java.util.List; import org.springframework.data.jpa.repository.JpaRepository; import org.springframework.data.jpa.repository.Query; import org.springframework.data.repository.query.Param; import persistence.dao.entity.OrderEntity; public interface OrderSpringDataRepository extends JpaRepository<OrderEntity, Long> { List<OrderEntity> findByStatus(OrderStatus status); @Query("select distinct o from OrderEntity o " + "left join fetch o.lines where o.status = :status") List<OrderEntity> findWithLinesByStatus(@Param("status") OrderStatus status); }
Spring Data implementa la interfaz y puede derivar consultas como findByStatus a partir del nombre. Para consultas más específicas se puede usar @Query.
8.1 Integración con la arquitectura
Hay dos opciones coherentes:
- El adaptador del repositorio de dominio utiliza directamente
OrderSpringDataRepositorycomo detalle interno depersistence. - Se conserva
OrderDaoy se escribe un adaptador que delega en Spring Data. En ese caso, se sustituyeOrderDaoJpapor este adaptador, evitando registrar dos implementaciones ambiguas deOrderDao.
El siguiente bloque ilustra la segunda opción:
// persistence/dao/impl/jpa/SpringDataOrderDao.java package persistence.dao.impl.jpa; import java.util.Optional; import persistence.dao.OrderDao; import persistence.dao.entity.OrderEntity; @Repository public class SpringDataOrderDao implements OrderDao { private final OrderSpringDataRepository repository; public SpringDataOrderDao(OrderSpringDataRepository repository) { this.repository = repository; } @Override public Optional<OrderEntity> findById(long id) { return repository.findById(id); } @Override public OrderEntity save(OrderEntity entity) { return repository.save(entity); } @Override public void flush() { repository.flush(); } }
No se hace que OrderSpringDataRepository extienda a la vez JpaRepository y OrderDao: sus firmas de save no son equivalentes y pueden entrar en conflicto por sus genéricos. La delegación mantiene ambos contratos separados. Como ocurre con merge, hay que utilizar el valor devuelto por save. El adaptador de dominio sigue cargando y actualizando la entidad gestionada para evitar sustituir relaciones por un grafo incompleto.
8.2 Proyección por interfaz de Spring Data
Spring Data también admite proyecciones mediante interfaces. Esto es una funcionalidad de Spring Data, no una proyección por interfaz definida por JPA:
// persistence/projection/OrderSummaryView.java package persistence.projection; import domain.model.OrderStatus; public interface OrderSummaryView { Long getId(); String getCustomerId(); OrderStatus getStatus(); }
El siguiente método se añadiría a OrderSpringDataRepository:
List<OrderSummaryView> findProjectedByStatus(OrderStatus status);
Spring Data crea vistas de los resultados a partir de las propiedades solicitadas. Estas proyecciones tampoco son entidades gestionadas y deben permanecer dentro de persistence; el adaptador las transforma si otro componente necesita sus datos.
| Opción | Característica |
|---|---|
EntityManager | Control explícito de operaciones y consultas JPA |
JpaRepository | Reduce código repetitivo para CRUD y consultas habituales |
| Constructor JPQL | Proyección de JPA hacia una clase o registro con constructor compatible |
| Proyección por interfaz | Funcionalidad proporcionada por Spring Data |
Ninguna de estas opciones exige que el dominio conozca Hibernate, EntityManager o Spring Data.
9. Pruebas de persistencia
Las pruebas de persistencia comprueban aspectos que un mock no verifica: el esquema, el mapeo, las relaciones, las consultas y la interacción con la base de datos.
@DataJpaTest prepara la infraestructura JPA y ejecuta cada prueba en una transacción que normalmente se revierte al terminar. Para probar también el adaptador y el mapper, se importan explícitamente sus componentes.
El siguiente ejemplo usa una base MariaDB de pruebas configurada mediante las propiedades del entorno. @AutoConfigureTestDatabase(replace = NONE) impide que Spring la sustituya por una base embebida. La base debe estar disponible y Flyway debe poder aplicar la migración anterior.
@DataJpaTest @AutoConfigureTestDatabase(replace = AutoConfigureTestDatabase.Replace.NONE) @Import({ OrderDaoJpa.class, OrderPersistenceMapper.class, OrderRepositoryImpl.class }) class OrderPersistenceTest { @Autowired private OrderRepository orderRepository; @PersistenceContext private EntityManager entityManager; @Test void savesAndReloadsOrderWithLines() { Order order = new Order(null, "customer-123", OrderStatus.PENDING, List.of(new OrderLine(null, "product-1", 2))); Order saved = orderRepository.save(order); entityManager.flush(); entityManager.clear(); Order loaded = orderRepository.findById(saved.id()).orElseThrow(); assertThat(loaded.customerId()).isEqualTo("customer-123"); assertThat(loaded.status()).isEqualTo(OrderStatus.PENDING); assertThat(loaded.lines()).hasSize(1); assertThat(loaded.lines().get(0).productId()).isEqualTo("product-1"); assertThat(loaded.lines().get(0).quantity()).isEqualTo(2); } }
Los imports de anotaciones y aserciones se omiten, igual que en los ejemplos anteriores. flush() fuerza la sincronización; clear() separa las entidades para que la lectura posterior no reutilice simplemente la instancia que seguía en el contexto. Una caché de segundo nivel, si se habilita, puede intervenir en la recuperación; hay que tenerla en cuenta cuando la prueba pretenda verificar una consulta concreta a la base de datos.
También conviene probar:
- La eliminación de una línea con
orphanRemovaly la actualización de líneas existentes. - El rechazo de identificadores de líneas pertenecientes a otro pedido.
- Las consultas JPQL y las relaciones que deben cargarse.
- Los errores de restricciones y el rollback.
- El comportamiento transaccional mediante una prueba que atraviese el servicio y compruebe los datos después de finalizar la transacción.
Para automatizar pruebas reproducibles puede utilizarse Testcontainers con MariaDB. Probar contra la misma tecnología que producción reduce las diferencias respecto a una base embebida. Las reglas de negocio, como qué pedidos se pueden cancelar, se prueban aparte mediante pruebas unitarias del dominio, sin base de datos.