Spring Data JPA @Query注解

我会带着你远行 2023-09-26 10:04 61阅读 0赞

### **1. 概述** ###

Spring Data提供了许多方法来定义我们可以执行的查询。其中之一是*@Query*注释。

在本教程中，我们将演示如何**使用春季数据JPA中的*@Query*注释来执行JPQL和本机SQL查询。**

我们还将展示在*@Query*注释不够用时如何构建动态查询。

### 延伸阅读： ###

### [春季数据 JPA 存储库中的派生查询方法][JPA] ###

探索春季数据 JPA 中的查询派生机制。

[阅读更多][JPA]→

### [春季数据 JPA @Modifying注释][JPA _Modifying] ###

通过组合@Query和@Modifying注释，在春季数据 JPA 中创建 DML 和 DDL 查询

[阅读更多][JPA _Modifying]→

### **2. 选择“查询”** ###

为了定义要为Spring数据存储库方法执行的SQL，我们可以**使用*@Query*注释来注释该方法 - 其*值*属性包含要执行的JPQL或SQL。**

*@Query*批注优先于命名查询，命名查询使用*@NamedQuery*进行批注或在 *orm.xml* 文件中定义。

将查询定义放在存储库内的方法正上方，而不是作为命名查询放在域模型内部，这是一种很好的方法。存储库负责持久性，因此它是存储这些定义的更好地方。

#### **2.1. JPQL** ####

**默认情况下，查询定义使用 JPQL。**

让我们看一个简单的存储库方法，该方法从数据库中返回活动的 *User* 实体：

@Query("SELECT u FROM User u WHERE u.status = 1")
    Collection<User> findAllActiveUsers();

#### **2.2. 原生** ####

我们也可以使用本机 SQL 来定义我们的查询。我们所要做的就是将***本机Query*属性的值设置为*true***，并在注释*的值*属性中定义本机SQL查询：

@Query(
      value = "SELECT * FROM USERS u WHERE u.status = 1", 
      nativeQuery = true)
    Collection<User> findAllActiveUsersNative();

### **3. 在查询中定义顺序** ###

我们可以将 *Sort* 类型的附加参数传递给具有*@Query*批注的 Spring Data 方法声明。它将被转换为传递给数据库的 *ORDER BY* 子句。

#### **3.1. JPA 提供的方法和派生方法的排序** ####

对于我们开箱即用的方法，例如 *findAll（Sort）* 或通过解析方法签名生成的方法，**我们只能使用对象属性来定义我们的排序**：

userRepository.findAll(Sort.by(Sort.Direction.ASC, "name"));

现在想象一下，我们要按 name 属性的长度进行排序：

userRepository.findAll(Sort.by("LENGTH(name)"));

当我们执行上述代码时，我们将收到一个异常：

org.springframework.data.mapping.PropertyReferenceException: No property LENGTH(name) found for type User!

#### **3.2. JPQL** ####

**当我们使用JPQL进行查询定义时，Spring Data可以毫无问题地处理排序** \- 我们所要做的就是添加一个*Sort*类型的方法参数：

@Query(value = "SELECT u FROM User u")
    List<User> findAllUsers(Sort sort);

我们可以调用此方法并传递 *Sort* 参数，该参数将按 *User* 对象的 *name* 属性对结果进行排序：

userRepository.findAllUsers(Sort.by("name"));

由于我们使用了*@Query*注释，因此我们可以使用相同的方法来按名称的长度获取*排序的用户*列表：

userRepository.findAllUsers(JpaSort.unsafe("LENGTH(name)"));

**使用 *JpaSort.unsafe（）* 创建*排序*对象实例至关重要。**

当我们使用：

Sort.by("LENGTH(name)");

然后，我们将收到与上面*看到的 findAll（）* 方法完全相同的异常。

当Spring Data发现使用*@Query*注释的方法的不安全*排序*顺序时，它只会将排序子句附加到查询中 - 它会跳过检查排序依据的属性是否属于域模型。

#### **3.3. 原生** ####

**当*@Query*批注使用本机 SQL 时，则无法定义*排序*。**

如果我们这样做，我们将收到一个例外：

org.springframework.data.jpa.repository.query.InvalidJpaQueryMethodException: Cannot use native queries with dynamic sorting and/or pagination

正如异常情况所说，本机查询不支持排序。错误消息提示分页也会导致异常。

但是，有一种启用分页的解决方法，我们将在下一节中介绍它。

### **4. 分页** ###

分页允许我们在*主页*中仅返回整个结果的子集。例如，在网页上的多个数据页面中导航时，这很有用。

分页的另一个优点是，从服务器发送到客户端的数据量是最小的。通过发送较小的数据片段，我们通常可以看到性能的提高。

#### **4.1. JPQL** ####

在 JPQL 查询定义中使用分页非常简单：

@Query(value = "SELECT u FROM User u ORDER BY id")
    Page<User> findAllUsersWithPagination(Pageable pageable);

**我们可以传递一个*页面请求*参数来获取一页数据。**

