[SPRING] Spring Data JPA로 동적 쿼리와 페이징 최적화하기: Specification과 @EntityGraph 활용

1. 🫐 도입

프로젝트를 진행하면서 동적으로 데이터를 조회해야 할 상황이 많았다. category, memberId, 정렬 기준 등 조회 조건이 자주 바뀌었고, 이 조건들을 조합하여 유연하게 쿼리를 생성할 수 있는 방식이 필요했다. 특히, 조건이 빈번하게 변경되거나 상황에 따라 추가되는 경우, 코드가 복잡해지고 유지보수도 어려워질 가능성이 컸다.

이때 Spring Data JPA의 Specification 기능을 알게 되었고, 이를 통해 다양한 필터 조건을 유연하게 추가하고 조합하여 필요한 데이터를 효율적으로 조회할 수 있음을 알게되었다. Specification을 활용하면 코드의 복잡성을 줄이고, 조건이 변해도 쿼리를 쉽게 관리할 수 있기 때문이다. 

 

- 동적 조건 추가: Specification을 사용하면 여러 필터 조건을 상황에 따라 동적으로 조합할 수 있다. 예를 들어, memberId, category, 정렬 조건 등을 필요한 대로 추가할 수 있다.

- JPA와의 통합: JpaSpecificationExecutor와 함께 사용하여, Specification을 통해 만들어진 동적 쿼리와 페이징(page, size)을 자연스럽게 결합할 수 있다.

 

2. 🫐 사용 과정

public class DiarySpecification {

    public static Specification<DiaryEntity> withCategoryAndIsPublic(Category category) {
        return (Root<DiaryEntity> root, CriteriaQuery<?> query, CriteriaBuilder cb) ->
                category != null
                        ? cb.and(cb.isTrue(root.get("isPublic")), cb.equal(root.get("category"), category))
                        : cb.isTrue(root.get("isPublic"));
    }

    public static Specification<DiaryEntity> orderByCreatedAt() {
        return (Root<DiaryEntity> root, CriteriaQuery<?> query, CriteriaBuilder cb) -> {
            query.orderBy(cb.desc(root.get("createdAt")));
            return query.getRestriction();
        };
    }

    public static Specification<DiaryEntity> orderByContentLength() {
        return (Root<DiaryEntity> root, CriteriaQuery<?> query, CriteriaBuilder cb) -> {
            query.orderBy(cb.desc(cb.length(root.get("content"))));
            return query.getRestriction();
        };
    }
}

🍒 Specification과 Query 같이 사용 불가

처음엔 @Query와 Specification을 함께 사용하여, @Query를 사용하여 특정 필터(예: memberId와 기본 조건)를 처리하고, 나머지 조건은 Specification을 통해 동적으로 추가하는 방식을 선택했다. 

@Query("SELECT d FROM DiaryEntity d JOIN FETCH d.soptMember m " +
            "WHERE m.id = :memberId ")
    Page<DiaryEntity> findByMemberId(
            Long memberId, Specification<DiaryEntity> specification, Pageable pageable
    );

 

그랬더니

Could not create query for public abstract org.springframework.data.domain.Page org.sopt.diary.domain.repository.DiaryRepository.findByMemberId(java.lang.Long,org.springframework.data.jpa.domain.Specification,org.springframework.data.domain.Pageable);
Reason: Using named parameters for method public abstract org.springframework.data.domain.Page org.sopt.diary.domain.repository.DiaryRepository.findByMemberId(java.lang.Long,org.springframework.data.jpa.domain.Specification,org.springframework.data.domain.Pageable) but parameter 'Optional[specification]' not found in annotated query 'SELECT d FROM DiaryEntity d JOIN FETCH d.soptMember m WHERE m.id = :memberId '

 

이런 에러가 발생했는데, 이는 Spring Data JPA는 @Query와 Specification을 동시에 사용하는 것을 지원하지 않기 때문에, @Query 방식으로 Specification을 처리할 수 없다고 한다. Specification과 @Query는 별도로 작동하므로, @Query 메서드에 Specification 파라미터를 추가하면 에러가 발생한다.

 

그래서 @Query를 제거하고 그냥 JPA 메서드 이름 기반 쿼리로 처리하도록

