JPA 共享主键加 Repository 后报 does not define an IdClass

一个实体把 @OneToOne 关联直接标成 @Id，Hibernate 能建立 EntityManagerFactory；加上 JpaRepository 后，应用才在启动时失败：

IllegalArgumentException:
This class [class com.example.UserActivityStatus] does not define an IdClass

如果 Repository 写成 JpaRepository<UserActivityStatus, User>，应核对共享主键的 Java 表示。关联对象是 User，不意味着仓库主键参数也应是 User。当父实体的主键是 Long，用标量主键配合 @MapsId 可以把这层关系明确表示出来。

下面针对父表单一 Long 主键、子表的同一列同时承担主键和外键的映射。复合主键需要另按 @EmbeddedId 或 @IdClass 的规则设计，不能直接替换成一个 Long。

先确认故障发生在实体映射还是仓库初始化

例如原来的子实体片段是：

@Id
@OneToOne
@JoinColumn(name = "user_id")
private User user;

没有仓库时能够启动，只说明这一阶段的映射被提供程序接受，不能证明 Spring Data 在读取 JPA 主键元数据时会得到预期的 ID 类型。does not define an IdClass 也不是要求给所有实体随意添加一个空的 IdClass。

确认父实体 User 实际以 Long id 为主键，子表 user_id 是唯一主键并引用父表。再检查 Repository 的第二个泛型参数、持久化注解是在字段还是 getter 上，以及是否还有未展示的其他 @Id。如果堆栈最内层是 No property ... found，则是另一条派生查询解析路径，可另查仓库方法的 Java 属性名。

这类共享主键映射在 Spring Boot 4.1.1、Java 26、PostgreSQL 组合中有明确故障表现；以下处理依据派生标识规则，不把它写成某一版本才允许的数据库结构。

显式保留 userId，由关联提供它的值

子实体可以采用下面的字段映射。示例省略其他业务字段，保留无参构造；表名需与项目实际映射一致：

import jakarta.persistence.Column;
import jakarta.persistence.Entity;
import jakarta.persistence.FetchType;
import jakarta.persistence.Id;
import jakarta.persistence.JoinColumn;
import jakarta.persistence.MapsId;
import jakarta.persistence.OneToOne;
import jakarta.persistence.Table;

@Entity
@Table(name = "user_activity_status")
public class UserActivityStatus {
    @Id
    @Column(name = "user_id")
    private Long userId;

    @MapsId
    @OneToOne(fetch = FetchType.LAZY, optional = false)
    @JoinColumn(name = "user_id")
    private User user;

    protected UserActivityStatus() {
    }

    public UserActivityStatus(User user) {
        this.user = user;
    }
}

User 是工程中已有的父实体，不是新建的另一个主键类。@MapsId 在这里不带属性名，表示关联对应整个简单主键；父实体的主键类型与子实体 userId 同为 Long。

仓库同时改成标量类型：

import org.springframework.data.jpa.repository.JpaRepository;

public interface UserActivityStatusRepository
        extends JpaRepository<UserActivityStatus, Long> {
}

只改实体、不改 Repository 泛型会留下不一致。也不要给子实体 userId 再加独立的 @GeneratedValue：共享主键来自父实体身份，不能由子实体另生成一个无关编号。

保存子实体之前，必须给关联设置父实体；父实体应已处于适合当前持久化操作的状态。示例没有声明级联保存，因此不要传一个尚未持久化的父对象后假定它会自动入库。是否增加 cascade 应由业务的生命周期决定，而不是为了跳过异常。

这项修改通常不需要新增第二个数据库 ID 列。检查 ORM 生成的 SQL 和现有约束，避免 schema 自动更新意外改变生产表。先在隔离数据中验证仓库创建、保存子实体、按父 ID 查找及关联读取；不能只观察启动日志不再报错。回退代码映射时保留原始数据，已经写入或迁移的表结构应单独处理。