JPA派生标识符映射报错：无效复合主键规范问题排查

这个错误的核心原因是你的PlayerStatId主键类的属性与对应的getter/setter方法名不匹配，导致JPA无法将主键类的字段与PlayerStat实体中的@Id关联属性正确映射。

具体问题点 #

在PlayerStat实体中，你用@Id标注了两个关联属性：score和teamMember。但在PlayerStatId类中，虽然你定义了对应的属性score（ScoreId类型）和teamMember（TeamMemberId类型），但你的getter方法却是getScoreId()和getTeamMemberId()，而不是符合JavaBean规范的getScore()和getTeamMember()。

JPA在验证复合主键映射时，会严格匹配实体类中@Id属性的名称与主键类中的属性名称（或对应的getter方法名）。名称不匹配就会触发你看到的Invalid composite primary key specification错误。

修正方案 #

修改PlayerStatId的getter/setter方法，使其与属性名保持一致：

import java.util.Objects;

public class PlayerStatId implements Serializable {
    private static final long serialVersionUID = 1L;
    private ScoreId score;
    private TeamMemberId teamMember;

    public PlayerStatId() { }

    // 修正getter/setter方法名，与属性名一致
    public ScoreId getScore() { return score; }
    public void setScore(ScoreId score) { this.score = score; }

    public TeamMemberId getTeamMember() { return teamMember; }
    public void setTeamMember(TeamMemberId teamMember) { this.teamMember = teamMember; }

    // 务必重写equals和hashCode方法（复合主键类必须实现）
    @Override
    public boolean equals(Object o) {
        if (this == o) return true;
        if (o == null || getClass() != o.getClass()) return false;
        PlayerStatId that = (PlayerStatId) o;
        return Objects.equals(score, that.score) && Objects.equals(teamMember, that.teamMember);
    }

    @Override
    public int hashCode() {
        return Objects.hash(score, teamMember);
    }
}

额外注意事项 #

1. 确保你的所有复合主键类（ScoreId、TeamMemberId、PlayerStatId）都正确重写了equals()和hashCode()方法——这是JPA处理复合主键的强制要求，否则会导致实体识别、缓存等异常问题。
2. 你的PlayerStat实体中的@Id关联映射（@ManyToOne+多@JoinColumn）是完全符合派生标识符规则的，不需要调整。

这不是EclipseLink或WildFly的Bug，只是映射时没有严格遵循JPA对@IdClass的命名匹配要求。修正方法名后，你的应用部署应该就能正常启动了。

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