🔎 QueryDSL – 동적 쿼리 및 정렬을 위한 Querydsl4RepositorySupport 구현

이 글에서는 동적으로 조건과 정렬을 반영하는 동적 쿼리와 동적 정렬을 위한 Querydsl4RepositorySupport 클래스 구현 및 QueryDSL 사용 방법에 대해 다룹니다.
구현 방법은 🧭 환경 설정 부터 나와 있습니다.

왜 QueryDSL을 사용하는가

QueryDSL은 무엇인가

QueryDSL은 정적 타입을 이용해 SQL과 같은 쿼리를 생성할 수 있도록 지원하는 오픈소스 프레임워크이다. 쿼리를 문자열로 작성하는 것이 아닌, QueryDSL이 제공하는 Fluent API를 이용해 코드 형식으로 쿼리를 작성하고 적용할 수 있도록 한다. 쉽게 말하면 코드로 쿼리를 조립할 수 있게 만들어서 동적 쿼리를 지원한다는 말이다.

JPQL만으로는 안된다고요?

현재 개발 중인 프로젝트의 요구사항 중에는 이미지의 정보에 대한 다중 조건 검색 지원에 관해 명시되어있다. 다중 조건 검색을 위해서는 동적 쿼리를 생성해야하는데, 다중 조건 검색 구현 전에는 JPQL을 사용했었다. 전체 리스트에서 정해진 조건을 만족하는 결과만 검색하면 됐기에 정적 쿼리인 JPQL만 사용해도 구현할 수 있었기 때문이다. 이전에 QueryDSL을 사용해본 적이 없었기에 괜히 어렵게 느껴져 JPQL에서 동적 쿼리를 사용할 수 있는 방법이 없을까 고민하고 찾아봤다. JPQL에서 동적 쿼리를 구현하기 위해서는 조건에 따라 쿼리를 수동으로 String으로 만들어 파라미터로 넣어주는 귀찮은 과정을 거쳐야 한다. 결국 JPQL로 동적 쿼리를 구현하는 것이 하드 코딩과 다를 바가 없다고 판단해 동적 쿼리를 지원하는 QueryDSL을 사용하기로 결정했다.

어.....근데 왜 정렬이 안되지?

해당 프로젝트에서는 무한 스크롤 구현을 위해 pagination을 지원한다. 이때 페이징을 위해 프론트로부터 받아오는 조건들(page, size, sort, keyword) 중 정렬 조건이 적용되지 않는 것을 확인했다. 커스텀하지 않은 QueryDSL을 사용했을 때, pagination 자체는 적용이 되었지만 정렬 조건은 적용되지 않았다. 찾아보니 동적 정렬을 위해 OrderSpecifier를 직접 설정해줘야 했다. 동적 정렬 적용과 QueryDSL을 더 편하게 사용하기 위해 Querydsl4RepositorySupport를 커스텀해 사용했다.

🧭 환경 설정

개발 환경

• Spring Boot v3.3.1
• Gradle build
• MySQL

의존성 설정

build.gradle

QueryDSL을 사용하기 위한 의존성과 source set을 설정해준다. source set에서는 java compile 후 생기는 Q domain class들의 생성 위치를 설정해줄 수 있다.
아래 설정에서는 QueryDSL 5.1.0을 사용하고 있다. QueryDSL은 4.x.x가 가장 많이 사용되지만, 5.x.x 버전이 release 되면서 fetchResults()와 fetchCount()가 deprecated 되었기에 5.0.0 이후 버전을 사용하는 게 향후 유지보수성에 좋을 것이라 판단해 QueryDSL 5.1.0를 사용했다.

...
dependencies {
    ...
    // querydsl 의존성 추가
    implementation 'com.querydsl:querydsl-jpa:5.1.0:jakarta'
    annotationProcessor "com.querydsl:querydsl-apt:${dependencyManagement.importedProperties['querydsl.version']}:jakarta"
    implementation 'com.querydsl:querydsl-core'
    annotationProcessor 'jakarta.persistence:jakarta.persistence-api'
    annotationProcessor 'jakarta.annotation:jakarta.annotation-api'
    ...
}
...
// source set 설정
sourceSets {
    main {
        java {
            // Q domain class들이 src/main/generated에 생성되도록 설정
            srcDirs = ['src/main/java', 'src/main/generated']
        }
    }
}
...

