解决Hibernate映射异常：外键列数与引用主键列数不匹配

问题场景 #

定义User实体类时，尝试通过@ElementCollection注解映射Map<String, Preference>类型的preferences字段，关联preferences表；同时Preference类被定义为拥有独立主键preferenceId、@ManyToOne关联User，以及name和val字段的实体类。运行时抛出以下异常：

org.hibernate.MappingException: Foreign key (FK7ar0ym10trw4wvrrermbpcm2l:preferences [preferences_PREFERENCES_ID])) must have same number of columns as the referenced primary key (preferences [user_id,NAME])
    at org.hibernate.mapping.ForeignKey.alignColumns(ForeignKey.java:148)
    at org.hibernate.mapping.ForeignKey.alignColumns(ForeignKey.java:130)
    at org.hibernate.boot.internal.InFlightMetadataCollectorImpl.secondPassCompileForeignKeys(InFlightMetadataCollectorImpl.java:1914)

相关代码 #

User类

@Entity
@Table(name = "user")
public class User extends HibernatePersistentObject implements Serializable

User类中preferences字段

@ElementCollection(fetch = FetchType.EAGER)
@CollectionTable(name = "preferences", joinColumns = @JoinColumn(name = "user_id"))
@MapKeyColumn(name = "NAME")
@Column(name = "VAL")
private Map<String, Preference> preferences;

Preference类

@Id
@GeneratedValue(strategy = GenerationType.SEQUENCE, generator = "preferences_seq")
@SequenceGenerator(name = "preferences_seq", sequenceName = "preferences_seq", allocationSize = 1)
@Column(name = "PREFERENCES_ID")
private int preferenceId;

@ManyToOne(fetch = FetchType.EAGER)
@JoinColumn(name = "user_id")
private User user;

@Column(name = "NAME")
private String name;

@Column(name = "VAL")
private String val;

错误原因 #

核心冲突是混用了@ElementCollection注解与独立实体类：

• @ElementCollection的设计目标是映射值类型集合（比如String、无主键的自定义值对象），Hibernate处理该注解时，会自动将关联表（preferences）的主键设为user_id + @MapKeyColumn指定的字段（NAME）的复合主键，以此关联主实体User。
• 但你将Preference定义为拥有独立主键preferenceId的实体类，还通过@ManyToOne建立了与User的外键关联，这导致Hibernate同时收到两种映射规则：
  1. 来自@ElementCollection的规则：preferences表用user_id+NAME复合主键关联User；
  2. 来自Preference实体的规则：preferences表用preferenceId作为主键，通过user_id外键关联User。
     两种规则的主键定义不匹配，最终触发“外键列数与引用主键列数不匹配”的异常。

修复方案 #

根据业务需求选择以下两种方案之一：

方案一：将Preference改为值对象（保留@ElementCollection） #

如果Preference不需要作为独立实体被其他类引用，仅作为User的附属数据集合，可将其改为值对象：

1. 修改Preference类，去掉@Entity注解、独立主键和@ManyToOne关联：

// 无需@Entity、主键及关联注解，仅保留业务属性
public class Preference implements Serializable {
    private String name;
    private String val;

    // 构造方法、getter/setter
}

2. 调整User类中preferences字段的注解，用值对象的name属性作为Map的key，并映射对应表字段：

@ElementCollection(fetch = FetchType.EAGER)
@CollectionTable(name = "preferences", joinColumns = @JoinColumn(name = "user_id"))
@MapKey(name = "name") // 基于值对象的name属性作为Map的key
@AttributeOverrides({
    @AttributeOverride(name = "name", column = @Column(name = "NAME")),
    @AttributeOverride(name = "val", column = @Column(name = "VAL"))
})
private Map<String, Preference> preferences;

方案二：改用@OneToMany关联（保留Preference作为独立实体） #

如果Preference需要作为独立实体（比如要被其他实体引用、需独立业务逻辑），则替换@ElementCollection为@OneToMany关联：

1. 修改User类的preferences字段，使用@OneToMany并指定映射关系：

@OneToMany(mappedBy = "user", fetch = FetchType.EAGER, cascade = CascadeType.ALL)
@MapKey(name = "name") // 基于Preference实体的name属性作为Map的key
private Map<String, Preference> preferences;

2. 完善Preference类，添加@Entity注解并确保关联字段配置正确：

@Entity
@Table(name = "preferences")
public class Preference implements Serializable {
    @Id
    @GeneratedValue(strategy = GenerationType.SEQUENCE, generator = "preferences_seq")
    @SequenceGenerator(name = "preferences_seq", sequenceName = "preferences_seq", allocationSize = 1)
    @Column(name = "PREFERENCES_ID")
    private int preferenceId;

    @ManyToOne(fetch = FetchType.EAGER)
    @JoinColumn(name = "user_id", nullable = false)
    private User user;

    @Column(name = "NAME")
    private String name;

    @Column(name = "VAL")
    private String val;

    // getter/setter，需包含setUser方法以维护双向关联
}

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