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,测试会自动创建内存数据库并验证三种查询结果。

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);
    }
}

运行测试:

bash
./mvnw -Dtest=UserRepositoryTest test

预期输出:

text
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 时还要警惕结果重复和分页失真,必要时先分页查询主键,再单独加载关联数据。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

编写派生查询与 JPQL

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通