Page<DiaryEntity> findBySoptMemberId(
            Long memberId, Specification<DiaryEntity> specification, Pageable pageable
    );

로 바꿔주었는데,

 

ERROR 42274 --- [nio-8080-exec-1] o.s.d.c.advice.GlobalExceptionHandler    : Unhandled exception occurred: At least 2 parameter(s) provided but only 1 parameter(s) present in query

 

또 이런 에러가 발생했다. 이 에러는 쿼리에 전달된 파라미터 수가 실제 필요한 파라미터 수와 일치하지 않다는 메세지였는데, 이는 findBySoptMemberId 메서드를 사용할 때 Specification을 함께 전달할 수 없다는 것이었다. Specification을 별도로 사용하려면 findAll 메서드와 결합해야 한다고 한다.

 

Specification과 함께 사용 가능한 메서드

JpaSpecificationExecutor 인터페이스는 기본적으로 다음 메서드들에서만 Specification을 사용할 수 있도록 제공한다:

- findAll(Specification<T> spec): Specification을 사용해 모든 조건을 필터링하고 조회

- findAll(Specification<T> spec, Pageable pageable): Specification과 페이징을 함께 사용해 조회

- findOne(Specification<T> spec): 단일 결과를 조회할 때 사용

- count(Specification<T> spec): 조건에 맞는 엔티티의 개수를 조회

- exists(Specification<T> spec): 조건에 맞는 엔티티가 존재하는지 확인

 

따라서 Specification에서 memberId와 추가 조건을 함께 처리하고, findAll 메서드로 조회하는 방식을 최종적으로 선택하게 되었다.

 

//service
Page<DiaryEntity> diaryEntities = diaryRepository.findAll(specification, pageable);

// repository
Page<DiaryEntity> findAll(Specification<DiaryEntity> specification, Pageable pageable);

 

🍒 Specification에서 JOIN FETCH가 안됨

N+1 문제를 해결하기 위해 soptMember JOIN FETCH 설정을 Specification에 해주었는데,

public static Specification<DiaryEntity> withCategoryAndIsPublic(Category category) {
        return (Root<DiaryEntity> root, CriteriaQuery<?>query, CriteriaBuilder cb) -> {
            root.fetch("soptMember"); // JOIN FETCH 설정
            query.distinct(true); // 중복 제거
            return cb.and(
                    cb.equal(root.get("category"), category),
                    cb.isTrue(root.get("isPublic")) // isPublic이 true인 경우만
            );
        };
    }

Unhandled exception occurred: org.hibernate.query.SemanticException: Query specified join fetching, but the owner of the fetched association was not present in the select list [SqmSingularJoin(org.sopt.diary.domain.DiaryEntity(12).soptMember(13) : soptMember)]

 

위와 같은 문제가 발생했다.

@ManyToOne 관계라 페이징과 JOIN FETCH 조합에서 문제가 없을 줄 알았는데, 찾아보니 이 에러는 Specification에서 JOIN FETCH를 사용하면서 페이징을 하려고 할 때 발생하는 Hibernate의 제약 사항 때문에 발생한다고 한다.

JOIN FETCH와 페이징을 함께 사용하면 Hibernate는 기본적으로 페치 조인을 사용한 엔티티를 select 대상에 포함시키지 못해 오류가 발생할 수 있다.

@ManyToOne 관계라도 페이징과 Criteria API 기반의 Specification의 JOIN FETCH 조합에서 Hibernate의 제한이 발생할 수 있다고 한다.

따라서 @EntityGraph를 활용하여 이 문제를 해결해주었다.

 

🍒 @EntityGraph 활용

일기 목록을 조회할 때,

    // 일기 목록 조회
    @Transactional(readOnly = true)
    public DiaryListResponse getDiaryList(
            final Category category,
            final String sortBy,
            Pageable pageable
    ) {
        Specification<DiaryEntity> specification = createSpecificationWithSorting(category, null, sortBy);
        pageable = PageRequest.of(pageable.getPageNumber(), pageable.getPageSize());

        Page<DiaryEntity> diaryEntities = diaryRepository.findAll(specification, pageable);
        return DiaryListResponse.from(diaryEntities);
    }

