Spring 5 Data JPA：基于特定字面量属性的一对一映射问题

问题根源 #

报错的核心原因是@JoinFormula中错误使用了referencedColumnName属性：

@JoinFormula(value = "'Buffering'", referencedColumnName = "propertyType")

referencedColumnName的作用是指定**当前实体（UserDetails）**中与目标实体列关联的属性列，但这里我们是用固定字符串值直接匹配目标实体（UserPreference）的propertyType主键列，该属性完全多余，导致Hibernate无法找到对应映射，抛出异常。

同时，UserPreference使用复合主键（userId + propertyType）但未显式声明，也会增加Hibernate映射解析的歧义。

修复方案 #

1. 定义复合主键类 #

为UserPreference的复合主键创建显式的主键类，让Hibernate清晰识别主键结构：

import java.io.Serializable;
import lombok.Data;

@Data
public class UserPreferenceId implements Serializable {
    private String userId;
    private PropertyType propertyType;
}

2. 修正UserPreference实体 #

添加@IdClass注解指定复合主键，显式配置枚举存储类型，并调整主键赋值逻辑：

@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
@Entity
@IdClass(UserPreferenceId.class)
public class UserPreference<T> {
    @Id
    @Column(name = "user_id")
    private String userId;

    @OneToOne
    @MapsId("userId")
    @JoinColumn(name = "user_id")
    @ToString.Exclude
    private User user;

    @Id
    @Enumerated(EnumType.STRING)
    private PropertyType propertyType;

    @Convert(converter = JsonConverter.class)
    @JavaType(value = StringJavaType.class)
    private List<T> values;

    private boolean favorite;

    public UserPreference(User user, PropertyType property) {
        this.user = user;
        this.userId = user.getUserId();
        this.propertyType = property;
    }
}

3. 修正UserDetails中的映射 #

移除@JoinFormula中的referencedColumnName属性，明确关联列的映射关系：

@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
@Entity
public class UserDetails {
    @Id
    @Column(name = "user_id")
    private String userId;

    @OneToOne
    @MapsId
    @JoinColumn(name = "user_id")
    @ToString.Exclude
    private User user;

    @OneToOne(cascade = CascadeType.ALL, orphanRemoval = true)
    @JoinColumnsOrFormulas({
            @JoinColumnOrFormula(formula = @JoinFormula(value = "'Buffering'")),
            @JoinColumnOrFormula(column = @JoinColumn(name = "user_id", referencedColumnName = "user_id"))
    })
    private UserPreference<BufferMode> buffering;

    // 新增其他偏好属性示例
    @OneToOne(cascade = CascadeType.ALL, orphanRemoval = true)
    @JoinColumnsOrFormulas({
            @JoinColumnOrFormula(formula = @JoinFormula(value = "'AntiAliasing'")),
            @JoinColumnOrFormula(column = @JoinColumn(name = "user_id", referencedColumnName = "user_id"))
    })
    private UserPreference<Boolean> antiAliasing;

    public UserDetails(User user) {
        this.user = user;
        this.userId = user.getUserId();
        this.buffering = new UserPreference<>(user, PropertyType.Buffering);
        this.antiAliasing = new UserPreference<>(user, PropertyType.AntiAliasing);
    }
}

关键说明 #

• 移除referencedColumnName后，Hibernate会正确将固定值'Buffering'与UserPreference的propertyType列做匹配，完成一对一关联。
• @Enumerated(EnumType.STRING)确保数据库中存储枚举的字符串名称，与@JoinFormula中的固定值完全匹配，避免序号匹配的潜在问题。
• 显式设置userId避免依赖@MapsId的自动赋值延迟，确保实体初始化时主键字段正确赋值。

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