本机查询也支持分页，但需要一些额外的工作。

#### **4.2. 原生** ####

我们可以通过**声明其他属性 *countQuery* 来为本机查询启用分页。**

这定义了要执行的 SQL，以计算整个结果中的行数：

@Query(
      value = "SELECT * FROM Users ORDER BY id", 
      countQuery = "SELECT count(*) FROM Users", 
      nativeQuery = true)
    Page<User> findAllUsersWithPagination(Pageable pageable);

#### **4.3. 2.0.4 之前的弹簧数据JPA版本** ####

上述本机查询解决方案适用于Spring数据JPA版本2.0.4及更高版本。

在该版本之前，当我们尝试执行此类查询时，我们将收到我们在上一节有关排序中描述的相同异常。

我们可以通过在查询中添加一个额外的分页参数来克服这个问题：

@Query(
      value = "SELECT * FROM Users ORDER BY id \n-- #pageable\n",
      countQuery = "SELECT count(*) FROM Users",
      nativeQuery = true)
    Page<User> findAllUsersWithPagination(Pageable pageable);

在上面的例子中，我们添加

\n-- #pageable\n

作为分页参数的占位符。这告诉春季数据JPA如何解析查询并注入可分页参数。此解决方案适用于 *H2* 数据库。

我们已经介绍了如何通过 JPQL 和本机 SQL 创建简单的选择查询。接下来，我们将演示如何定义其他参数。

### **5. 索引查询参数** ###

有两种可能的方法可以将方法参数传递给查询：索引参数和命名参数。

在本节中，我们将介绍索引参数。

#### **5.1. JPQL** ####

对于 JPQL 中的索引参数，Spring Data 将**按照方法声明中出现的顺序将方法参数传递给查询**：

@Query("SELECT u FROM User u WHERE u.status = ?1")
    User findUserByStatus(Integer status);
    
    @Query("SELECT u FROM User u WHERE u.status = ?1 and u.name = ?2")
    User findUserByStatusAndName(Integer status, String name);

对于上述查询，*状态*方法参数将分配给索引*为 1* 的查询参数，*并将 name* 方法参数分配给索引为 *2* 的查询参数。

#### **5.2. 原生** ####

本机查询的索引参数的工作方式与 JPQL 完全相同：

@Query(
      value = "SELECT * FROM Users u WHERE u.status = ?1", 
      nativeQuery = true)
    User findUserByStatusNative(Integer status);

在下一节中，我们将展示一种不同的方法：通过 name 传递参数。

### **6. 命名参数** ###

我们还**可以使用命名参数将方法参数传递给查询。**我们使用存储库方法声明中的*@Param*注释来定义这些内容。

用 *@Param* 注释的每个参数都必须具有与相应的 JPQL 或 SQL 查询参数名称匹配的值字符串。具有命名参数的查询更易于阅读，并且在需要重构查询时不易出错。

#### **6.1. JPQL** ####

如上所述，我们在方法声明中使用*@Param*注释，以将JPQL中按名称定义的参数与方法声明中的参数进行匹配：

@Query("SELECT u FROM User u WHERE u.status = :status and u.name = :name")
    User findUserByStatusAndNameNamedParams(
      @Param("status") Integer status, 
      @Param("name") String name);

请注意，在上面的示例中，我们将 SQL 查询和方法参数定义为具有相同的名称，但只要值字符串相同，就不需要它：

@Query("SELECT u FROM User u WHERE u.status = :status and u.name = :name")
    User findUserByUserStatusAndUserName(@Param("status") Integer userStatus, 
      @Param("name") String userName);

#### **6.2. 原生** ####

对于本机查询定义，与 JPQL 相比，我们如何通过名称将参数传递给查询没有区别 — 我们使用*@Param*注释：

@Query(value = "SELECT * FROM Users u WHERE u.status = :status and u.name = :name", 
      nativeQuery = true)
    User findUserByStatusAndNameNamedParamsNative(
      @Param("status") Integer status, @Param("name") String name);

### **7. 集合参数** ###

让我们考虑一下 JPQL 或 SQL 查询的 *where* 子句包含*输入*（或*非 IN*）关键字的情况：

SELECT u FROM User u WHERE u.name IN :names

在这种情况下，我们可以定义一个将 *Collection* 作为参数的查询方法：

@Query(value = "SELECT u FROM User u WHERE u.name IN :names")
    List<User> findUserByNameList(@Param("names") Collection<String> names);

由于参数是*集合*，因此可以与*列表、哈希集*等一起使用。

接下来，我们将演示如何使用 @*修改注释修改*数据。

### **8. 使用*@Modifying*更新查询** ###

我们可以**使用 @*Query* 注释来修改数据库的状态，方法是将 @*Modifying* 注释添加到**存储库方法中。

#### **8.1. JPQL** ####

与*选择*查询相比，修改数据的存储库方法有两个区别 — 它具有*@Modifying*注释，当然，JPQL 查询使用 *update* 而不是 *select*：

