如何使用Spring Data JPA处理复合主键的查询与最佳实践？

在关系型数据库设计中，当单一字段无法唯一标识一行记录时，就需要使用复合主键。Spring Data JPA提供了成熟且灵活的机制来支持复合主键的映射与查询，开发者可以根据业务复杂度选择不同的实现方式。

复合主键的两种定义方式

使用IdClass

IdClass方式要求先定义一个主键类，该类的字段名和类型必须与实体中对应字段一致，并且实现序列化与equals、hashCode方法。

// 主键类
public class OrderItemPK implements java.io.Serializable {
    private Long orderId;
    private Long productId;

    public OrderItemPK() {}

    public OrderItemPK(Long orderId, Long productId) {
        this.orderId = orderId;
        this.productId = productId;
    }

    // 省略 getter、setter、equals、hashCode
}

// 实体类
@Entity
@IdClass(OrderItemPK.class)
public class OrderItem {
    @Id
    private Long orderId;
    @Id
    private Long productId;
    private Integer quantity;

    // 省略 getter、setter
}

使用EmbeddedId

EmbeddedId将主键类作为实体的一个嵌入属性，结构更清晰，也更容易传递主键值。

@Embeddable
public class OrderItemPK implements java.io.Serializable {
    private Long orderId;
    private Long productId;

    // 省略构造方法、getter、setter、equals、hashCode
}

@Entity
public class OrderItem {
    @EmbeddedId
    private OrderItemPK id;
    private Integer quantity;

    // 省略 getter、setter
}

复合主键的查询策略

方法名派生查询

使用IdClass时，可以在Repository中通过主键字段名直接派生查询方法。

public interface OrderItemRepository extends JpaRepository<OrderItem, OrderItemPK> {
    List<OrderItem> findByOrderId(Long orderId);
    List<OrderItem> findByOrderIdAndProductId(Long orderId, Long productId);
}

使用EmbeddedId时，需要通过嵌入属性路径编写方法名。

public interface OrderItemRepository extends JpaRepository<OrderItem, OrderItemPK> {
    List<OrderItem> findByIdOrderId(Long orderId);
    List<OrderItem> findByIdOrderIdAndIdProductId(Long orderId, Long productId);
}

使用@Query注解

对于复杂条件，可以使用JPQL显式指定复合主键的字段。

public interface OrderItemRepository extends JpaRepository<OrderItem, OrderItemPK> {
    @Query("select o from OrderItem o where o.id.orderId = :oid and o.quantity > :q")
    List<OrderItem> findLargeQuantity(@Param("oid") Long orderId, @Param("q") Integer q);
}

最佳实践建议

• 优先使用EmbeddedId，使主键语义更明确，便于在业务代码中传递。
• 复合主键的字段顺序应与数据库索引顺序一致，避免查询时索引失效。
• 对高频查询字段建立联合索引，提升Spring Data JPA生成SQL的执行效率。
• 在涉及复合主键的批量更新中，注意事务边界，防止部分写失败导致数据不一致。

复合主键虽能准确表达业务约束，但也会增加查询与关联复杂度，应在确有必要时才使用。

小结

Spring Data JPA通过IdClass与EmbeddedId完整支持复合主键场景，配合方法名查询与@Query可覆盖绝大多数数据访问需求。合理设计主键结构并遵循索引与事务实践，可让复合主键查询既安全又高效。

Spring_Data_JPA复合主键查询策略修改时间：2026-07-26 07:03:10