Hibernate自引用实体映射与父子结构查询实战指南

在构建药品分类这类具有树形结构的业务模型时，我们常常会遇到一个典型的场景：一个分组（例如MedicamentGroup）既可能包含多个子分组，同时自身也可能隶属于其他父分组。这种自引用的多对多关系，如果建模或查询不当，很容易踩坑。最常见的错误之一，就是在使用QueryDSL进行查询时，试图直接投影（select）一个@ManyToMany集合属性，结果触发令人困惑的SQL语法错误：ERROR: syntax error at or near "."。

这背后的根本原因其实很明确：QueryDSL的select()方法并不支持直接投影关联集合属性。Hibernate在尝试将集合字段映射为SQL列时，会生成非法的语句（例如SELECT ..., . as col_2_0_），从而导致数据库报错。

✅ 正确建模：精简注解与显式关联表配置

要解决这个问题，首先得从实体映射的源头入手。一个常见的误区是在双向自引用关系中都使用了@JoinTable，却没有指定mappedBy属性。这会让Hibernate误以为这是两个独立的单向关联，进而生成冗余的关联表并破坏SQL结构。

正确的做法是明确指定关系的“拥有方”和“反向方”：

@Entity
@Table(name = "medicaments_group")
@Getter @Setter
public class MedicamentGroup extends GenericDictionary {
    @Id
    private Long id;
    private boolean groupMain;

    // 主动方：此分组的直接子分组（childrens）
    @ManyToMany(fetch = FetchType.LAZY)
    @JoinTable(
        name = "medicaments_group_join",
        joinColumns = @JoinColumn(name = "medicament_group_id"),      // 当前组ID
        inverseJoinColumns = @JoinColumn(name = "medicament_join_id") // 子组ID
    )
    private List childrens = new ArrayList<>();

    // 被动方：此分组的父分组（childrenOf），由 childrens 维护，无需重复建表
    @ManyToMany(mappedBy = "childrens", fetch = FetchType.LAZY)
    private List childrenOf = new ArrayList<>();
}

⚠️ 关键说明：

• childrens是关系的拥有方（owning side），负责维护medicaments_group_join这张关联表；
• childrenOf是反向映射（inverse side），通过mappedBy = "childrens"告知Hibernate复用同一张关联表，避免了重复建表；
• 移除了cascade = CascadeType.ALL（除非业务上确实需要级联删除整个子树），这能防止意外删除父组时连带清除所有子组的风险；
• 显式声明fetch = FetchType.LAZY至关重要，它能防止无意识的即时加载（EAGER）所引发的N+1查询问题。

✅ 正确查询：避免投影集合，改用 JPQL 或 EntityGraph

既然知道了select(..., childrens)是非法操作，那么该如何安全高效地查询并加载关联的子集合呢？这里推荐两种经过验证的健壮方案。

方案一：JPQL + JOIN FETCH（推荐用于简单场景）

对于查询条件相对固定的场景，直接在Repository中使用JPQL的JOIN FETCH是最清晰直接的方式。

@Repository
public interface MedicamentGroupRepository extends JpaRepository {
    @Query("SELECT DISTINCT mg FROM MedicamentGroup mg " +
           "LEFT JOIN FETCH mg.childrens child " +
           "WHERE mg.groupMain = false")
    List findGroupsAndChildren();
}

这里有几个要点：

• 使用DISTINCT是为了消除因JOIN FETCH可能导致返回的根实体重复的问题。
• LEFT JOIN FETCH是关键，它能在同一次SQL查询中预先加载childrens集合，从而彻底规避后续遍历时触发的N+1查询。
• 查询返回的已经是childrens集合被初始化好的完整实体，无需再进行手动组装。

方案二：EntityGraph（更灵活，适合复杂条件）

当查询条件动态多变，或者你希望将加载策略与查询逻辑解耦时，EntityGraph是更优雅的选择。

// 1. 在实体类上定义图
@NamedEntityGraph(
    name = "MedicamentGroup.withChildren",
    attributeNodes = @NamedAttributeNode("childrens")
)
@Entity
@Table(name = "medicaments_group")
public class MedicamentGroup { ... }

// 2. 在查询时应用图
@EntityGraph(value = "MedicamentGroup.withChildren", type = EntityGraph.EntityGraphType.LOAD)
List groups = repository.findAll(
    Example.of(new MedicamentGroup().setGroupMain(false))
);

这种方式将“加载什么关联”的定义（EntityGraph）与“如何查询”（Example查询、QueryDSL等）分离开，代码结构更清晰，也更容易复用。

❌ 错误实践与注意事项

最后，再梳理几个需要警惕的常见陷阱：

• 绝对不要在QueryDSL或JPA Criteria API中直接select集合属性：像select(..., root.get("childrens"))这样的操作注定会失败，这是框架层面的限制。
• 勿用“删库重建”作为解决方案：有些临时性的“解决方案”会建议删除数据库再重新创建。这本质上只是掩盖了问题（比如残留的错误表结构），并非根本解决之道，在正式环境中更是危险操作。
• 警惕循环引用导致的序列化问题：如果你的实体需要通过JSON接口返回，childrens和childrenOf之间的双向引用会导致无限递归序列化。记得在其中一个集合上使用@JsonIgnore，或者使用@JsonManagedReference/@JsonBackReference注解对来妥善处理。
• 启用SQL日志进行验证：在开发阶段，强烈建议开启SQL日志来验证Hibernate生成的语句是否符合预期。在application.yml中添加如下配置：

spring:
  jpa:
    show-sql: true
    properties:
      hibernate:
        format_sql: true

这样，你就能清晰地看到生成的SQL是否正确地关联了medicaments_group_join和medicaments_group表。

遵循以上这些实践，你就能安全、高效地处理Hibernate中的自引用@ManyToMany实体，在获取带子节点的完整树形结构数据的同时，确保代码的清晰性和数据库操作的一致性。