[QueryDSL] 5. 프로젝션과 DTO 매핑

엔티티 전체를 가져오는 것이 항상 좋은 것은 아니다. API 응답에는 이름과 이메일만 필요한데 엔티티의 모든 컬럼을 SELECT하면 불필요한 데이터 전송이 발생한다. 필요한 컬럼만 골라서 DTO로 바로 받는 것, 이것이 프로젝션이다.

단일 컬럼 프로젝션

컬럼 하나만 조회하면 해당 타입의 리스트로 바로 받을 수 있다.

List<String> names = queryFactory
        .select(user.name)
        .from(user)
        .fetch();

반환 타입이 List<String>이다. select에 Path 하나만 넣으면 해당 Path의 Java 타입으로 결과가 반환된다.

Tuple

컬럼 여러 개를 조회하되, DTO를 따로 만들기 애매할 때 Tuple을 쓴다.

List<Tuple> result = queryFactory
        .select(user.name, user.email)
        .from(user)
        .fetch();

for (Tuple tuple : result) {
    String name = tuple.get(user.name);
    String email = tuple.get(user.email);
}

Tuple은 QueryDSL이 제공하는 제네릭 컨테이너다. tuple.get()에 조회할 때 사용한 것과 같은 Path를 넣으면 해당 값을 꺼낼 수 있다.

Projections.constructor

생성자를 기반으로 DTO에 값을 매핑한다. 가장 널리 쓰이는 방식이다.

public record UserDto(String name, String email) {}

이 DTO에 다음과 같이 매핑한다.

List<UserDto> users = queryFactory
        .select(Projections.constructor(
                UserDto.class,
                user.name,
                user.email
        ))
        .from(user)
        .fetch();

Projections.constructor는 select에 나열한 컬럼 순서대로 생성자 파라미터에 매핑한다. DTO에 (String, String) 생성자가 있어야 한다. record 클래스는 컴팩트 생성자가 자동 생성되므로 바로 사용할 수 있다.

장점

• 컴파일 타임에 생성자 존재 여부를 검증한다.
• 불변 객체(record)와 잘 어울린다.

주의점

• 컬럼 순서가 생성자 파라미터 순서와 일치해야 한다. 순서가 바뀌면 런타임에 값이 뒤섞이거나 타입 불일치 예외가 발생한다.

Projections.fields

필드에 직접 값을 주입한다. 리플렉션으로 동작하므로 setter나 생성자가 필요 없다.

List<UserDto> users = queryFactory
        .select(Projections.fields(
                UserDto.class,
                user.name,
                user.email
        ))
        .from(user)
        .fetch();

필드 이름과 컬럼 이름이 일치해야 매핑된다. 이름이 다르면 .as() 별칭을 붙여야 한다.

Projections.fields(
        UserDto.class,
        user.name.as("userName"),   // DTO의 필드명이 userName인 경우
        user.email
)

필드명이 바뀌어도 컴파일 에러가 나지 않고 null로 들어가므로, 리팩토링에 취약하다는 단점이 있다.

Projections.bean

setter를 기반으로 값을 주입한다. JavaBean 규약을 따르는 DTO에 사용한다.

@Getter @Setter
public class UserDto {
    private String name;
    private String email;
}

사용법은 fields와 동일하다.

List<UserDto> users = queryFactory
        .select(Projections.bean(
                UserDto.class,
                user.name,
                user.email
        ))
        .from(user)
        .fetch();

fields와 마찬가지로 이름 기반 매핑이다. 다른 점은 setter 메서드를 호출한다는 것이다. setter가 없으면 값이 주입되지 않는다.

@QueryProjection

DTO 생성자에 @QueryProjection을 붙이면, 해당 DTO의 Q클래스가 생성된다. 컴파일 타임에 타입과 순서를 모두 검증할 수 있는 가장 안전한 방식이다.

public class UserDto {
    private String name;
    private String email;

    @QueryProjection
    public UserDto(String name, String email) {
        this.name = name;
        this.email = email;
    }
}

빌드하면 QUserDto가 생성된다. 사용법은 이렇다.

List<UserDto> users = queryFactory
        .select(new QUserDto(user.name, user.email))
        .from(user)
        .fetch();

QUserDto의 생성자는 StringPath를 받으므로, 잘못된 타입이나 순서를 넣으면 컴파일 에러가 난다. Projections.constructor에서 발생할 수 있는 순서 실수를 원천 차단한다.

방식 비교

각 방식의 특성을 정리한다.

Projections.constructor

• 생성자 파라미터 순서로 매핑
• 불변 객체(record) 호환
• 순서 실수 시 런타임 에러

Projections.fields

• 필드 이름으로 매핑
• setter/생성자 불필요
• 이름 불일치 시 null (런타임)

Projections.bean

• setter로 매핑
• 필드 이름 기반
• setter 필수

@QueryProjection

• 컴파일 타임 검증
• 타입 + 순서 모두 안전
• DTO에 QueryDSL 의존 발생

실무에서는 Projections.constructor 또는 @QueryProjection을 주로 사용한다. constructor는 DTO의 독립성을 유지하면서도 생성자 기반 매핑이 가능하고, @QueryProjection은 안전성이 필요한 핵심 쿼리에 적합하다. fields와 bean은 이름 기반이라 리팩토링에 취약하므로, 레거시 호환이 아니면 쓸 이유가 적다.

자주 하는 실수

---