Common Pitfalls & Debugging Guide

// ❌ WRONG — transaction never starts
@Service
public class OrderService {
    public void processOrder(Order order) {
        validate(order);
        saveOrder(order);  // this.saveOrder() — bypasses proxy!
    }

    @Transactional
    public void saveOrder(Order order) {
        orderRepository.save(order);
        paymentRepository.charge(order);  // NOT in a transaction!
    }
}

// ✅ CORRECT — extract to separate bean
@Service
@RequiredArgsConstructor
public class OrderService {
    private final OrderPersistenceService persistenceService;

    public void processOrder(Order order) {
        validate(order);
        persistenceService.saveOrder(order);  // goes through proxy
    }
}

@Service
public class OrderPersistenceService {
    @Transactional
    public void saveOrder(Order order) {
        orderRepository.save(order);
        paymentRepository.charge(order);  // IN a transaction ✅
    }
}

// ❌ WRONG — transaction commits despite exception!
@Transactional
public void transferMoney(Long from, Long to, BigDecimal amount) throws InsufficientFundsException {
    accountRepository.debit(from, amount);
    if (getBalance(from).compareTo(BigDecimal.ZERO) < 0) {
        throw new InsufficientFundsException();  // Checked exception — NO rollback!
    }
    accountRepository.credit(to, amount);
}

// ✅ CORRECT — explicitly declare rollback for checked exceptions
@Transactional(rollbackFor = InsufficientFundsException.class)
public void transferMoney(Long from, Long to, BigDecimal amount) throws InsufficientFundsException {
    // now rolls back on InsufficientFundsException
}

// OR better — use unchecked exceptions for business logic errors
@Transactional
public void transferMoney(Long from, Long to, BigDecimal amount) {
    // ...
    throw new InsufficientFundsRuntimeException();  // RuntimeException — auto rollback ✅
}

// Entity
@Entity
public class Author {
    @OneToMany(mappedBy = "author", fetch = FetchType.LAZY)
    private List<Book> books;
}

// Service — looks innocent
public List<AuthorDTO> getAllAuthors() {
    List<Author> authors = authorRepository.findAll();  // 1 query
    return authors.stream()
        .map(a -> new AuthorDTO(a.getName(), a.getBooks().size()))  // N queries!
        .toList();
}

// Solution 1: JOIN FETCH in JPQL
@Query("SELECT a FROM Author a JOIN FETCH a.books")
List<Author> findAllWithBooks();

// Solution 2: @EntityGraph
@EntityGraph(attributePaths = {"books"})
List<Author> findAll();

// Solution 3: @BatchSize on the collection (fetches in groups)
@OneToMany(mappedBy = "author")
@BatchSize(size = 50)  // fetches books for 50 authors at once
private List<Book> books;

@Service
public class OrderService {
    @Autowired private PaymentService paymentService;  // needs PaymentService
}

@Service
public class PaymentService {
    @Autowired private OrderService orderService;  // needs OrderService — circular!
}

// ✅ BEST: Redesign — extract shared logic
@Service
public class OrderService {
    private final OrderPaymentCoordinator coordinator;
}

@Service
public class PaymentService {
    private final OrderPaymentCoordinator coordinator;
}

@Service
public class OrderPaymentCoordinator {
    // shared logic that both needed from each other
}

// ⚠️ OK: Use @Lazy to break the cycle
@Service
public class OrderService {
    @Autowired @Lazy private PaymentService paymentService;
}

// ⚠️ OK: Use ObjectProvider for lazy resolution
@Service
public class OrderService {
    private final ObjectProvider<PaymentService> paymentProvider;

    public void process() {
        paymentProvider.getObject().charge(...);  // resolved at call time
    }
}

// ❌ WRONG — prototype acts like singleton
@Service  // singleton by default
public class ReportService {
    @Autowired
    private ReportGenerator generator;  // injected ONCE, same instance always used

    public Report generate() {
        return generator.build();  // stale state from previous call!
    }
}

@Component
@Scope("prototype")
public class ReportGenerator {
    private List<String> data = new ArrayList<>();  // accumulates across calls!
}

// ✅ CORRECT — use ObjectProvider
@Service
public class ReportService {
    private final ObjectProvider<ReportGenerator> generatorProvider;

    public Report generate() {
        ReportGenerator generator = generatorProvider.getObject();  // new instance!
        return generator.build();
    }
}

// ❌ DANGEROUS — ThreadLocal leaks in Tomcat thread pool
public class RequestContext {
    private static final ThreadLocal<UserInfo> context = new ThreadLocal<>();

    public static void set(UserInfo user) { context.set(user); }
    public static UserInfo get() { return context.get(); }
    // Missing: public static void clear() { context.remove(); }
}

// ✅ CORRECT — always clear in a filter/interceptor
@Component
public class RequestContextFilter extends OncePerRequestFilter {
    @Override
    protected void doFilterInternal(HttpServletRequest req, HttpServletResponse res,
                                     FilterChain chain) throws ServletException, IOException {
        try {
            RequestContext.set(extractUser(req));
            chain.doFilter(req, res);
        } finally {
            RequestContext.clear();  // ALWAYS in finally block
        }
    }
}

// ❌ Accessing lazy collection outside the Hibernate session
@GetMapping("/authors/{id}")
public AuthorDTO getAuthor(@PathVariable Long id) {
    Author author = authorService.findById(id);  // session closes here
    return new AuthorDTO(
        author.getName(),
        author.getBooks().size()  // 💥 LazyInitializationException!
    );
}

// ✅ Solution 1: Fetch eagerly in the query
@Query("SELECT a FROM Author a JOIN FETCH a.books WHERE a.id = :id")
Optional<Author> findByIdWithBooks(@Param("id") Long id);

// ✅ Solution 2: Use DTO projection in the query
@Query("SELECT new com.example.AuthorDTO(a.name, SIZE(a.books)) FROM Author a WHERE a.id = :id")
Optional<AuthorDTO> findAuthorDTOById(@Param("id") Long id);

// ❌ Problem: Spring doesn't know which DataSource to auto-configure
@Configuration
public class DatabaseConfig {
    @Bean
    public DataSource primaryDataSource() { ... }

    @Bean
    public DataSource reportingDataSource() { ... }
    // Startup error: expected single matching bean but found 2
}

// ✅ Solution: Mark one as @Primary
@Configuration
public class DatabaseConfig {
    @Bean
    @Primary  // auto-configuration will use this one
    public DataSource primaryDataSource() { ... }

    @Bean
    @Qualifier("reporting")
    public DataSource reportingDataSource() { ... }
}