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<Professor> findAllByKeyword(@Param("stichpunkt") Stichpunkt stichpunkt);该查询抛出QueryCreationException的根本原因在于其JPQL语法错误。JPQL是面向对象的查询语言，它操作的是实体（Entities）及其属性（Attributes），而非底层的数据库表和列名。在JPQL中，如果需要关联不同的实体，必须通过JOIN语句来明确导航实体之间的关系。
原始查询的错误点在于：
- 直接在WHERE子句中引用了数据库表名（professor_hat_stichpunkt，stichpunkt）和列名（id_professor，id_stichpunkt），而没有通过JOIN语句引入这些实体别名。
- p.id_professor这种写法在JPQL中也是不规范的，p是Professor实体的一个别名，应直接使用实体属性，如p.id（如果id是主键属性）。
- 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查询提供了一个很好的参考：
@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<Supervisor> findAllByKeyword(@Param("keyword")Keyword keyword);这个示例查询展示了如何正确使用JOIN语句来关联实体，并且通过OR条件同时考虑了两种可能的关联路径：
- s.keyword = :keyword：Supervisor实体直接通过keyword属性关联Keyword实体（多对一）。
- 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<Professor, Integer> {
/**
* 根据给定的关键词（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<Professor> findAllByKeyword(@Param("stichpunkt") Stichpunkt stichpunkt);
}代码解析：
- SELECT DISTINCT p FROM Professor p: 声明我们要选择Professor实体，并为其指定别名p。DISTINCT用于确保返回的教授列表不包含重复项。
-
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。
-
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会自动根据实体的主键进行比较，这是推荐的写法。
- 这是查询的核心逻辑，它结合了两种关联方式：
- 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<Professor> findAllByKeyword(@Param("stichpunkt") Stichpunkt stichpunkt);此查询使用INNER JOIN，因为它要求Professor必须在ProfessorHatStichpunkt中有对应的Stichpunkt关联。
关键概念与注意事项
JPQL 与 SQL 的区别
- JPQL (Java Persistence Query Language)：是面向对象的查询语言，操作的是实体对象和它们的属性，而不是数据库表和列。它通过实体关系来导航数据。
