JPA Criteria API 多级关联查询与集合条件匹配

本文详细阐述如何使用jpa criteria api进行多级路径导航，以查询关联实体集合中的特定属性。我们将通过实体间的`onetoone`和`onetomany`关系，演示如何构建`join`对象，并应用`equal`或`in`等条件，高效地检索符合复杂业务逻辑的数据。

JPA Criteria API 路径导航基础

JPA Criteria API 提供了一种类型安全且编程化的方式来构建动态查询，避免了硬编码JPQL字符串的繁琐和易错性。在处理具有复杂关联关系的实体时，路径导航（Path Navigation）是其核心功能之一。

核心概念：

• CriteriaBuilder: 用于构建查询表达式、谓词和排序等。
• CriteriaQuery: 定义查询的根、选择、条件和排序等。
• Root: 查询的起始点，代表FROM子句中的实体。
• Join: 用于表示实体之间的关联，通过Root或另一个Join对象的join()方法创建。它允许我们遍历实体图并访问关联实体的属性。

考虑以下实体结构，它代表了房产、设施和内部装饰之间的关系：

// Property Entity
class Property {
    // ... 其他属性
    @OneToOne(mappedBy = "property", cascade = CascadeType.ALL)
    @JsonManagedReference
    private Amenities amenities; // 房产与设施是一对一关系
}

// Amenities Entity
class Amenities {
    // ... 其他属性
    @OneToMany(mappedBy = "amenities", cascade = CascadeType.ALL)
    @JsonManagedReference
    private List interiors; // 设施与内部装饰是一对多关系
}

// Interiors Entity
public class Interiors { // 注意：原文拼写为 Interirios，此处修正为 Interiors
    @Id
    @GeneratedValue(strategy = GenerationType.AUTO)
    private int id;
    private String name; // 内部装饰名称，例如 "Gym", "Pool"
}

在这个结构中，Property拥有一个Amenities对象，而Amenities又包含一个Interiors对象的列表。我们的目标是查询满足Interiors列表中某个条件（例如名称）的Property。

实现多级关联查询

要从Property实体导航到Interiors实体的属性，我们需要进行两级关联：首先从Property到Amenities，然后从Amenities到Interiors。

import javax.persistence.EntityManager;
import javax.persistence.criteria.CriteriaBuilder;
import javax.persistence.criteria.CriteriaQuery;
import javax.persistence.criteria.Join;
import javax.persistence.criteria.Root;
import javax.persistence.criteria.Predicate;
import java.util.List;
import java.util.Arrays;

// 假设我们有一个EntityManager实例
// EntityManager em; 

// 1. 获取CriteriaBuilder
CriteriaBuilder cb = em.getCriteriaBuilder();

// 2. 创建CriteriaQuery，指定返回类型为Property
CriteriaQuery query = cb.createQuery(Property.class);

// 3. 定义查询的根（FROM Property）
Root propertyRoot = query.from(Property.class);

// 4. 第一级关联：从Property到Amenities
// 默认是INNER JOIN。如果需要LEFT JOIN，可以指定 JoinType.LEFT
Join amenitiesJoin = propertyRoot.join("amenities");

// 5. 第二级关联：从Amenities到Interiors
// 注意：由于interiors是List，这里join操作会为集合中的每个元素生成一个Join
Join interiorsJoin = amenitiesJoin.join("interiors");

// 现在 interiorsJoin 对象代表了每一个 Interiors 实体，我们可以对其属性进行操作

通过链式调用join()方法，我们成功地从Property导航到了Interiors。interiorsJoin现在是一个Join类型的对象，它允许我们访问Interiors实体的属性，例如name。

在关联集合中应用查询条件

在多级关联查询中，我们通常需要在最深层关联的实体上应用条件。以下是两种常见的场景。

场景一：检查关联集合中是否存在特定值

此场景旨在查找那些其关联集合（interiors）中至少有一个元素满足特定条件的实体。例如，查找所有包含名称为"Gym"的内部设施的房产。

// 构建谓词：Interiors的名称等于"Gym"
Predicate nameEqualsGym = cb.equal(interiorsJoin.get("name"), "Gym");

// 将谓词添加到查询中
query.where(nameEqualsGym);

// 执行查询
// List result = em.createQuery(query).getResultList();
// System.out.println("拥有'Gym'设施的房产数量: " + result.size());

解释：interiorsJoin.get("name") 会访问Interiors实体中的name属性。cb.equal()则构建了一个等于条件的谓词。当执行此查询时，JPA会查找所有通过amenities和interiors关联，并且interiors中至少有一个元素的name属性为"Gym"的Property。

场景二：检查关联集合中是否存在于给定列表的值 (使用IN表达式)

此场景用于查找那些其关联集合（interiors）中至少有一个元素的属性值存在于一个预定义列表中的实体。例如，查找所有包含名称为"Gym"或"Pool"的内部设施的房产。

百度智能云·曦灵

百度旗下的AI数字人平台

下载

// 定义一个包含多个值的列表
List desiredNames = Arrays.asList("Gym", "Pool", "Sauna");

// 构建谓词：Interiors的名称在desiredNames列表中
Predicate nameInList = interiorsJoin.get("name").in(desiredNames);

// 将谓词添加到查询中
query.where(nameInList);

// 执行查询
// List result = em.createQuery(query).getResultList();
// System.out.println("拥有'Gym'或'Pool'或'Sauna'设施的房产数量: " + result.size());

解释：interiorsJoin.get("name").in(desiredNames) 构建了一个IN谓词。它会检查Interiors实体的name属性是否在desiredNames列表中。

