多关联属性匹配的User记录JPQL查询语法错误排查

问题根源 #

你遇到的BadJpqlGrammarException是因为JPQL中JOIN的语法位置错误——JOIN必须紧跟在主实体的关联属性之后，或通过ON子句与主实体关联，不能随意放置。同时直接JOIN两个一对多关联会产生笛卡尔积，导致重复的User记录，也不符合可选条件的查询需求。

实体类参考（简化版） #

@Entity
public class User {
    @Id
    private Long id;
    @OneToMany(mappedBy = "user", fetch = FetchType.LAZY)
    private List<EmailData> emails;
    @OneToMany(mappedBy = "user", fetch = FetchType.LAZY)
    private List<PhoneData> phones;
    // getter/setter 省略
}

@Entity
public class EmailData {
    @Id
    private Long id;
    @ManyToOne(fetch = FetchType.LAZY)
    private User user;
    private String email;
    // getter/setter 省略
}

@Entity
public class PhoneData {
    @Id
    private Long id;
    @ManyToOne(fetch = FetchType.LAZY)
    private User user;
    private String phone;
    // getter/setter 省略
}

正确实现方案 #

方案1：使用EXISTS子查询（推荐，无笛卡尔积） #

通过EXISTS子查询分别检查是否存在匹配的EmailData/PhoneData，既避免笛卡尔积，又高效支持可选条件：

public interface UserRepository extends JpaRepository<User, Long> {
    @Query("""
        SELECT u FROM User u
        WHERE (:email IS NULL OR EXISTS (SELECT e FROM EmailData e WHERE e.user = u AND e.email = :email))
        AND (:phone IS NULL OR EXISTS (SELECT p FROM PhoneData p WHERE p.user = u AND p.phone = :phone))
        """)
    List<User> findByOptionalEmailAndPhone(@Param("email") String email, @Param("phone") String phone);
}

方案2：LEFT JOIN + DISTINCT（备选，需去重） #

如果偏好JOIN写法，可通过LEFT JOIN结合DISTINCT去重，但性能略逊于EXISTS：

public interface UserRepository extends JpaRepository<User, Long> {
    @Query("""
        SELECT DISTINCT u FROM User u
        LEFT JOIN u.emails e
        LEFT JOIN u.phones p
        WHERE (:email IS NULL OR e.email = :email)
        AND (:phone IS NULL OR p.phone = :phone)
        """)
    List<User> findByOptionalEmailAndPhone(@Param("email") String email, @Param("phone") String phone);
}

关键说明 #

• 可选条件处理：通过:param IS NULL OR ...实现动态匹配——当参数为null时，该条件自动失效，满足仅传邮箱/手机号的需求。
• 避免笛卡尔积：EXISTS子查询只做存在性检查，不会生成关联表的笛卡尔积；而JOIN写法必须加DISTINCT去重，否则一个User对应多个Email/Phone时会返回重复记录。
• JPQL语法规范：JOIN必须关联主实体的关联属性（如u.emails），或通过ON子句明确关联关系，不能孤立使用JOIN。

内容的提问来源于stack exchange，提问作者Sergey Zolotarev