QueryDSL Q클래스 실종 이유: 환경변수 - Gradle 까지

문제 상황

QueryDSL을 적용하려고 했지만, 가장 먼저 막힌 부분은 QUser 같은 Q클래스가 보이지 않는 문제였다.

예를 들어 RepositoryImpl 에서 해당 코드를 쓰고 싶은데

QUser user = QUser.user;

IDE에서는 QUser 자체를 찾지 못했다.

처음에는 QueryDSL 문법 문제라고 생각했지만, 실제 원인은 Q 클래스 생성 자체가 안 된 것이었다.

---

원인 정리

문제를 추적해보니, 단순히 import 문제가 아니라 여러 설정이 겹쳐있었다.

1. 의존성 필요

implementation 'com.querydsl:querydsl-jpa:5.1.0:jakarta'
annotationProcessor 'com.querydsl:querydsl-apt:5.1.0:jakarta'
annotationProcessor 'jakarta.annotation:jakarta.annotation-api'
annotationProcessor 'jakarta.persistence:jakarta.persistence-api'

2. Config 필요

@Configuration
public class QueryDslConfig {

    @PersistenceContext
    private EntityManager em;

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

3. 로컬 Java 환경변수 문제
   가장 크게 시간을 잡아먹은 건 사실 로컬 Java 환경변수 문제였다.

Gradle 실행 시 아래와 같은 에러가 발생했다.

• JAVA_HOME is not set
• java command could not be found

즉, gradlew 는 실행됐지만, Java를 찾지 못하는 상태였다.

---

해결 과정

1. InteliJ에서 실제 JDK 경로 확인

2. JAVA_HOME 설정
   사용자 환경 변수에 값을 추가했다

3. Path 설정
   처음에는 %JAVA_HOME%\bin을 넣었지만, 환경에 따라 문자열 그대로 남아 Java를 찾지 못하는 문제가 있었다.
   최종적으로는 절대경로를 직접 넣는 방식으로 해결했다.

4. Gradle 빌드 재실행
   환경변수 설정 후 다음 명령으로 컴파일을 다시 수행했다.

.\gradlew.bat clean compileJava --info

그 결과 Q 클래스가 생성되었고, build/generated/sources/annotationProcessor/java/main 경로 아래에서 확인할 수 있었다.

---

느낀점

처음에는 QueryDSL 문법이 문제라고 생각했지만, 실제로는 다음 세 가지가 얽혀 있었다.

• Gradle 의존성 설정
• annotation processor 동작 여부
• Java 환경변수 설정

그 결과 Q 클래스가 생성되었고, build/generated/sources/annotationProcessor/java/main 경로 아래에서 확인할 수 있었다.

---

정리

이번 문제의 핵심은 QueryDSL Q 클래스가 자동 생성되지 않았다는 점이었다.
원인은 annotation processor 설정과 Java 환경변수 문제였고,
Gradle 설정 수정 + JAVA_HOME/Path 설정 + 재빌드를 통해 해결할 수 있었다.

결과적으로 QueryDSL 자체보다도, 개발 환경과 빌드 시스템을 정확히 이해하는 과정이 더 중요하다는 걸 많이 배운 작업이었다.