[트러블슈팅] Spring Boot에서 동적 쿼리 개선하기: @Query에서 QueryDSL로

TROUBLE SHOOTING

Spring Boot에서 동적 쿼리 개선하기 — @Query에서 QueryDSL로

목차

• 1. 들어가며
• 2. 처음 구현 — @Query
• 3. QueryDSL 도입
• 4. 빈 등록 및 Repository 구조
• 5. @Query vs QueryDSL 비교
• 6. 트러블슈팅: Q클래스 생성 오류
• 7. 마치며

01. 들어가며

Booktine 프로젝트에서 게시물 검색 기능을 구현하면서 동적 쿼리 처리 방식을 고민하게 됐다. 요구사항은 사용자가 키워드(제목, 저자)와 독서 상태(읽는 중, 완독, 읽고 싶음)를 조건으로 게시물을 검색할 수 있어야 했다. 문제는 두 조건 모두 선택 사항이라는 것이다. 키워드만 입력할 수도 있고, 상태만 선택할 수도 있고, 아무 조건 없이 전체 조회를 할 수도 있다.

이런 동적 쿼리 상황에서 처음에는 @Query로 구현했다가 QueryDSL로 전환했고, 그 과정을 정리했다.

02. 처음 구현 — @Query

처음에는 JPA @Query로 간단하게 작성했다.

@Query("SELECT p FROM Post p WHERE p.user.id = :userId " +
       "AND (:keyword IS NULL OR p.title LIKE %:keyword% OR p.author LIKE %:keyword%) " +
       "AND (:status IS NULL OR p.readingStatus = :status)")
List<Post> searchPosts(Long userId, String keyword, ReadingStatus status);

동작은 했지만 코드를 보면서 몇 가지 불편함이 느껴졌다.

문제점

• 문자열 쿼리라 컴파일 타임에 오류를 잡을 수 없다. p.title을 p.titlee로 오타를 내도 컴파일은 통과하고 런타임에서야 오류가 난다.
• 조건이 추가될수록 쿼리 문자열이 길어진다. 지금은 조건이 2개지만 장르 필터, 날짜 범위 등이 추가되면 쿼리가 한눈에 들어오지 않는다.
• IS NULL 처리 방식이 어색하다. 조건이 없을 때를 처리하기 위해 :keyword IS NULL OR ... 패턴을 반복해야 한다.

03. QueryDSL 도입

QueryDSL이란?

QueryDSL은 자바 코드로 타입 안전하게 쿼리를 작성할 수 있게 해주는 프레임워크다. 엔티티 클래스를 기반으로 QPost, QUser 같은 Q클래스를 자동 생성하고, 이를 이용해 IDE 자동완성과 컴파일 타임 검증을 지원한다.

의존성 추가 (build.gradle)

dependencies {
    implementation 'com.querydsl:querydsl-jpa:5.0.0:jakarta'
    annotationProcessor 'com.querydsl:querydsl-apt:5.0.0:jakarta'
    annotationProcessor 'jakarta.annotation:jakarta.annotation-api'
    annotationProcessor 'jakarta.persistence:jakarta.persistence-api'
}

def generated = 'src/main/generated'

sourceSets {
    main.java.srcDirs += [generated]
}

tasks.withType(JavaCompile) {
    options.getGeneratedSourceOutputDirectory().set(file(generated))
}

clean {
    delete file(generated)
}

./gradlew compileJava를 실행하면 src/main/generated 경로에 Q클래스가 자동 생성된다.

참고: src/main/generated는 빌드 시 자동 생성되는 파일이므로 .gitignore에 추가하자.

# QueryDSL
src/main/generated

04. 빈 등록 및 Repository 구조

JPAQueryFactory 빈 등록

@Configuration
public class QueryDslConfig {
    @PersistenceContext
    private EntityManager entityManager;

    @Bean
    public JPAQueryFactory jpaQueryFactory() {
        return new JPAQueryFactory(entityManager);
    }
}

Repository 구조

• PostRepository: JpaRepository + PostRepositoryCustom 상속
• PostRepositoryCustom: 인터페이스
• PostRepositoryImpl: QueryDSL 구현체

PostRepositoryImpl.java 구현

@RequiredArgsConstructor
public class PostRepositoryImpl implements PostRepositoryCustom {
    private final JPAQueryFactory queryFactory;

    @Override
    public List<Post> searchPosts(Long userId, String keyword, ReadingStatus status) {
        QPost post = QPost.post;
        BooleanBuilder builder = new BooleanBuilder();

        // 필수 조건: 사용자 ID
        builder.and(post.user.id.eq(userId));

        // 선택 조건: 키워드 (제목 또는 저자)
        if (keyword != null && !keyword.isBlank()) {
            builder.and(
                post.title.containsIgnoreCase(keyword)
                    .or(post.author.containsIgnoreCase(keyword))
            );
        }

        // 선택 조건: 독서 상태
        if (status != null) {
            builder.and(post.readingStatus.eq(status));
        }

        return queryFactory
                .selectFrom(post)
                .where(builder)
                .orderBy(post.createdAt.desc())
                .fetch();
    }
}

05. @Query vs QueryDSL 비교

비교 항목	@Query	QueryDSL
타입 안전성	❌ 런타임 오류 가능	✅ 컴파일 타임 검증
동적 쿼리 가독성	❌ 조건 많아질수록 복잡	✅ BooleanBuilder로 깔끔
조건 추가 확장성	❌ 쿼리 문자열 직접 수정	✅ 조건 블록만 추가
설정 복잡도	✅ 설정 불필요	❌ 의존성/Q클래스 설정
학습 곡선	✅ 낮음 (SQL 유사)	❌ 다소 있음

06. 트러블슈팅 — Q클래스 생성 오류

[Error] cannot find symbol: QPost post = QPost.post;

원인: APT가 Q클래스를 생성할 출력 경로가 설정되지 않아 compileJava 실행 시 Q클래스가 생성되지 않은 것이었습니다.

해결: build.gradle에 Q클래스 생성 경로 설정을 추가하고 ./gradlew clean compileJava를 다시 실행하니 src/main/generated에 Q클래스가 정상 생성됐습니다.

07. 마치며

현재 조건이 2개뿐인 단순한 검색 기능에서는 @Query로도 충분히 구현 가능하다. 하지만 이후 장르 필터, 날짜 범위 검색 등 조건이 추가될 것을 고려해 QueryDSL을 도입했다. 초기 설정 비용이 다소 있지만 타입 안전성과 확장성 면에서 장기적으로 유지보수가 훨씬 편하다는 걸 느꼈다.

Last Sync: 2026-04-29 | Booktine Project Log