이런식으로 Specification 객체를 통해 동적 쿼리를 구성하고, diaryRepository에서 findAll 메서드를 통해 조건과 페이징에 맞는 일기 목록을 조회하는데, 이 때 findAll로 일기 목록을 가져오는 메서드에

    @Override
    @EntityGraph(attributePaths = {"soptMember"})
    Page<DiaryEntity> findAll(Specification<DiaryEntity> specification, Pageable pageable);

 

이렇게 @EntityGraph(attributePaths = {"soptMember"})를 적용하여 soptMember를 즉시 로딩(fetch join)하도록 설정하였다.

 

3. 🫐 최종 코드

//Service

    // 내 일기 목록 조회
    @Transactional(readOnly = true)
    public MyDiaryListResponse getMyDiaryList(
            final Long memberId,
            final Category category,
            final String sortBy,
            Pageable pageable
    ) {
        Specification<DiaryEntity> specification = createSpecificationWithSorting(category, memberId, sortBy);
        pageable = PageRequest.of(pageable.getPageNumber(), pageable.getPageSize());

        memberService.findById(memberId);
        Page<DiaryEntity> diaryEntities = diaryRepository.findAll(specification, pageable);
        return MyDiaryListResponse.from(diaryEntities);
    }
    
    private Specification<DiaryEntity> createSpecificationWithSorting(Category category, Long memberId, String sortBy) {
        Specification<DiaryEntity> specification;

        if (memberId != null) {
            specification = DiarySpecification.withMemberIdAndCategory(memberId, category);
        } else {
            specification = DiarySpecification.withCategoryAndIsPublic(category);
        }

        // 정렬 조건 추가
        if (CREATED_AT.equals(sortBy)) {
            specification = specification.and(DiarySpecification.orderByCreatedAt());
        } else if (CONTENT_LENGTH.equals(sortBy)) {
            specification = specification.and(DiarySpecification.orderByContentLength());
        }

        return specification;
    }

 

// Specification

public class DiarySpecification {

    public static Specification<DiaryEntity> withCategoryAndIsPublic(Category category) {
        return (Root<DiaryEntity> root, CriteriaQuery<?> query, CriteriaBuilder cb) ->
                category != null
                        ? cb.and(cb.isTrue(root.get("isPublic")), cb.equal(root.get("category"), category))
                        : cb.isTrue(root.get("isPublic"));
    }

    public static Specification<DiaryEntity> withMemberIdAndCategory(Long memberId, Category category) {
        return (root, query, cb) -> {
            Join<Object, Object> memberJoin = root.join("soptMember");  // soptMember 필드 조인
            return category != null
                    ? cb.and(cb.equal(memberJoin.get("id"), memberId), cb.equal(root.get("category"), category))
                    : cb.equal(memberJoin.get("id"), memberId);
        };
    }

    public static Specification<DiaryEntity> orderByCreatedAt() {
        return (Root<DiaryEntity> root, CriteriaQuery<?> query, CriteriaBuilder cb) -> {
            query.orderBy(cb.desc(root.get("createdAt")));
            return query.getRestriction();
        };
    }

    public static Specification<DiaryEntity> orderByContentLength() {
        return (Root<DiaryEntity> root, CriteriaQuery<?> query, CriteriaBuilder cb) -> {
            query.orderBy(cb.desc(cb.length(root.get("content"))));
            return query.getRestriction();
        };
    }
}

 

// repository

public interface DiaryRepository extends JpaRepository<DiaryEntity, Long>, JpaSpecificationExecutor<DiaryEntity> {

    @Override
    @EntityGraph(attributePaths = {"soptMember"})
    Page<DiaryEntity> findAll(Specification<DiaryEntity> specification, Pageable pageable);

}

 

 

위와 같은 방식으로 구현하면, 다양한 필터 조건을 동적으로 추가하면서도 성능을 최적화할 수 있다.

Specification과 @EntityGraph를 조합하면 아래와 같은 장점을 얻을 수 있다.

• 유연한 조건 추가: Specification을 통해 다양한 필터 조건을 동적으로 조합하여 적용할 수 있다.
• N+1 문제 해결: @EntityGraph로 페이징과 함께 JOIN FETCH 문제를 해결하고, 필요한 연관 데이터를 효율적으로 가져올 수 있다.

다음엔 QueryDSL을 이용하여 동적 쿼리를 구현해보아야겠다!