[JAVA] JPA Repository 메서드 쿼리 작성법 – 실무 중심 가이드

Spring Data JPA를 사용하면 반복적인 CRUD SQL을 직접 작성하지 않아도 됩니다. 핵심은 바로 Repository 인터페이스에서 메서드 이름만으로 쿼리를 자동 생성해주는 기능입니다. JpaRepository를 확장하여 쿼리를 작성하는 방법과 실무에서 자주 쓰는 메서드 예시, 그리고 주의할 점까지 정리합니다.

 

1. 기본 구조

@Repository
public interface UserRepository extends JpaRepository<User, Long> {
    // 메서드 이름 기반 쿼리
    Optional<User> findByEmail(String email);
    
    List<User> findAllByAgeGreaterThan(int age);
}

Spring Data JPA는 findBy, existsBy, countBy, deleteBy 등의 키워드를 분석하여 자동으로 SQL을 생성합니다.

 

2. 메서드 이름 규칙

• findBy[컬럼명]: 단일 조건 조회
• findAllBy: 조건에 맞는 전체 리스트 반환
• countBy: 조건에 해당하는 row 개수
• existsBy: 존재 여부 확인 (true/false)
• deleteBy: 조건에 따른 삭제

예시:

List<User> findByStatusAndAgeLessThan(String status, int age);

boolean existsByUsername(String username);

int countByRole(String role);

void deleteByInactiveTrue();

 

3. 정렬(Sorting)과 페이징(Paging)

Spring Data JPA는 Sort와 Pageable 객체를 인자로 받아 정렬과 페이징을 간단히 처리할 수 있습니다.

List<User> findByRole(String role, Sort sort);

Page<User> findByAgeGreaterThan(int age, Pageable pageable);

 

4. 복잡한 조건 – @Query 활용

메서드 이름만으로 표현이 어려운 복잡한 조건은 @Query 어노테이션으로 JPQL 또는 Native SQL을 작성할 수 있습니다.

@Query("SELECT u FROM User u WHERE u.email LIKE %:keyword% AND u.active = true")
List<User> searchActiveUsers(@Param("keyword") String keyword);

복잡한 조건이 많아지면 Querydsl, Specification, NativeQuery 도입을 고려해볼 수 있습니다.

 

5. 주의할 점

• 컬럼명은 엔티티 필드 기준이어야 합니다. DB 컬럼명이 아닙니다.
• 조합된 메서드는 길어질수록 가독성이 떨어질 수 있습니다. @Query나 Querydsl로 리팩터링이 필요할 수 있습니다.
• 조회 결과가 Optional, List, Stream, Page, Slice 등 다양하므로 상황에 맞게 선택하세요.
• 중복된 메서드 이름은 빌드 에러를 발생시킵니다.

 

6. 실무에서 자주 사용하는 메서드 예시

// 회원 활성 여부 확인
boolean existsByEmailAndActiveTrue(String email);

// 30일 이상 로그인하지 않은 사용자 찾기
List<User> findAllByLastLoginBefore(LocalDateTime deadline);

// 특정 도메인 이메일 사용자 리스트
List<User> findByEmailEndingWith(String domain);

// 이름 포함 검색 (Like 쿼리)
List<User> findByNameContaining(String keyword);

// 상태값 in 조건
List<User> findByStatusIn(List<String> statuses);

 

7. 마무리

Spring Data JPA의 Repository 메서드 쿼리 기능은 생산성을 극대화해주는 강력한 도구입니다. 단, 복잡한 비즈니스 로직에서는 메서드명이 지나치게 길어지거나 유지보수가 어려워질 수 있으니, 적절한 시점에 @Query 또는 Querydsl 도입을 고려하시는 것이 좋습니다.