📚[Spring] QueryDSL

스트링 쿼리의 단점

스트링 쿼리(String Query)란 JPA 에서 JPQL 이나 SQL 쿼리를 문자열로 직접 작성하는 것을 말하며
보통 @Query 어노테이션을 통해 사용된다.
복잡한 조건을 명시적으로 다룰 수 있어 빠르게 구현할 수 있다는 장점이 있지만 오타나 문법 오류가
컴파일 타임에 검출되지 않아 런타임 오류로 이어질 수 있다는 치명적인 단점이 있다.
또한 문자열로 조건을 조합해야 하므로 동적 쿼리 작성이 복잡하고 불편하다는 한계도 존재한다.

JPQL 의 동적 쿼리 예시 - TaskCustomRepository

	public List<Task> searchTasks(String title, String content, String status) {
	//조건문을 추가할 기본 jpql
	String jpql = "select t from Task t";

	//조건문을 담을 리스트
	List<String> conditionList = new ArrayList<>();

	if(StringUtils.hasText(title)) {
		conditionList.add("t.title like concat('%', :title, '%')"); //와일드카드 포함
	}
	if(StringUtils.hasText(content)) {
		conditionList.add("t.content like concat('%', :content, '%')");
	}
	if(StringUtils.hasText(status)) {
		conditionList.add("t.status = :status");
	}

	//조건리스트가 하나라도 있다면 where + conditionList.get(0) + and + .get(1) ...
	if(!conditionList.isEmpty()) {
		jpql += " where " + String.join(" and ", conditionList);
	}

	//완성된 jpql 을 기반으로 쿼리 객체 생성
	TypedQuery<Task> query = em.createQuery(jpql, Task.class);

	//파라미터 바인딩
	if(StringUtils.hasText(title)) {
		query.setParameter("title", title); //와일드카드 포함
	}
	if(StringUtils.hasText(content)) {
		query.setParameter("content", content);
	}
	if(StringUtils.hasText(status)) {
		//이넘타입 변환 메서드 소문자도 가능
		Status fromStatus = Status.from(status);
		query.setParameter("status", fromStatus);
	}

	System.out.println("JPQL: " + jpql);
	//결과 리스트 반환
	return query.getResultList();
}

3개의 파라미터를 처리하는 동적 쿼리임에도 불구하고 코드가 꽤 복잡하다는 것을 알 수 있다.
조건이 늘어갈수록 코드의 가독성은 급격하게 떨어지고 각 조건을 일일이 검사하고 문자열을 조립하고 파라미터를 바인딩하는 과정이 번거롭고 실수가 발생하기 쉽다.
이처럼 단순한 조건이라도 로직이 복잡해지면 관리가 어려워지기 때문에 실무에서는 코드의 안정성과 가독성, 유지보수성을 위해 QueryDSL 같은 도구를 많이 사용한다.

---

QueryDSL

들어가기에 앞서 QueryDSL은 스프링 시큐리티에 내장된 기능이 아니다.
따라서 QueryDsl을 사용하기 위해선 선행되어야 할 작업들이 있다.

먼저 추가해줄 의존성은 아래와 같다.

    //QueryDSL 추가
    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"

1. implementation 'com.querydsl:querydsl-jpa:5.1.0:jakarta'
   • QueryDSL 에서 JPA를 사용할 수 있게 해주는 핵심 라이브러리
   • 이 의존성을 통해 JPAQueryFactory, Q클래스 등 Q클래스를 활용한 쿼리 작성이 가능
2. annotationProcessor "com.querydsl:querydsl-apt:5.1.0:jakarta"
   • APT: Annotation Processing Tool (소스코드 생성도구)
   • @Entity 가 붙은 클래스들을 분석해서 Q클래스를 자동 생성해주는 도구
3. annotationProcessor "jakarta.annotation:jakarta.annotation-api"
   • QueryDSL APT가 작동할 때 필요한 자바 어노테이션 처리관련 API
   • @Generated, @Nullable, @PostConstruct 같은 어노테이션의 정의가 들어 있음
4. annotationProcessor "jakarta.persistence:jakarta.persistence-api"
   • JPA 어노테이션 정의(@Entity, @Id, @Column)를 제공
   • QueryDsl 이 엔티티를 올바르게 등을 보고 Q클래스를 만들기 때문에 해당 API가 필요

의존성 추가후

• compileJava 실행 시 build/generated/.../Q클래스 자동으로 생성

---

QueryDslConfig

QueryDSL을 활용하기 위해서는 JPAQueryFactory 객체가 필요하다.
이를 위해 별도의 설정 클래스를 생성하고 EntityManager를 주입받아 JPAQueryFactory를 빈으로 등록한다.

