queryDSL 알아보기

JPA, JPQL, 그리고 QueryDSL — 타입 안정성과 유지보수를 위한 진화

현대 자바 백엔드 개발에서 JPA는 객체와 데이터베이스 간의 매핑을 쉽게 해주는 강력한 도구입니다. 하지만, 단순한 CRUD를 넘어 복잡한 조회 쿼리를 작성하다 보면 JPA만으로는 부족한 순간들이 찾아옵니다. 이때 등장하는 것이 바로 JPQL, 그리고 QueryDSL입니다.

이번 글에서는 JPA → JPQL → QueryDSL로 이어지는 흐름 속에서 각각의 역할과 한계, 그리고 QueryDSL의 장점과 사용법까지 정리해 보겠습니다.

1. JPA란?

JPA(Java Persistence API)는 자바 객체와 관계형 데이터베이스를 매핑해주는 ORM 기술입니다. 엔티티 클래스만 잘 정의해두면, save(), findById(), delete() 같은 기본적인 CRUD는 거의 자동화됩니다.

예시:

// 엔티티 저장
em.persist(user); 

// ID로 엔티티 조회
User user = em.find(User.class, 1L);

하지만 이렇게 기본적인 CRUD만으로는 한계가 있습니다. 예를 들어 사용자 이름이나 나이를 조건으로 검색하거나, 여러 엔티티를 조인하여 조회하는 등 복잡한 조건을 다루기 시작하면 다른 접근 방식이 필요합니다.

2. JPQL이란?

JPA는 복잡한 조회를 위해 SQL과 유사한 JPQL(Java Persistence Query Language)을 제공합니다. JPQL은 SQL과 비슷하지만, 테이블이 아닌 엔티티 객체를 대상으로 쿼리를 작성한다는 점이 다릅니다.

예시:

String jpql = "SELECT u FROM User u WHERE u.name = :name"; 
List<User> result = em.createQuery(jpql, User.class)
    .setParameter("name", "루시")
    .getResultList();

JPQL의 한계

• 문자열 기반: 오타나 구조 변경 시 컴파일 타임에 오류를 발견할 수 없음
• 동적 쿼리 작성이 복잡함: 조건이 많아질수록 if문과 StringBuilder를 조합해야 하는 복잡성 증가
• IDE 지원 부족: 자동 완성, 리팩토링 지원이 제한적
• 리팩토링 안전성 부족: 엔티티나 필드명이 변경되어도 쿼리 문자열은 자동으로 업데이트되지 않음

이러한 문제를 해결하기 위해 등장한 것이 바로 QueryDSL입니다.

3. QueryDSL이란?

QueryDSL은 Java 코드로 쿼리를 작성할 수 있도록 도와주는 타입 안전한 DSL(Domain Specific Language)입니다. 컴파일 시점에 오류를 잡을 수 있고, 메소드 체이닝 방식으로 복잡한 동적 쿼리도 쉽게 작성할 수 있습니다.

예시:

QUser user = QUser.user;
List<User> users = queryFactory
    .selectFrom(user)
    .where(user.name.eq("루시"))
    .fetch();

QueryDSL의 장점

• 타입 안정성: 오타나 필드명 변경 시 컴파일 오류로 즉시 확인 가능
• 동적 쿼리 용이: BooleanBuilder 또는 BooleanExpression을 사용해 조건을 유연하게 조립 가능
• IDE 자동완성 지원: 필드와 메소드 자동완성으로 생산성 향상
• 가독성 높음: 메소드 체이닝 방식으로 복잡한 조건도 Java 코드처럼 읽히는 DSL 형태
• 리팩토링 안전성: 엔티티나 필드명이 변경되면 Q클래스도 재생성되어 안전하게 변경 사항 반영

QueryDSL의 단점

• 초기 설정이 복잡: Q클래스 생성을 위한 애노테이션 프로세서 설정 필요 (Gradle/Maven 플러그인)
• 학습 비용: 처음 접하는 개발자에게는 낯설 수 있음
• 빌드 시간 증가: Q클래스 생성 과정이 빌드 시간에 추가됨

4. 실제 사용 예시

조건 검색 예시 (동적 쿼리)

// BooleanBuilder 방식
BooleanBuilder builder = new BooleanBuilder();
if (name != null) {
    builder.and(user.name.eq(name));
}
if (age != null) {
    builder.and(user.age.goe(age));
}

List<User> result = queryFactory
    .selectFrom(user)
    .where(builder)
    .fetch();

// 다중 파라미터 방식 (더 깔끔한 코드)
List<User> result = queryFactory
    .selectFrom(user)
    .where(
        nameEq(name),
        ageGoe(age)
    )
    .fetch();

// 조건 메소드 정의
private BooleanExpression nameEq(String name) {
    return name != null ? user.name.eq(name) : null;
}

private BooleanExpression ageGoe(Integer age) {
    return age != null ? user.age.goe(age) : null;
}

정렬, 페이징 예시

List<User> result = queryFactory
    .selectFrom(user)
    .orderBy(user.age.desc(), user.name.asc())
    .offset(pageable.getOffset())
    .limit(pageable.getPageSize())
    .fetch();

// 전체 카운트 쿼리
Long count = queryFactory
    .select(user.count())
    .from(user)
    .fetchOne();

조인 및 프로젝션 예시

List<Tuple> result = queryFactory
    .select(
        user.name,
        order.orderDate,
        order.status
    )
    .from(user)
    .join(user.orders, order)
    .where(user.age.gt(20))
    .fetch();

5. 마무리 — 언제 어떤 기술을 선택할까?

상황	추천 도구	이유
단순 CRUD	Spring Data JPA	코드 최소화, 빠른 개발
비교적 단순한 조건 검색	JPQL/Native Query	간단한 구현, 익숙한 SQL 구문
복잡한 조건, 동적 쿼리	QueryDSL	타입 안전성, 유지보수성 우수
최적화가 필요한 복잡한 쿼리	JPA + Native SQL	성능에 초점, 데이터베이스 최적화 활용

추가로 알면 좋은 것들

• QueryDSL + Spring Data JPA 통합 사용법:
  • QuerydslPredicateExecutor 인터페이스 활용
  • QuerydslRepositorySupport 상속
  • 사용자 정의 레포지토리 구현을 통한 통합
• Modern QueryDSL 활용 기법:
  • JPAQueryFactory Bean 등록을 통한 의존성 주입 패턴
  • BooleanExpression 반환 메소드를 활용한 조건 모듈화
  • Projection을 위한 DTO 직접 조회 최적화 (@QueryProjection 활용)
• QueryDSL의 다양한 지원:
  • JPA, SQL(JDBC), MongoDB, Lucene 등 다양한 백엔드 지원
  • 4.x 버전 사용이 안정적이며 현재 가장 널리 사용됨
  • 5.0 버전은 개발 중으로 Java 8+ 지원 예정

맺으며

QueryDSL은 JPA를 사용하는 실무 환경에서 매우 유용한 도구입니다. 특히 동적 조건 검색이나 복잡한 조회 쿼리가 많은 프로젝트에서 그 진가를 발휘합니다. 초기 설정의 복잡함과 학습 비용은 있지만, 중장기적인 관점에서 코드 품질과 생산성 향상에 크게 기여합니다.

최근에는 Spring Data JPA와의 통합이 더욱 자연스러워지고, 여러 써드파티 라이브러리들이 등장하면서 QueryDSL 생태계가 더욱 풍부해지고 있습니다. 자바 백엔드 개발자라면 QueryDSL을 익혀두면 큰 무기가 될 것입니다.