QueryDSL 完整實戰指南：類型安全的動態查詢解決方案

Sun, 08 Aug 2021 13:07:45 +0800

維護狀態說明：QueryDSL 4.x 自 2018 年後長期缺乏維護；5.0.0（2022 年）雖遷移至 Jakarta namespace，但開發活躍度仍低。評估新專案時請考量以下替代方案：

方案	適用場景	維護狀態
QueryDSL 5.x	現有專案延續、需要複雜型別安全查詢	低度維護
Spring Data JPA Specification	簡單動態查詢，無需額外依賴	積極維護
jOOQ	複雜 SQL、需要完整 SQL 功能	積極維護
Blaze-Persistence	JPA 進階查詢、Entity View	積極維護

概述

QueryDSL 是一個強大的 Java 查詢框架，提供類型安全的 SQL 查詢建構功能。它通過代碼生成技術創建查詢類型，在編譯時期就能發現查詢錯誤，大幅提升開發效率和代碼質量。本文將深入介紹 QueryDSL 的各種用法和最佳實踐。

核心優勢

類型安全：編譯時檢查，避免執行期錯誤
IDE 支援：完整的自動完成和重構功能
統一 API：支援 JPA、SQL、MongoDB 等多種數據源
動態查詢：靈活的條件組合和查詢建構
效能優化：生成高效的 SQL 查詢

支援的技術棧

JPA/Hibernate：最常用的 ORM 整合
Spring Data JPA：與 Spring 生態完美整合
SQL 數據庫：MySQL、PostgreSQL、Oracle 等
NoSQL 數據庫：MongoDB、Lucene 等

環境配置與設定

1. Maven 依賴配置

<properties>
    <querydsl.version>5.0.0</querydsl.version>
    <maven.compiler.source>17</maven.compiler.source>
    <maven.compiler.target>17</maven.compiler.target>
</properties>

<dependencies>
    <!-- Spring Boot Starter Data JPA -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-data-jpa</artifactId>
    </dependency>
    
    <!-- QueryDSL JPA -->
    <dependency>
        <groupId>com.querydsl</groupId>
        <artifactId>querydsl-jpa</artifactId>
        <version>${querydsl.version}</version>
        <classifier>jakarta</classifier>
    </dependency>
    
    <!-- QueryDSL APT (Annotation Processing Tool) -->
    <dependency>
        <groupId>com.querydsl</groupId>
        <artifactId>querydsl-apt</artifactId>
        <version>${querydsl.version}</version>
        <classifier>jakarta</classifier>
        <scope>provided</scope>
    </dependency>
    
    <!-- Database Driver -->
    <dependency>
        <groupId>mysql</groupId>
        <artifactId>mysql-connector-java</artifactId>
        <scope>runtime</scope>
    </dependency>
    
    <!-- Validation -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-validation</artifactId>
    </dependency>
</dependencies>

<build>
    <plugins>
        <!-- Maven Compiler Plugin -->
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <version>3.11.0</version>
            <configuration>
                <source>17</source>
                <target>17</target>
                <annotationProcessorPaths>
                    <path>
                        <groupId>com.querydsl</groupId>
                        <artifactId>querydsl-apt</artifactId>
                        <version>${querydsl.version}</version>
                        <classifier>jakarta</classifier>
                    </path>
                    <path>
                        <groupId>jakarta.persistence</groupId>
                        <artifactId>jakarta.persistence-api</artifactId>
                        <version>3.1.0</version>
                    </path>
                    <path>
                        <groupId>jakarta.annotation</groupId>
                        <artifactId>jakarta.annotation-api</artifactId>
                        <version>2.1.1</version>
                    </path>
                </annotationProcessorPaths>
            </configuration>
        </plugin>
        
        <!-- Generate Sources Plugin -->
        <plugin>
            <groupId>org.codehaus.mojo</groupId>
            <artifactId>build-helper-maven-plugin</artifactId>
            <version>3.4.0</version>
            <executions>
                <execution>
                    <phase>generate-sources</phase>
                    <goals>
                        <goal>add-source</goal>
                    </goals>
                    <configuration>
                        <sources>
                            <source>target/generated-sources/annotations</source>
                        </sources>
                    </configuration>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

2. Gradle 配置

plugins {
    id 'org.springframework.boot' version '3.1.0'
    id 'io.spring.dependency-management' version '1.1.0'
    id 'java'
}

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
    implementation 'org.springframework.boot:spring-boot-starter-web'
    implementation 'org.springframework.boot:spring-boot-starter-validation'
    
    // QueryDSL
    implementation 'com.querydsl:querydsl-jpa:5.0.0:jakarta'
    annotationProcessor 'com.querydsl:querydsl-apt:5.0.0:jakarta'
    annotationProcessor 'jakarta.persistence:jakarta.persistence-api'
    annotationProcessor 'jakarta.annotation:jakarta.annotation-api'
    
    runtimeOnly 'mysql:mysql-connector-java'
    testImplementation 'org.springframework.boot:spring-boot-starter-test'
}

// QueryDSL 配置
def queryDslDir = "$buildDir/generated/querydsl"

querydsl {
    jpa = true
    querydslSourcesDir = queryDslDir
}

sourceSets {
    main.java.srcDir queryDslDir
}

configurations {
    querydsl.extendsFrom compileClasspath
}

compileQuerydsl {
    options.annotationProcessorPath = configurations.querydsl
}

IntelliJ IDEA + Gradle APT 常見問題

QueryDSL 依賴 Annotation Processing（APT）在編譯時產生 Q 類別（如 QUser）。IntelliJ 與 Gradle APT 的整合不完美，常見錯誤及解法：

QueryDSL on Bill.Lin's Notes