Spring Data JPA 查询异常排查与实体关系映射实践

spring data jpa作为spring生态中简化数据访问层的强大工具，极大地提高了开发效率。然而，在使用其自定义查询功能（如`@query`注解）时，开发者常会遇到因jpql（java persistence query language）语法不当或实体关系映射理解偏差而导致的运行时异常，例如`querycreationexception`。这类异常通常发生在应用启动阶段，表明spring无法解析或验证jpql查询语句，而非查询执行时的数据错误。

问题诊断：JPQL 语法错误与实体关系误解

本节将深入分析一个典型的JPQL查询失败案例，并探讨其背后的原因，主要集中在JPQL语法与实体关系映射的正确使用上。

原始查询的问题分析

提供的原始JPQL查询如下：

@Query("SELECT DISTINCT p FROM Professor p " +
        "WHERE p.id_professor = professor_hat_stichpunkt.id_professor " +
        "AND professor_hat_stichpunkt.id_stichpunkt = stichpunkt.id_stichpunkt " +
        "AND stichpunkt.id_stichpunkt = :stichpunkt" +
        "ORDER BY p.nachname")
List findAllByKeyword(@Param("stichpunkt") Stichpunkt stichpunkt);

该查询抛出QueryCreationException的根本原因在于其JPQL语法错误。JPQL是面向对象的查询语言，它操作的是实体（Entities）及其属性（Attributes），而非底层的数据库表和列名。在JPQL中，如果需要关联不同的实体，必须通过JOIN语句来明确导航实体之间的关系。

原始查询的错误点在于：

1. 直接在WHERE子句中引用了数据库表名（professor_hat_stichpunkt，stichpunkt）和列名（id_professor，id_stichpunkt），而没有通过JOIN语句引入这些实体别名。
2. p.id_professor这种写法在JPQL中也是不规范的，p是Professor实体的一个别名，应直接使用实体属性，如p.id（如果id是主键属性）。
3. stichpunkt.id_stichpunkt = :stichpunkt：如果:stichpunkt是一个Stichpunkt实体对象，那么正确的比较方式应该是s = :stichpunkt（直接比较实体）或s.id = :stichpunkt.id（比较实体ID）。

实体模型分析

为了正确构建JPQL查询，理解实体之间的关系至关重要。

我们有三个核心实体：

• Professor：代表教授。
  • @Id id_professor (映射到 id)
  • 包含一个直接的多对一关系：@ManyToOne(targetEntity = Stichpunkt.class, optional = false) @JoinColumn(name = "id_stichpunkt", referencedColumnName = "id_stichpunkt", nullable = false) private Stichpunkt stichpunkt; 这意味着每个Professor必须关联一个Stichpunkt。
• Stichpunkt：代表关键词。
  • @Id id_stichpunkt (映射到 id)
• ProfessorHatStichpunkt：这是一个用于表示Professor和Stichpunkt之间多对多关系的连接实体。
  • 使用@EmbeddedId来定义复合主键Id，其中包含Professor professor和Stichpunkt stichpunkt的引用。

值得注意的是，Professor实体中既有直接的ManyToOne到Stichpunkt的映射，又存在一个独立的ProfessorHatStichpunkt实体来处理多对多关系。这可能表示两种不同的关联方式，或者其中一个映射是冗余的。在实际项目中，需要根据业务需求明确其意图。

与示例项目的对比分析

示例项目中的SupervisorRepository查询提供了一个很好的参考：

炉米Lumi

字节跳动推出的AI模型分享社区和模型训练平台

下载

@Query("SELECT DISTINCT s FROM Supervisor s " +
        "INNER JOIN SupervisorHasKeyword shk ON shk.id.supervisor = s " +
        "WHERE s.keyword = :keyword " +
        "OR shk.id.keyword = :keyword " +
        "ORDER BY s.name")
List findAllByKeyword(@Param("keyword")Keyword keyword);

这个示例查询展示了如何正确使用JOIN语句来关联实体，并且通过OR条件同时考虑了两种可能的关联路径：

1. s.keyword = :keyword：Supervisor实体直接通过keyword属性关联Keyword实体（多对一）。
2. shk.id.keyword = :keyword：Supervisor实体通过SupervisorHasKeyword连接实体（多对多）关联Keyword实体。

这种模式与当前项目中的Professor和Stichpunkt的映射情况非常相似，即Professor也存在一个直接的stichpunkt属性，并且有一个ProfessorHatStichpunkt连接实体。