Q domain class 생성

의존성 설정이 제대로 되었는 지 확인하기 위해 Q domain class를 생성해 테스트한다. Q domain class는 기존에 만들어져있는 JPA repository들의 domain entity class를 바탕으로 생성된다. 그러니까 Q domain class를 만들기 위해서는 당연히 domain entity class를 만들어놔야 한다.
Q domain class를 생성하기 위해서는 프로젝트 내의 Gradle 메뉴에서 build/clean 실행 → other/compileJava 또는 build/build를 실행하면 된다. 실행 후 앞서 설정해둔 sourceSet 내부에 Q domain class들이 생성되면 제대로 설정된 것이다.

🚀 How to use

아래의 글은 이미 JPA Repository를 이용해 구현된 domain entity와 repository class가 있다는 가정 하에 작성되었습니다.

JPA Repository와 QueryDSL 연동

QueryDSL을 사용할 인터페이스 선언

여기에서는 다중 조건 검색만을 위한 SearchContentRepository 인터페이스를 선언해주었다.

package example.api.content.repository.search;

public interface SearchContentRepository {

    Page<ContentViewDto> searchByKeyword(Pageable pageable, String keyword,
      	List<Long> uploadDateRange, AccountEntity account);
}

JPA repository에 QueryDSL 인터페이스 상속 설정

기존에 사용하던 JPA repository(여기서는 ContentRepository)에 앞서 선언한 SearchContentRepository 인터페이스를 부모로 설정해준다.

package example.api.content.repository;

@Repository
public interface ContentRepository extends JpaRepository<ContentEntity, Long>, SearchContentRepository {

    ContentEntity findByContentId(String contentId);
    ContentEntity findByContentIdAndAccount(String contentId, AccountEntity account);
}

Querydsl4RepositorySupport 구현

동적 정렬 지원을 위해 pageable의 sort로 OrderSpecifier를 생성하는 getOrderSpecifier() 메서드를 추가하고, pagination을 지원하도록 applyPagination() 메서드를 추가해 커스터마이징했다.

package example.global.querydsl;

import com.querydsl.core.types.EntityPath;
import com.querydsl.core.types.Expression;
import com.querydsl.core.types.Order;
import com.querydsl.core.types.OrderSpecifier;
import com.querydsl.core.types.dsl.PathBuilder;
import com.querydsl.jpa.impl.JPAQuery;
import com.querydsl.jpa.impl.JPAQueryFactory;
import jakarta.persistence.EntityManager;
import java.util.ArrayList;
import java.util.List;
import java.util.function.Function;
import lombok.Getter;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.data.domain.Page;
import org.springframework.data.domain.Pageable;
import org.springframework.data.domain.Sort;
import org.springframework.data.jpa.repository.support.JpaEntityInformation;
import org.springframework.data.jpa.repository.support.JpaEntityInformationSupport;
import org.springframework.data.jpa.repository.support.Querydsl;
import org.springframework.data.querydsl.SimpleEntityPathResolver;
import org.springframework.data.support.PageableExecutionUtils;
import org.springframework.stereotype.Repository;

/**
 * Querydsl4 repository support
 */
@Repository
@Getter
public abstract class Querydsl4RepositorySupport {

    private final Class domainClass;
    private Querydsl querydsl;
    private EntityManager entityManager;
    private JPAQueryFactory queryFactory;

    public Querydsl4RepositorySupport(Class domainClass) {
        this.domainClass = domainClass;
    }

    /**
     * Set entity manager
     *
     * @param entityManager entity manager
     */
    @Autowired
    public void setEntityManager(EntityManager entityManager) {

        JpaEntityInformation entityInformation = JpaEntityInformationSupport.getEntityInformation(
            domainClass, entityManager);
        SimpleEntityPathResolver resolver = SimpleEntityPathResolver.INSTANCE;
        EntityPath path = resolver.createPath(entityInformation.getJavaType());

        this.entityManager = entityManager;
        this.querydsl = new Querydsl(entityManager,
            new PathBuilder<>(path.getType(), path.getMetadata()));
        this.queryFactory = new JPAQueryFactory(entityManager);
    }

