Spring Data JPA中@IdClass复合主键查询返回空的问题排查

问题描述 #

我正在开发一个基于Spring Boot + JPA的项目，查询一个用@IdClass定义复合主键的实体时，仓库方法返回空结果。已经确认以下内容：

• 所有导入均为正确的jakarta.persistence.*
• 仓库已正确注入到服务层
• 方法已从服务层正常调用

想确认当前配置是否正确，以及使用@IdClass配合Spring Data JPA时有哪些特定注意事项？

实体类代码 #

@Entity 
@Table(name = "entity_relation", schema = "my_schema") 
@IdClass(EntityRelationKey.class) 
public class EntityRelation {

    @Id
    private Long groupId;

    @Id
    private Integer sequenceNo;

    @ManyToOne(fetch = FetchType.EAGER)
    @JoinColumn(name = "entity_id", referencedColumnName = "id")
    private MainEntity mainEntity;
}

复合主键类代码 #

@Data 
@NoArgsConstructor 
@AllArgsConstructor 
public class EntityRelationKey implements Serializable { 
    private Long groupId; 
    private Integer sequenceNo; 
}

仓库接口代码 #

@Repository 
public interface EntityRelationRepository extends JpaRepository<EntityRelation, EntityRelationKey> {
    List<EntityRelation> findByGroupIdOrderBySequenceNoAsc(@Param("groupId") Long groupId); 
}

问题：调用List<EntityRelation> relations = entityRelationRepository.findByGroupIdOrderBySequenceNoAsc(groupId);时返回空列表。

配置检查与@IdClass使用注意事项 #

1. 当前配置的正确性 #

从代码来看，核心配置是符合要求的：

• 复合主键类EntityRelationKey实现了Serializable，具备无参/全参构造，字段名、类型和实体类的主键字段完全匹配
• 实体类正确标注@IdClass，主键字段添加@Id注解
• 仓库接口正确继承JpaRepository，泛型参数指定了实体类和对应的主键类型
• 查询方法findByGroupIdOrderBySequenceNoAsc符合Spring Data JPA的命名规则，能被正确解析

2. 返回空结果的排查方向 #

（1）数据库数据验证

直接在数据库执行原生SQL查询，确认是否存在对应groupId的记录：

SELECT * FROM my_schema.entity_relation WHERE group_id = ?;

如果SQL执行也无结果，说明数据库本身没有对应数据；如果有结果，再继续排查JPA的映射问题。

（2）字段映射匹配检查

检查数据库表entity_relation中的列名是否和实体类字段匹配：

• 实体类的groupId默认会映射到数据库的group_id（Spring Boot默认开启驼峰转下划线配置），确认数据库列名是否正确
• 确认schema = "my_schema"是否和实际使用的数据库schema一致，避免查错表

（3）参数正确性验证

检查服务层传入的groupId参数：

• 是否为null或者错误的数值
• 类型是否匹配（比如是否把字符串错误转换为Long类型）

（4）开启SQL日志查看实际执行语句

在application.yml中添加配置，开启JPA的SQL日志输出：

spring:
  jpa:
    show-sql: true
    properties:
      hibernate:
        format_sql: true

控制台会打印出生成的SQL语句，复制到数据库客户端执行，对比查询条件和预期是否一致。

3. @IdClass使用的核心注意事项 #

• 主键类必须重写equals()和hashCode()：你使用了Lombok的@Data，会自动生成这两个方法，这是JPA识别实体唯一性的关键；如果不用Lombok，必须手动实现这两个方法
• 实体类与主键类的字段必须完全匹配：字段名称、类型都要一致，不能有拼写或类型错误（比如实体类是Long groupId，主键类不能写成Long groupID）
• 查询完整实体需传入完整主键：如果要通过主键查询单个实体，必须传入完整的EntityRelationKey对象，比如entityRelationRepository.findById(new EntityRelationKey(1L, 1))
• 避免主键字段关联其他实体：复合主键字段不能是@ManyToOne或@OneToOne关联，你的代码中主键都是基础类型，符合要求

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