完整示例代码

下面是一个完整的JPA Criteria API查询方法示例，演示如何根据内部设施名称进行筛选：

import javax.persistence.EntityManager;
import javax.persistence.PersistenceContext;
import javax.persistence.criteria.CriteriaBuilder;
import javax.persistence.criteria.CriteriaQuery;
import javax.persistence.criteria.Join;
import javax.persistence.criteria.Root;
import javax.persistence.criteria.Predicate;
import java.util.List;
import java.util.Arrays;

public class PropertyQueryService {

    @PersistenceContext
    private EntityManager em;

    /**
     * 根据内部设施名称查询房产列表。
     * @param interiorNames 内部设施名称列表。如果为空或null，则查询所有房产。
     * @return 符合条件的房产列表。
     */
    public List findPropertiesByInteriorNames(List interiorNames) {
        CriteriaBuilder cb = em.getCriteriaBuilder();
        CriteriaQuery query = cb.createQuery(Property.class);
        Root propertyRoot = query.from(Property.class);

        // 多级关联：Property -> Amenities -> Interiors
        Join amenitiesJoin = propertyRoot.join("amenities");
        Join interiorsJoin = amenitiesJoin.join("interiors");

        // 构建谓词列表
        Predicate finalPredicate = null;

        if (interiorNames != null && !interiorNames.isEmpty()) {
            // 场景二：使用IN表达式
            finalPredicate = interiorsJoin.get("name").in(interiorNames);
        } else {
            // 场景一的简化版：如果只查询一个特定名称，例如"Gym"
            // finalPredicate = cb.equal(interiorsJoin.get("name"), "Gym");
            // 如果没有特定条件，则不添加where子句，查询所有关联的房产
            // 这里我们假设如果列表为空，则不添加名称过滤条件
        }

        if (finalPredicate != null) {
            query.where(finalPredicate);
        }

        // 避免重复数据，如果一个Property通过多个Interiors匹配条件，可能会返回多次
        // 可以通过 distinct() 来处理，但需注意可能影响性能或复杂查询结果
        query.distinct(true); 

        return em.createQuery(query).getResultList();
    }

    // 示例用法
    public static void main(String[] args) {
        // 假设em已正确初始化
        // PropertyQueryService service = new PropertyQueryService();
        // service.em = initializedEntityManager; 

        // 查找拥有"Gym"或"Pool"设施的房产
        // List gymOrPoolProperties = service.findPropertiesByInteriorNames(Arrays.asList("Gym", "Pool"));
        // System.out.println("拥有'Gym'或'Pool'设施的房产数量: " + gymOrPoolProperties.size());

        // 查找拥有"Sauna"设施的房产
        // List saunaProperties = service.findPropertiesByInteriorNames(Arrays.asList("Sauna"));
        // System.out.println("拥有'Sauna'设施的房产数量: " + saunaProperties.size());

        // 查找所有关联了内部设施的房产 (如果findPropertiesByInteriorNames方法逻辑允许)
        // List allPropertiesWithInteriors = service.findPropertiesByInteriorNames(null); 
    }
}

注意事项与最佳实践

1. JoinType的选择:

   • join()方法默认执行INNER JOIN。这意味着只有当所有关联路径上的实体都存在时，才会返回结果。
   • 如果需要包含没有关联实体的父实体，例如，想查询所有Property，即使它们没有Amenities或Interiors，则应使用LEFT JOIN：

     Join amenitiesJoin = propertyRoot.join("amenities", JoinType.LEFT);
     Join interiorsJoin = amenitiesJoin.join("interiors", JoinType.LEFT);

   • 使用LEFT JOIN时，在where子句中对子实体属性进行条件判断时，需要额外处理null值，以避免意外过滤掉父实体。

2. distinct(true):

   • 当通过OneToMany关系进行join并应用条件时，如果一个父实体有多个子实体满足条件，那么该父实体可能会在结果集中出现多次。
   • 使用query.distinct(true)可以确保返回唯一的父实体对象。

3. 性能考量:

   • 过多的join操作可能会影响查询性能。
   • 对于大型数据集，考虑是否可以使用子查询或更优化的查询策略。
   • 合理建立数据库索引对于join和where子句中的字段至关重要。

4. 类型安全:

   • Criteria API 的主要优势在于其类型安全。尽管示例中使用了字符串字面量"amenities"、"interiors"、"name"，但在实际项目中，强烈建议使用JPA元模型（Metamodel）来获取属性名，以避免运行时错误：

     // 假设你已生成了Property_, Amenities_, Interiors_ 元模型
     // Join amenitiesJoin = propertyRoot.join(Property_.amenities);
     // Join interiorsJoin = amenitiesJoin.join(Amenities_.interiors);
     // Predicate nameEqualsGym = cb.equal(interiorsJoin.get(Interiors_.name), "Gym");

     这能在编译时捕获属性名拼写错误。

5. 处理空集合:

   • 如果amenities或interiors集合可能为空，并且你使用了INNER JOIN，那么没有关联数据的Property将不会被返回。如果这是预期行为，则没有问题。否则，请考虑使用LEFT JOIN。

总结

JPA Criteria API 提供了一种强大且灵活的方式来构建复杂的数据库查询，尤其擅长处理实体间的关联关系。通过理解Root、Join以及如何构建Predicate，我们可以有效地进行多级路径导航，并在关联集合上应用各种条件，如equal和in表达式。在实际开发中，结合类型安全的元模型和对JoinType的正确选择，能够编写出健壮且易于维护的查询代码。