Java 后端 / 系统课时
编写派生查询与 JPQL
编写派生查询与 JPQL
本课解决仓储层“查询方式怎么选”的问题。你将用一个可运行测试同时验证方法名派生查询、@Query 编写的 JPQL 和原生 SQL,并掌握从简单条件到复杂查询的升级边界。
学习目标
- 根据查询复杂度选择派生查询、JPQL 或原生 SQL
- 正确区分实体属性名与数据库表字段名
- 用集成测试验证查询条件、排序和聚合结果
选择查询方式
Spring Data JPA 会根据仓储接口生成实现,但不同查询方式适合的复杂度不同。
| 方式 | 适合场景 | 主要约束 |
|---|---|---|
| 方法名派生查询 | 条件少、含义直观的等值、范围、模糊和排序查询 | 方法名过长后可读性迅速下降 |
| JPQL | 多条件、投影、关联查询和聚合 | 使用实体名与 Java 属性名,不直接使用表名 |
| 原生 SQL | 数据库特有函数、复杂窗口查询或已有 SQL 复用 | 与数据库方言耦合,分页时常需额外 countQuery |
选择原则是先用最简单且可读的方式。派生方法一旦需要多个可选条件、复杂连接或数据库专有能力,就应升级为 JPQL、Specification 或原生 SQL,而不是继续拉长方法名。
编写并验证三类查询
下面的完整测试文件依赖 Spring Boot 3、Spring Data JPA、H2 和 AssertJ。将它保存为 src/test/java/com/example/demo/UserRepositoryTest.java,测试会自动创建内存数据库并验证三种查询结果。
package com.example.demo;
import jakarta.persistence.Entity;
import jakarta.persistence.GeneratedValue;
import jakarta.persistence.Id;
import jakarta.persistence.Table;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.orm.jpa.DataJpaTest;
import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.data.jpa.repository.Query;
import org.springframework.data.repository.query.Param;
import org.springframework.test.context.TestPropertySource;
import java.time.Instant;
import java.util.List;
import static org.assertj.core.api.Assertions.assertThat;
@Entity
@Table(name = "user_account")
class UserAccount {
@Id
@GeneratedValue
private Long id;
private String email;
private String status;
private Instant createdAt;
// JPA 通过无参构造器恢复实体,业务代码不应直接调用。
protected UserAccount() {
}
UserAccount(String email, String status, Instant createdAt) {
this.email = email;
this.status = status;
this.createdAt = createdAt;
}
String getEmail() {
return email;
}
}
interface UserRepository extends JpaRepository<UserAccount, Long> {
// 简单且固定的条件交给方法名解析,排序也由名称声明。
List<UserAccount> findByStatusAndEmailContainingIgnoreCaseOrderByCreatedAtDesc(
String status, String keyword);
// JPQL 使用实体名和属性名,不使用数据库表名。
@Query("""
select u
from UserAccount u
where u.status = :status
and u.createdAt >= :from
order by u.createdAt desc
""")
List<UserAccount> findRecentByStatus(
@Param("status") String status,
@Param("from") Instant from);
// 只有需要直接控制 SQL 时才启用 nativeQuery。
@Query(value = """
select count(*)
from user_account
where status = :status
""", nativeQuery = true)
long countByStatusNative(@Param("status") String status);
}
@DataJpaTest
@TestPropertySource(properties = "spring.jpa.hibernate.ddl-auto=create-drop")
class UserRepositoryTest {
@Autowired
private UserRepository repository;
@Test
void shouldExecuteDerivedJpqlAndNativeQueries() {
// 固定基准时间可让排序与范围断言在每次运行中保持一致。
Instant base = Instant.parse("2026-08-01T00:00:00Z");
repository.saveAll(List.of(
new UserAccount("alice@example.com", "ACTIVE", base.plusSeconds(20)),
new UserAccount("bob@example.com", "ACTIVE", base.plusSeconds(10)),
new UserAccount("carol@example.com", "LOCKED", base)
));
List<UserAccount> derived =
repository.findByStatusAndEmailContainingIgnoreCaseOrderByCreatedAtDesc(
"ACTIVE", "example");
List<UserAccount> jpql =
repository.findRecentByStatus("ACTIVE", base.plusSeconds(15));
long nativeCount = repository.countByStatusNative("ACTIVE");
assertThat(derived).extracting(UserAccount::getEmail)
.containsExactly("alice@example.com", "bob@example.com");
assertThat(jpql).extracting(UserAccount::getEmail)
.containsExactly("alice@example.com");
assertThat(nativeCount).isEqualTo(2);
}
}运行测试:
./mvnw -Dtest=UserRepositoryTest test预期输出:
Tests run: 1, Failures: 0, Errors: 0, Skipped: 0
BUILD SUCCESS具体日志时间和本地路径可能不同,但测试数量与通过结果应一致。
理解 JPQL 与原生 SQL 的边界
JPQL 中的 UserAccount 是实体名,status 和 createdAt 是 Java 属性名;原生 SQL 中的 user_account 才是表名。把表名写进 JPQL,或把驼峰属性名直接写进原生 SQL,通常会在启动或执行查询时失败。
JPQL 适合保持领域模型与数据库结构解耦。原生 SQL 则适合窗口函数、数据库特有 JSON 操作或经过专项优化的复杂语句。原生查询返回实体时,结果列必须能映射实体字段;返回自定义结构时,应使用接口投影或 DTO 映射明确接收结果。
处理查询边界
派生查询中的 null 参数通常会生成 is null 语义,而不是自动忽略条件。需要“参数为空就不筛选”时,应显式写 JPQL 条件,或使用 Specification 动态组装谓词。
分页查询若使用复杂原生 SQL,应同时提供准确的计数语句,否则总页数可能错误。对集合关联使用 fetch join 时还要警惕结果重复和分页失真,必要时先分页查询主键,再单独加载关联数据。