Spring Data JPA Repository Best Practices

Follow these practices for efficient and maintainable data access.

Repository Interface

@Repository
public interface CustomerRepository extends JpaRepository<Customer, Long> {
    
    // Query derivation - Spring generates the query
    Optional<Customer> findByEmail(String email);
    
    List<Customer> findByGuestFalse();
    
    List<Customer> findByNameContainingIgnoreCase(String name);
    
    boolean existsByEmail(String email);
    
    // Pagination support
    Page<Customer> findByGuestFalse(Pageable pageable);
}

Custom Queries with @Query

@Repository
public interface AppointmentRepository extends JpaRepository<Appointment, Long> {
    
    // JPQL query
    @Query("SELECT a FROM Appointment a WHERE a.customer.id = :customerId AND a.status = :status")
    List<Appointment> findByCustomerAndStatus(
        @Param("customerId") Long customerId, 
        @Param("status") String status
    );
    
    // Native query (use sparingly)
    @Query(value = "SELECT * FROM appointments WHERE appointment_time BETWEEN ?1 AND ?2", 
           nativeQuery = true)
    List<Appointment> findByDateRange(LocalDateTime start, LocalDateTime end);
    
    // Join fetch to avoid N+1
    @Query("SELECT a FROM Appointment a " +
           "LEFT JOIN FETCH a.customer " +
           "LEFT JOIN FETCH a.employee " +
           "WHERE a.id = :id")
    Optional<Appointment> findByIdWithDetails(@Param("id") Long id);
    
    // Aggregate queries
    @Query("SELECT COUNT(a) FROM Appointment a WHERE a.employee.id = :employeeId AND a.status = 'COMPLETED'")
    long countCompletedByEmployee(@Param("employeeId") Long employeeId);
}

Modifying Queries

@Repository
public interface AppointmentRepository extends JpaRepository<Appointment, Long> {
    
    @Modifying
    @Query("UPDATE Appointment a SET a.status = :status WHERE a.id = :id")
    int updateStatus(@Param("id") Long id, @Param("status") String status);
    
    @Modifying
    @Query("DELETE FROM Appointment a WHERE a.status = 'CANCELLED' AND a.appointmentTime < :before")
    int deleteCancelledBefore(@Param("before") LocalDateTime before);
}

Projections

// Interface projection - only selected fields
public interface CustomerSummary {
    Long getId();
    String getName();
    String getEmail();
}

// DTO projection - full control
public record CustomerDTO(Long id, String name, String email) {}

@Repository
public interface CustomerRepository extends JpaRepository<Customer, Long> {
    
    // Interface projection
    List<CustomerSummary> findAllProjectedBy();
    
    // DTO projection with JPQL
    @Query("SELECT new com.salonhub.api.customer.dto.CustomerDTO(c.id, c.name, c.email) FROM Customer c")
    List<CustomerDTO> findAllAsDTO();
    
    // Dynamic projection
    <T> List<T> findByGuestFalse(Class<T> type);
}

Entity Graphs

@Entity
@NamedEntityGraph(
    name = "Appointment.withDetails",
    attributeNodes = {
        @NamedAttributeNode("customer"),
        @NamedAttributeNode("employee"),
        @NamedAttributeNode("serviceType")
    }
)
public class Appointment {
    // fields
}

@Repository
public interface AppointmentRepository extends JpaRepository<Appointment, Long> {
    
    @EntityGraph("Appointment.withDetails")
    Optional<Appointment> findById(Long id);
    
    @EntityGraph(attributePaths = {"customer", "employee"})
    List<Appointment> findByStatus(String status);
}

Specifications for Dynamic Queries

public class AppointmentSpecifications {
    
    public static Specification<Appointment> hasStatus(String status) {
        return (root, query, cb) -> 
            status == null ? null : cb.equal(root.get("status"), status);
    }
    
    public static Specification<Appointment> hasCustomer(Long customerId) {
        return (root, query, cb) -> 
            customerId == null ? null : cb.equal(root.get("customer").get("id"), customerId);
    }
    
    public static Specification<Appointment> hasDateBetween(LocalDateTime start, LocalDateTime end) {
        return (root, query, cb) -> {
            if (start == null && end == null) return null;
            if (start == null) return cb.lessThanOrEqualTo(root.get("appointmentTime"), end);
            if (end == null) return cb.greaterThanOrEqualTo(root.get("appointmentTime"), start);
            return cb.between(root.get("appointmentTime"), start, end);
        };
    }
}