    /**
     * Select query - 쿼리 생성을 위한 메소드
     *
     * @param expr 쿼리 대상
     * @param <T>  쿼리 결과 타입
     * @return JPAQuery
     */
    protected <T> JPAQuery<T> select(Expression<T> expr) {
        return getQueryFactory().select(expr);
    }

    /**
     * Select query - 쿼리 생성을 위한 메소드
     *
     * @param from 쿼리 대상
     * @param <T> 쿼리 결과 타입
     * @return JPAQuery
     */
    protected <T> JPAQuery<T> selectFrom(EntityPath<T> from) {
        return getQueryFactory().selectFrom(from);
    }

    /**
     * Apply pagination - 페이징 처리를 위한 메소드
     *
     * @param pageable     페이징 정보
     * @param contentQuery 콘텐츠 쿼리
     * @param countQuery   카운트 쿼리
     * @param <T>          페이징 결과 타입
     * @return 페이징 결과
     */
    protected <T> Page<T> applyPagination(Pageable pageable,
        Function<JPAQueryFactory, JPAQuery> contentQuery,
        Function<JPAQueryFactory, JPAQuery> countQuery,
        Class<?> sortTargetClass,
        String sortVariableName) {

        JPAQuery jpaContentQuery = contentQuery.apply(getQueryFactory());
        List<OrderSpecifier> orders = getOrderSpecifier(pageable.getSort(), sortTargetClass,
            sortVariableName);
        if (!orders.isEmpty()) {
            jpaContentQuery.orderBy(orders.toArray(new OrderSpecifier[0]));
        }

        List<T> content = getQuerydsl().applyPagination(pageable, jpaContentQuery).fetch();
//        JPAQuery countResult = countQuery.apply(getQueryFactory());
        Long totalCount = countQuery.apply(getQueryFactory()).fetchCount();

        return PageableExecutionUtils.getPage(content, pageable, () -> totalCount);
    }

    /**
     * Get order specifier - 동적 정렬을 위한 메소드
     *
     * @param sort             정렬 조건
     * @param sortTargetClass  정렬 대상 클래스
     * @param sortVariableName 정렬 대상 변수명
     * @return 정렬 조건
     */
    private List<OrderSpecifier> getOrderSpecifier(Sort sort, Class<?> sortTargetClass,
        String sortVariableName) {

        List<OrderSpecifier> orders = new ArrayList<>();

        // Sort
        sort.stream().forEach(order -> {
            Order direction = order.isAscending() ? Order.ASC : Order.DESC;
            String prop = order.getProperty();
            PathBuilder orderByExpression = new PathBuilder(sortTargetClass, sortVariableName);
            orders.add(new OrderSpecifier(direction, orderByExpression.get(prop)));
        });
        return orders;
    }
}

QueryDSL 인터페이스의 구현체 구현

앞서 만든 SearchContentRepository 인터페이스를 구현한 SearchStudyRepositoryImpl 클래스를 구현한다. 이때 Querydsl4RepositorySupport 추상 클래스를 상속해 위에서 구현한 메서드를 사용할 수 있도록 한다.
조건 추가 시 조건이 null인지 확인 후 builder에 추가해주는 방식으로 구현할 수 있다.

package example.api.content.repository.search;

import com.querydsl.core.BooleanBuilder;
import com.querydsl.core.types.Projections;
import com.querydsl.jpa.JPQLQuery;
import com.querydsl.jpa.impl.JPAQuery;
import com.querydsl.jpa.impl.JPAQueryFactory;
import java.util.List;
import example.api.account.domain.AccountEntity;
import kr.co.beamworks.cadaimbe.api.account.domain.QAccountEntity;
import kr.co.beamworks.cadaimbe.api.patient.domain.QPatientEntity;
import kr.co.beamworks.cadaimbe.api.study.domain.QStudyEntity;
import kr.co.beamworks.cadaimbe.api.study.domain.StudyEntity;
import kr.co.beamworks.cadaimbe.api.study.dto.response.StudyViewDto;
import kr.co.beamworks.cadaimbe.global.querydsl.Querydsl4RepositorySupport;
import kr.co.beamworks.cadaimbe.global.util.time.TimeConverter;
import org.springframework.data.domain.Page;
import org.springframework.data.domain.Pageable;
import org.springframework.data.jpa.repository.support.QuerydslRepositorySupport;
import org.springframework.stereotype.Repository;

