[QueryDSL] 4. 동적 쿼리

검색 기능을 만들면 "이름은 입력했고, 나이는 안 넣었고, 지역은 선택했고..." 같은 상황이 생긴다. 조건이 있으면 적용하고 없으면 무시하는 쿼리, 이것이 동적 쿼리다. QueryDSL이 가장 빛나는 영역이기도 하다.

BooleanBuilder

BooleanBuilder는 조건을 하나씩 쌓아가는 가변 객체다.

public List<User> search(String name, Integer minAge, String region) {
    BooleanBuilder builder = new BooleanBuilder();

    if (name != null) {
        builder.and(user.name.contains(name));
    }
    if (minAge != null) {
        builder.and(user.age.goe(minAge));
    }
    if (region != null) {
        builder.and(user.region.eq(region));
    }

    return queryFactory
            .selectFrom(user)
            .where(builder)
            .fetch();
}

BooleanBuilder는 빈 상태에서 시작해서, 조건이 존재할 때만 and()로 추가한다. 최종적으로 where에 전달하면, 추가된 조건들이 AND로 연결된 하나의 조건이 된다. 조건이 하나도 없으면 where가 생략된다.

OR 조건 조합

AND만 쓰는 게 아니다. OR 조건을 섞어야 할 때도 있다.

BooleanBuilder builder = new BooleanBuilder();

// 이름이 "kim"이거나 "lee"인 사용자
builder.or(user.name.eq("kim"));
builder.or(user.name.eq("lee"));

// AND와 OR를 함께
BooleanBuilder andCondition = new BooleanBuilder();
andCondition.and(user.age.goe(20));
andCondition.and(builder);  // OR 조건을 AND로 묶기

OR 조건이 복잡해지면 BooleanBuilder를 중첩해서 쓸 수 있다. 다만 이 지점부터 가독성이 급격히 떨어진다.

where 다중 파라미터 패턴

QueryDSL의 where는 가변인자를 받는다. null이 전달되면 해당 조건을 무시한다. 이 특성을 활용하면 BooleanBuilder 없이도 동적 쿼리를 작성할 수 있다.

public List<User> search(String name, Integer minAge, String region) {
    return queryFactory
            .selectFrom(user)
            .where(
                    nameContains(name),
                    ageGoe(minAge),
                    regionEq(region)
            )
            .fetch();
}

private BooleanExpression nameContains(String name) {
    return name != null ? user.name.contains(name) : null;
}

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

private BooleanExpression regionEq(String region) {
    return region != null ? user.region.eq(region) : null;
}

각 조건을 별도 메서드로 분리한다. 값이 null이면 null을 반환하고, where가 알아서 무시한다. 이 방식의 장점은 뚜렷하다.

• 가독성 : 쿼리 본문에 if문이 없다. 어떤 조건들이 적용되는지 한눈에 보인다.
• 재사용 : nameContains()는 다른 쿼리에서도 그대로 쓸 수 있다.
• 조합 : BooleanExpression끼리 and(), or()로 조합할 수 있다.

// 조건 조합 예시
private BooleanExpression nameOrRegion(String name, String region) {
    BooleanExpression nameExpr = nameContains(name);
    BooleanExpression regionExpr = regionEq(region);

    if (nameExpr == null) return regionExpr;
    if (regionExpr == null) return nameExpr;
    return nameExpr.or(regionExpr);
}

BooleanBuilder vs where 다중 파라미터

두 방식의 차이를 비교하면 이렇다.

BooleanBuilder

• 가변 객체. 조건을 순서대로 쌓는다.
• if문이 메서드 본문에 들어간다.
• 복잡한 OR 조합에 유리하다.
• 조건 재사용이 어렵다.

where 다중 파라미터

• 조건별 메서드 분리. 불변 BooleanExpression을 반환한다.
• 쿼리 본문이 깔끔하다.
• 조건을 다른 쿼리에서 재사용할 수 있다.
• 실무에서 권장되는 방식이다.

일반적으로 where 다중 파라미터 방식을 기본으로 쓰고, OR 조건이 복잡하게 중첩되는 경우에만 BooleanBuilder를 보조적으로 활용하는 것이 좋다.

검색 조건 객체 활용

파라미터가 많아지면 검색 조건을 별도 객체로 묶는 것이 깔끔하다.

public record UserSearchCondition(
        String name,
        Integer minAge,
        Integer maxAge,
        String region
) {}

이 조건 객체를 받아서 쿼리를 작성한다.

public List<User> search(UserSearchCondition condition) {
    return queryFactory
            .selectFrom(user)
            .where(
                    nameContains(condition.name()),
                    ageGoe(condition.minAge()),
                    ageLoe(condition.maxAge()),
                    regionEq(condition.region())
            )
            .fetch();
}

메서드 시그니처가 깔끔해지고, 검색 조건이 늘어나도 메서드 파라미터를 바꿀 필요가 없다. 검색 조건 클래스 설계에 대한 자세한 내용은 실전 패턴과 면접 대비 편에서 다룬다.

자주 하는 실수