Spring Boot中@OneToMany关联未映射类Hibernate异常求助

我正在学习Spring Boot结合PostgreSQL开发，原本一切正常，但在现有实体中新增一对多关联后，出现Hibernate异常：

Use of @OneToMany or @ManyToMany targeting an unmapped class: com.github.hryniuklukas.Basic_WMS.model.Document.palletList[com.github.hryniuklukas.Basic_WMS.model.Pallet]

此前Pallet与PalletSpace的关联运行正常，新增Document实体后触发该异常。JPA Buddy能正确识别关联关系并展示引用树，但Spring无法启动。

Pallet实体类 #

import lombok.Getter;
import lombok.NoArgsConstructor;
import lombok.Setter;

import javax.persistence.*;
import java.time.LocalDate;

@NoArgsConstructor
@MappedSuperclass
@Entity
@Table(name = "pallet")
@Getter
@Setter
public class Pallet {
    private @Id @GeneratedValue(strategy = GenerationType.IDENTITY) Long id;
    private String palletCode;
    private LocalDate date;
    private boolean isInWarehouse;
    public Pallet(String palletCode, LocalDate date){
        this.palletCode=palletCode;
        this.date = date;
        this.isInWarehouse = true;
    }

    @ManyToOne(fetch = FetchType.LAZY)
    private PalletSpace palletSpace;
    @ManyToOne(fetch = FetchType.LAZY)
    private Document outboundDocument;
    @Override
    public boolean equals(Object o) {
        if (this == o) return true;
        if (!(o instanceof Pallet )) return false;
        return id != null && id.equals(((Pallet) o).getId());
    }
    public void setPalletStatusAsSent(){
        this.isInWarehouse = false;
    }
    @Override
    public int hashCode() {
        return getClass().hashCode();
    }
}

PalletSpace实体类 #

import lombok.Getter;
import lombok.NoArgsConstructor;
import lombok.Setter;

import javax.persistence.*;
import java.util.ArrayList;
import java.util.List;


@NoArgsConstructor
@Getter
@Setter
@Entity(name = "PalletSpace")
@Table(name = "pallet_space")
public class PalletSpace {
    private @Id @GeneratedValue (strategy = GenerationType.IDENTITY) Long id;
    private String spaceCode;

    @OneToMany(
            mappedBy = "palletSpace",
            cascade = CascadeType.ALL,
            orphanRemoval = true
    )
    private List<Pallet> palletList = new ArrayList<>();
    public PalletSpace(String spaceCode){
        this.spaceCode = spaceCode;
    }
    public void addPallet(Pallet pallet){
        palletList.add(pallet);
        pallet.setPalletSpace(this);
    }
    public void removePallet(Pallet pallet){
        palletList.remove(pallet);
        pallet.setPalletSpace(null);
    }
}

Document实体类 #

import lombok.Getter;
import lombok.NoArgsConstructor;
import lombok.Setter;
import lombok.extern.slf4j.Slf4j;

import javax.persistence.*;
import java.util.ArrayList;
import java.util.List;

@NoArgsConstructor
@Getter
@Setter
@Slf4j
@Entity
@Table(name = "document")
public class Document {
  private @Id @GeneratedValue(strategy = GenerationType.IDENTITY) Long id;

  @OneToMany(
          mappedBy = "outboundDocument",
          cascade = CascadeType.PERSIST
  )
  private List<Pallet> palletList = new ArrayList<>();


  public void addPalletToDocument(Pallet pallet) {
    palletList.add(pallet);
    pallet.setOutboundDocument(this);
  }

  public List<Pallet> getConnectedPalletList() {
    return this.palletList;
  }

  public void removePalletFromDocument(Pallet pallet) {
    palletList.remove(pallet);
    pallet.setOutboundDocument(null);
  }

  public void executeDocument() {
      palletList.forEach(Pallet::setPalletStatusAsSent);
  }
}

应用配置 #

spring.datasource.url=jdbc:postgresql://localhost:5050/postgres
spring.datasource.username=${DB_USER}
spring.datasource.password=${DB_PASS}
spring.datasource.driverClassName=org.postgresql.Driver
spring.jpa.show-sql=true
spring.jpa.hibernate.ddl-auto=update
spring.jpa.properties.hibernate.dialect = org.hibernate.dialect.PostgreSQLDialect

问题排查与解决 #

异常提示targeting an unmapped class，说明Hibernate未将Pallet识别为映射实体，核心问题出在Pallet类的注解冲突：

• Pallet同时标注了@MappedSuperclass和@Entity，这两个注解功能互斥：@MappedSuperclass用于定义可被子类继承的映射规则，本身不会被当作独立实体；@Entity则标记类为可直接映射到数据库表的实体类。同时使用会导致Hibernate无法正确识别Pallet的实体身份，进而在Document的@OneToMany关联时判定目标类未映射。

解决步骤：

1. 移除Pallet类上的@MappedSuperclass注解，仅保留@Entity即可——因为Pallet本身是需要独立映射的实体，并非作为其他实体的父类使用。
2. 重启应用，Hibernate就能正确识别Pallet实体，关联关系可正常加载。

内容的提问来源于stack exchange，提问作者Łukasz Hryniuk