SpringBoot+JPA复合主键映射报错：@MapsId隐式列引用失败

问题场景 #

使用JPA、Hibernate和SpringBoot映射Microsoft SQL Server的关联表，该表复合主键包含一个普通数值字段和两个指向其他表的外键。创建了标注@Embeddable的主键类RoleIdEntity，在实体类RoleEntity中用@EmbeddedId关联，但启动应用时抛出异常：

Implicit column reference in the @MapsId mapping fails, try to use explicit referenceColumnNames

错误原因 #

Hibernate不允许在@Embeddable嵌入主键类中直接用@ManyToOne关联其他实体作为主键字段。嵌入主键的字段必须是基本数据类型或可嵌入类型，直接关联实体会导致Hibernate无法正确解析外键列的映射关系，触发上述异常。

解决步骤 #

1. 修改嵌入主键类RoleIdEntity #

将原有的@ManyToOne关联实体替换为对应实体的主键类型，仅保留列映射注解，去掉关联相关的注解：

import lombok.AllArgsConstructor;
import lombok.Builder;
import lombok.EqualsAndHashCode;
import lombok.NoArgsConstructor;

import javax.persistence.Column;
import javax.persistence.Embeddable;
import java.io.Serializable;
import java.math.BigDecimal;

@Builder
@AllArgsConstructor
@NoArgsConstructor
@EqualsAndHashCode
@Embeddable
public class RoleIdEntity implements Serializable {

    @Column(name = "IDEPRF")
    private BigDecimal ideprf; // 普通数值主键

    @Column(name = "CODVEO")
    private String codveo; // 对应MuseumEntity的主键类型（根据实际实体调整）

    @Column(name = "CODSBE")
    private String codsbe; // 对应RegisterEntity的主键类型（根据实际实体调整）
}

2. 修改主实体类RoleEntity #

添加单独的@ManyToOne关联，并通过@MapsId显式指定关联实体的主键对应嵌入主键中的字段名，同时指定外键列：

import lombok.AllArgsConstructor;
import lombok.Builder;
import lombok.Data;
import lombok.NoArgsConstructor;

import javax.persistence.*;
import java.math.BigDecimal;
import java.sql.Timestamp;

@Data
@Builder
@AllArgsConstructor
@NoArgsConstructor
@Entity
@Table(name = "DPRF", schema = "dbo")
public class RoleEntity {

    @EmbeddedId
    private RoleIdEntity id;

    // 关联MuseumEntity，@MapsId指定对应主键类中的codveo字段
    @ManyToOne
    @MapsId("codveo")
    @JoinColumn(name = "CODVEO", referencedColumnName = "CODVEO")
    private MuseumEntity museum;

    // 关联RegisterEntity，@MapsId指定对应主键类中的codsbe字段
    @ManyToOne
    @MapsId("codsbe")
    @JoinColumn(name = "CODSBE", referencedColumnName = "CODSBE")
    private RegisterEntity register;

    @Column(name="DESPROFILI",length = 40)
    private String desprofili;

    @Column(name="DATFINVALPRF")
    private Timestamp datfinvalprf;

    @Column(name="INDAMM")
    private String indamm;

    @Column(name="INDVSZ")
    private String indvsz;

    @Column(name="CODPEN")
    private String codpen;

    @Column(name="DATULTMOD")
    private Timestamp datultmod;

    @Column(name="OPAULTMOD",length = 40)
    private String opaultmod;

    @Column(name="PTN",length = 40)
    private String ptnultmod;

    @Column(name="IDETIPPRFVDA",length = 38)
    private BigDecimal idetipprfvda;

    @Column(name="FLGASSFUN",length = 1)
    private String flgassfun;

    @Column(name="FLGASSOPA",length = 1)
    private String flgassopa;

    @Column(name="FLGMOD", length = 1)
    private String flgmod;

    @Column(name="IDEMLO")
    private BigDecimal idemlo;

    @Column(name="FLGBSE")
    private String flgbse;
}

关键修改说明 #

• 嵌入主键类仅存储基本类型的主键值，符合JPA对可嵌入主键的要求。
• 主实体中通过@MapsId("字段名")将关联实体的主键值映射到嵌入主键的对应字段，显式建立外键与主键字段的关联，解决Hibernate隐式映射失败的问题。
• 注意：codveo和codsbe的类型需要与MuseumEntity、RegisterEntity的主键类型保持一致，根据实际实体调整。

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