spring-boot-patterns

Use thin REST controllers that delegate to one service per handler, keep entities inside the persistence boundary, and split services into aggregate services (one per aggregate root) and application services (cross-aggregate use cases). Map between layers with dedicated REST and domain mappers.

Declare every caller-visible failure once in a single error catalog enum carrying status, type URI, title, and detail. Use one RestControllerAdvice extending ResponseEntityExceptionHandler, with the type URI as the only machine-readable identifier and correlationId as the sole extension member.

Yes, the architecture is identical on both generations: controllers, services, domain models, transaction boundaries, and the error contract do not change. Only surrounding details differ, such as the JSON library, mapper bean, and retry engine, plus Spring Boot 4's automatic Jackson module registration.

The transaction boundary is the highest service the use case enters. An application service opens the transaction for multi-aggregate use cases, while an aggregate service opens its own when the operation stays within one aggregate. Both levels use @Transactional with default propagation.

This happens when the exception advice only handles project exception types. Exhausted lock retries propagate Spring framework exceptions like OptimisticLockingFailureException, so the advice needs explicit handlers for those parent types to map them to 409 or 503 with Retry-After.

Single-phase is the default: the claim commits with the effect in one transaction. Two-phase is required only when the use case makes a synchronous external call whose result the caller receives, and it mandates a lease deadline so a crash does not block the key forever.