修正 JPQL 查询：构建正确的实体关联

基于对实体模型和示例查询的理解，我们可以构建一个正确的JPQL查询来查找与给定Stichpunkt关联的Professor。我们将采纳与示例项目相似的逻辑，同时考虑Professor与Stichpunkt的两种关联方式。

采用多对多与直接多对一组合查询

考虑到Professor实体中存在一个直接的stichpunkt属性（多对一关系），并且ProfessorHatStichpunkt实体用于表示多对多关系，最全面的查询方式是同时考虑这两种关联。

import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.data.jpa.repository.Query;
import org.springframework.data.repository.query.Param;
import java.util.List;

// 假设ProfessorRepository接口
public interface ProfessorRepository extends JpaRepository {

    /**
     * 根据给定的关键词（Stichpunkt）查找所有相关的教授。
     * 查询会考虑两种关联方式：
     * 1. 教授直接关联的关键词（通过Professor.stichpunkt属性）。
     * 2. 教授通过ProfessorHatStichpunkt连接实体关联的关键词（多对多关系）。
     *
     * @param stichpunkt 要查找的关键词实体
     * @return 匹配的教授列表
     */
    @Query("SELECT DISTINCT p FROM Professor p " +
           "LEFT JOIN ProfessorHatStichpunkt phs ON phs.id.professor = p " +
           "WHERE p.stichpunkt = :stichpunkt " + // 教授直接关联的关键词
           "OR phs.id.stichpunkt = :stichpunkt " + // 通过多对多连接实体关联的关键词
           "ORDER BY p.nachname")
    List findAllByKeyword(@Param("stichpunkt") Stichpunkt stichpunkt);
}

代码解析：

1. SELECT DISTINCT p FROM Professor p: 声明我们要选择Professor实体，并为其指定别名p。DISTINCT用于确保返回的教授列表不包含重复项。
2. LEFT JOIN ProfessorHatStichpunkt phs ON phs.id.professor = p:
   • 使用LEFT JOIN而不是INNER JOIN。这是因为一个Professor可能只通过其stichpunkt属性直接关联一个Stichpunkt，而没有在ProfessorHatStichpunkt表中对应的记录。LEFT JOIN会保留所有Professor记录，即使它们在ProfessorHatStichpunkt中没有匹配项。
   • ProfessorHatStichpunkt是连接实体，别名为phs。
   • ON phs.id.professor = p：这是正确的JOIN条件，它通过ProfessorHatStichpunkt复合主键id中的professor属性来关联Professor实体p。
3. WHERE p.stichpunkt = :stichpunkt OR phs.id.stichpunkt = :stichpunkt:
   • 这是查询的核心逻辑，它结合了两种关联方式：
     • p.stichpunkt = :stichpunkt：检查Professor实体自身的stichpunkt属性是否与传入的:stichpunkt参数匹配。
     • phs.id.stichpunkt = :stichpunkt：检查通过ProfessorHatStichpunkt连接实体关联的Stichpunkt是否与传入的:stichpunkt参数匹配。
   • OR操作符使得只要满足其中一个条件，该教授就会被选中。
   • = :stichpunkt：当:stichpunkt参数是一个Stichpunkt实体对象时，JPQL会自动根据实体的主键进行比较，这是推荐的写法。
4. ORDER BY p.nachname: 按教授的姓氏排序结果。

仅通过多对多关联查询（如果直接ManyToOne是冗余的）

如果业务上明确Professor和Stichpunkt的关系仅通过ProfessorHatStichpunkt实体来维护，那么Professor类中的@ManyToOne private Stichpunkt stichpunkt;映射应该是被移除或修改的。在这种情况下，查询会更简洁：

// 如果Professor类中的stichpunkt属性被移除或不用于此查询
@Query("SELECT DISTINCT p FROM Professor p " +
       "JOIN ProfessorHatStichpunkt phs ON phs.id.professor = p " +
       "WHERE phs.id.stichpunkt = :stichpunkt " +
       "ORDER BY p.nachname")
List findAllByKeyword(@Param("stichpunkt") Stichpunkt stichpunkt);

此查询使用INNER JOIN，因为它要求Professor必须在ProfessorHatStichpunkt中有对应的Stichpunkt关联。

关键概念与注意事项

JPQL 与 SQL 的区别

• JPQL (Java Persistence Query Language)：是面向对象的查询语言，操作的是实体对象和它们的属性，而不是数据库表和列。它通过实体关系来导航数据。