@Configuration
public class QueryDslConfig {

	@PersistenceContext
	private EntityManager entityManager;

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

이렇게 등록된 JPAQueryFactory는 Spring Bean으로 관리되기 때문에 서비스나 커스텀 리포지토리 클래스에서 바로 주입받아 QueryDSL 쿼리를 쉽게 사용할 수 있다.

---

Projection

QueryDsl에서는 JPA의 기본 프로젝션(SELECT new 패키지명...)과 다르게 다양한 방식으로 DTO에 직접 데이터를 매핑할 수 있다.

@Getter
public class TaskSearchRequestDto {
	private String title;
	private String content;
	private String status;
	
	public TaskSearchRequestDto(String title, String content, String status) {
		this.title = title;
		this.content = content;
		this.status = status;
    }
}

이처럼 생성자를 정의해놓고 다음과 같이 프로젝션이 가능하다.

.select(Projections.constructor(TaskSearchRequestDto.class, task.title, task.content, task.status))

---

@QueryProjection

생성자에 @QueryProjection 어노테이션을 붙여준 뒤 compileJava를 실행하면 해당 DTO에 대한 Q클래스가 함께 생성된다.

해당 어노테이션을 사용시 다양한 장점을 얻을 수 있다.

• 타입안정성: 컴파일 타임에 오류를 잡아줌(필드 누락, 잘못된 순서 등)
• 리팩토링 안전: 생성자 변경 시 컴파일 에러로 즉시 확ㅇ니 가능
• 깔끔한 문법: Projections.constructor(...) 보다 직관적이고 짧음

.select(new QTaskSearchRequestDto(task.title, task.content, task.status))

하지만 DTO까지 Q클래스가 생성됨에 따라 QueryDSL에 대한 의존도가 너무 높아지게 된다.
모듈화나 계층 분리를 중시하는 구조에서는 사용에 대해 고려해볼 필요가 있다.

---

Where절 다중 파라미터 방식

QueryDsl에서 .where() 절 안에 여러개의 조건을 나열해서 사용하는 방식으로 조건들이 null인지 여부와 상관없이 한 번에 처리할 수 있다는 장점을 가진다.

@Repository
@RequiredArgsConstructor
public class TaskCustomRepositoryImpl implements TaskCustomRepository{

	private final JPAQueryFactory queryFactory;

	@Override
	public List<Task> searchTasksByQueryDsl(String title, String content, String status) {
		return queryFactory
			.selectFrom(task)
			.where(titleContains(title), contentContains(content), statusEq(status))
			.fetch();
	}

	private BooleanExpression titleContains(String title) {
		return title != null ? task.title.contains(title) : null;
	}

	private BooleanExpression contentContains(String content) {
		return content != null ? task.content.contains(content) : null;
	}

	private BooleanExpression statusEq(String status) {
		return status != null ? task.status.eq(Status.from(status)) : null;
	}

}

.where() 절 안에 BooleanExpression 을 반환하는 메서드를 나열해서 사용한다.
해당 메서드들은 파라미터에 전달된 값이 있을 경우 문자열 조건에 맞는 값을 반환한다.
queryDsl은 조건에 null이 포함될 경우 조건을 무시하므로 오류 없이 동적쿼리가 완성된다.

---

가독성/재사용성 향상

private BooleanExpression titleContains(String title) {
	//삼항 연산자로 간결하게 표현
   return title != null ? task.title.contains(title) : null;
}

위처럼 BooleanExpression 메서드만 정의해 놓으면 쿼리문이 깔끔해지고 재사용도 용이해진다.

---

마치며

BooleanExpression 방식 외에도 보다 복잡한 조건을 쓸 땐 BooleanBuilder를 사용하는 방식도 있다.
다음 기회엔 BooleanBuilder를 통해 조금 더 복잡한 쿼리문도 작성해 볼 예정이다.
추가로 QueryDSL 문자열 조건 메서드에 대해 정리한 표를 첨부하며 마무리하겠다.

---

QueryDSL 문자열 조건 메서드

메서드	SQL 변환	설명
eq("abc")	= 'abc'	정확히 일치
ne("abc")	!= 'abc'	일치하지 않음
contains("abc")	LIKE '%abc%'	특정 문자열 포함
startsWith("abc")	LIKE 'abc%'	특정 문자열로 시작
endsWith("abc")	LIKE '%abc'	특정 문자열로 끝남
like("%abc%")	LIKE '%abc%'	와일드카드 직접 지정
in(list)	IN (...)	여러 값 중 포함
isNull()	IS NULL	값이 null 인 경우
isNotNull()	IS NOT NULL	null 이 아닌 경우

---