@Modifying
    @Query("update User u set u.status = :status where u.name = :name")
    int updateUserSetStatusForName(@Param("status") Integer status, 
      @Param("name") String name);

返回值定义执行查询时更新的行数。索引参数和命名参数都可以在更新查询中使用。

#### **8.2. 原生** ####

我们也可以使用本机查询来修改数据库的状态。我们只需要添加*@Modifying*注释：

@Modifying
    @Query(value = "update Users u set u.status = ? where u.name = ?", 
      nativeQuery = true)
    int updateUserSetStatusForNameNative(Integer status, String name);

#### **8.3. 插入** ####

要执行插入操作，我们必须应用*@Modifying*并使用本机查询[，因为 INSERT 不是 JPA 接口的一部分][INSERT _ JPA]：

@Modifying
    @Query(
      value = 
        "insert into Users (name, age, email, status) values (:name, :age, :email, :status)",
      nativeQuery = true)
    void insertUser(@Param("name") String name, @Param("age") Integer age, 
      @Param("status") Integer status, @Param("email") String email);

### **9. 动态查询** ###

通常，我们会遇到基于条件或数据集构建SQL语句的需要，这些条件或数据集的值仅在运行时才知道。在这些情况下，我们不能只使用静态查询。

#### **9.1. 动态查询示例** ####

例如，让我们想象一种情况，我们需要从运行时定义的集合中选择所有电子邮件*类似于*一个的用户 - *email1*，*email2*，...，*emailn*：

SELECT u FROM User u WHERE u.email LIKE '%email1%' 
        or  u.email LIKE '%email2%'
        ... 
        or  u.email LIKE '%emailn%'

由于集合是动态构造的，因此我们无法在编译时知道要添加多少 *LIKE* 子句。

在这种情况下，**我们不能只使用*@Query*注释，因为我们无法提供静态 SQL 语句。**

相反，通过实现自定义复合存储库，我们可以扩展基本的 *JpaRepository* 功能，并提供我们自己的逻辑来构建动态查询。让我们来看看如何做到这一点。

#### **9.2. 自定义仓库和 JPA 标准 API** ####

对我们来说幸运的是，**Spring提供了一种通过使用自定义片段接口来扩展基本存储库的方法。**然后，我们可以将它们链接在一起以创建[复合存储库][Link 1]。

我们将从创建自定义片段接口开始：

public interface UserRepositoryCustom {
        List<User> findUserByEmails(Set<String> emails);
    }

然后我们将实现它：

public class UserRepositoryCustomImpl implements UserRepositoryCustom {
    
        @PersistenceContext
        private EntityManager entityManager;
    
        @Override
        public List<User> findUserByEmails(Set<String> emails) {
            CriteriaBuilder cb = entityManager.getCriteriaBuilder();
            CriteriaQuery<User> query = cb.createQuery(User.class);
            Root<User> user = query.from(User.class);
    
            Path<String> emailPath = user.get("email");
    
            List<Predicate> predicates = new ArrayList<>();
            for (String email : emails) {
                predicates.add(cb.like(emailPath, email));
            }
            query.select(user)
                .where(cb.or(predicates.toArray(new Predicate[predicates.size()])));
    
            return entityManager.createQuery(query)
                .getResultList();
        }
    }

**如上所示，我们利用 [JPA 标准 API][JPA _ API] 来构建动态查询。**

**此外，我们需要确保在类名中包含 *Impl* 后缀。**Spring 将搜索*“用户存储库自定义”*实现为*“用户存储库自定义”。*由于片段本身不是存储库，因此Spring依靠这种机制来查找片段实现。

#### **9.3. 扩展现有仓库** ####

请注意，从第 2 节到第 7 节的所有查询方法都在*用户存储库*中。

因此，现在我们将通过在*用户存储库*中扩展新界面来集成我们的片段：

public interface UserRepository extends JpaRepository<User, Integer>, UserRepositoryCustom {
        //  query methods from section 2 - section 7
    }

#### **9.4. 使用仓库** ####

最后，我们可以调用我们的动态查询方法：

Set<String> emails = new HashSet<>();
    // filling the set with any number of items
    
    userRepository.findUserByEmails(emails);

我们已成功创建了一个复合存储库，并调用了我们的自定义方法。

### **10. 结论** ###

在本文中，我们介绍了使用*@Query*注释在Spring数据JPA存储库方法中定义查询的几种方法。

我们还学习了如何实现自定义存储库和创建动态查询。

与往常一样，本文中使用的完整代码示例可在 [GitHub 上][GitHub]找到。

[JPA]: https://www.baeldung.com/spring-data-derived-queries
[JPA _Modifying]: https://www.baeldung.com/spring-data-jpa-modifying-annotation
[INSERT _ JPA]: https://www.baeldung.com/jpa-insert
[Link 1]: https://www.baeldung.com/spring-data-composable-repositories
[JPA _ API]: https://www.baeldung.com/hibernate-criteria-queries
[GitHub]: https://github.com/eugenp/tutorials/tree/master/persistence-modules/spring-data-jpa-query-2