@Repository
public class SearchStudyRepositoryImpl extends Querydsl4RepositorySupport implements SearchStudyRepository {

    /**
     * Creates a new {@link QuerydslRepositorySupport} instance for the given domain type.
     */
    public SearchStudyRepositoryImpl() {
        super(StudyEntity.class);
    }

    /**
     * Search study by keyword
     *
     * @param pageable pageable
     * @param keyword keyword
     * @param studyDateRange study date range(Unix time)
     * @param uploadDateRange upload date range(Unix time)
     * @param cadaiScoreRange cadai score range(0.0 ~ 100.0)
     * @param account account entity
     * @return study view dto page
     */
    @Override
    public Page<StudyViewDto> searchByKeyword(Pageable pageable, String keyword,
        List<Long> uploadDateRange, List<Double> cadaiScoreRange, AccountEntity account) {

        JPAQueryFactory queryFactory = new JPAQueryFactory(getEntityManager());
        QContentEntity studyEntity = QContentEntity.contentEntity;
        QAccountEntity accountEntity = QAccountEntity.accountEntity;

        BooleanBuilder builder = new BooleanBuilder();

        if (keyword != null && !keyword.isEmpty()) {
            builder.or(contentEntity.contentId.like("%" + keyword + "%"));
            builder.or(contentEntity.title.like("%" + keyword + "%"));
            builder.or(accountEntity.institution.like("%" + keyword + "%"));
            builder.or(contentEntity.description.like("%" + keyword + "%"));
        }

        // Add account condition if account is not null
        if (account != null) {
            builder.and(accountEntity.eq(account));
        }

        // Add range conditions
        if (uploadDateRange != null && uploadDateRange.size() == 2) {
            builder.and(contentEntity.uploadDate.between(TimeConverter.convertUnixTimeToLocalDateTime(uploadDateRange.get(0)),
                TimeConverter.convertUnixTimeToLocalDateTime(uploadDateRange.get(1))));
        }

        // 동적 쿼리 생성
        JPQLQuery<ContentViewDto> query = queryFactory
            .select(Projections.constructor(
                ContentViewDto.class,
                contentEntity.contentId,
                contentEntity.title,
                accountEntity.institution,
                contentEntity.description,
                contentEntity.uploadDate))
            .from(contentEntity)
            .join(contentEntity.account, accountEntity)
            .where(builder);

        // pagination 적용
        return applyPagination(pageable,
            factory -> (JPAQuery) query,
            factory -> (JPAQuery) query,
            ContentEntity.class,
            "contentEntity"
        );
    }
}

이제 뭘 해야 하는가

리팩토링이 필요하다......

프로젝트를 빠르게 끝내는 게 가장 큰 목표였기 때문에 JPQL과 QueryDSL을 함께 사용하는 방식으로 구현되고 있다. 하지만 QueryDSL을 사용하는 이상 굳이 JPQL을 사용할 이유가 없기에 QueryDSL만을 사용해 검색 기능을 구현할 수 있도록 리팩토링할 예정이다.

더 유연한 검색을 지원하자

예를 들어 이름을 검색할 때 제목이 'Hello world'인 게시글이 있다고 하자. 현재까지 구현된 검색 기능에서는 Hello w, Hel 등은 검색 시 해당 게시글이 나오지만 hello world를 검색했을 때는 나오지 않는다. 이처럼 lower case, 띄어쓰기가 생략된 검색어에 대해 더 유연하게 검색을 지원할 수 있도록 추가적인 리서치와 개발이 필요하다.

---

Reference : querydsl을 이용한 페이징/검색 기능 구현, [Querydsl]동적 sorting을 위한 OrderSpecifier 클래스 구현, QueryDSL 공식 홈페이지