// Usage
@Service
public class AppointmentService {
    
    public List<Appointment> search(String status, Long customerId, LocalDateTime start, LocalDateTime end) {
        Specification<Appointment> spec = Specification
            .where(AppointmentSpecifications.hasStatus(status))
            .and(AppointmentSpecifications.hasCustomer(customerId))
            .and(AppointmentSpecifications.hasDateBetween(start, end));
        
        return appointmentRepository.findAll(spec);
    }
}

Transaction Management

@Service
@Transactional(readOnly = true)  // Default read-only
public class AppointmentService {
    
    private final AppointmentRepository appointmentRepository;
    private final QueueService queueService;
    
    // Read operation - uses class-level readOnly=true
    public AppointmentResponseDTO findById(Long id) {
        return appointmentRepository.findById(id)
            .map(appointmentMapper::toResponseDTO)
            .orElseThrow(() -> new ResourceNotFoundException("Appointment not found"));
    }
    
    // Write operation - override to allow writes
    @Transactional
    public AppointmentResponseDTO create(AppointmentRequestDTO request) {
        Appointment appointment = appointmentMapper.toEntity(request);
        appointment = appointmentRepository.save(appointment);
        return appointmentMapper.toResponseDTO(appointment);
    }
    
    // Complex transaction spanning multiple services
    @Transactional(rollbackFor = Exception.class)
    public void completeAppointment(Long id) {
        Appointment appointment = appointmentRepository.findById(id)
            .orElseThrow(() -> new ResourceNotFoundException("Appointment not found"));
        
        appointment.setStatus("COMPLETED");
        appointmentRepository.save(appointment);
        
        // If this fails, entire transaction rolls back
        queueService.removeFromQueue(appointment.getCustomer().getId());
    }
}

Optimistic Locking

@Entity
public class Appointment {
    @Id
    private Long id;
    
    @Version
    private Long version;
    
    // Other fields
}

// Handling optimistic lock exception
@Service
public class AppointmentService {
    
    @Transactional
    @Retryable(value = OptimisticLockException.class, maxAttempts = 3)
    public void updateAppointment(Long id, AppointmentUpdateDTO dto) {
        Appointment appointment = appointmentRepository.findById(id)
            .orElseThrow(() -> new ResourceNotFoundException("Appointment not found"));
        
        // Update fields
        appointmentMapper.updateEntity(dto, appointment);
        
        // Save will throw OptimisticLockException if version mismatch
        appointmentRepository.save(appointment);
    }
}

Auditing

@Configuration
@EnableJpaAuditing
public class JpaConfig {
    
    @Bean
    public AuditorAware<String> auditorProvider() {
        return () -> Optional.ofNullable(SecurityContextHolder.getContext())
            .map(SecurityContext::getAuthentication)
            .map(Authentication::getName);
    }
}

@MappedSuperclass
@EntityListeners(AuditingEntityListener.class)
public abstract class BaseEntity {
    
    @CreatedDate
    @Column(updatable = false)
    private LocalDateTime createdAt;
    
    @LastModifiedDate
    private LocalDateTime updatedAt;
    
    @CreatedBy
    @Column(updatable = false)
    private String createdBy;
    
    @LastModifiedBy
    private String updatedBy;
}

@Entity
public class Appointment extends BaseEntity {
    // Entity-specific fields
}

Query Hints for Performance

@Repository
public interface AppointmentRepository extends JpaRepository<Appointment, Long> {
    
    @QueryHints(value = {
        @QueryHint(name = "org.hibernate.fetchSize", value = "50"),
        @QueryHint(name = "org.hibernate.readOnly", value = "true"),
        @QueryHint(name = "org.hibernate.cacheable", value = "true")
    })
    @Query("SELECT a FROM Appointment a WHERE a.status = :status")
    List<Appointment> findByStatusOptimized(@Param("status") String status);
}

Repository Checklist

• [ ] Extend JpaRepository for full CRUD support
• [ ] Use query derivation for simple queries
• [ ] Use @Query for complex JPQL queries
• [ ] Add JOIN FETCH or @EntityGraph to prevent N+1
• [ ] Use projections when full entities aren't needed
• [ ] Implement Specification for dynamic queries
• [ ] Configure transactions appropriately
• [ ] Add @Version for optimistic locking where needed
• [ ] Enable auditing for tracking changes