Spring Data JPA 复合主键查询与最佳实践指南

顺亿

2026-09-14 • 👁 0人浏览过

本教程详细阐述了如何在spring data jpa中有效处理复合主键查询。文章首先指出`jparepository`对单一id类型的限制，进而提供了三种核心解决方案：直接使用`embeddedid`类型进行`findbyid`查询、利用spring data jpa的派生查询方法，以及通过`@query`注解自定义jpql查询。此外，教程还强调了使用现代日期时间api（如`localdate`）和健壮的`optional`处理机制（特别是结合自定义异常实现优雅的错误管理）等最佳实践。 Spring Data JPA 复合主键查询策略在Spring Data JPA应用中，处理具有复合主键的实体是常见需求。然而，JpaRepository的findById()方法默认只接受一个单一类型的ID参数，这使得直接使用多个字段进行复合主键查询变得不直观。本文将深入探讨如何在Spring Data JPA中优雅地实现复合主键查询，并提供相关的最佳实践。 1. 理解复合主键的定义首先，我们需要正确定义复合主键。Spring Data JPA通常通过@Embeddable注解的类结合@EmbeddedId注解在实体中使用。以下是一个复合主键PlansPKId和使用它的Plans实体的示例：

import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;
import lombok.EqualsAndHashCode;
import javax.persistence.Embeddable;
import java.io.Serializable;
import java.util.Date; // 注意：推荐使用java.time.* 包下的日期类型

@Data
@AllArgsConstructor
@NoArgsConstructor
@EqualsAndHashCode
@Embeddable
public class PlansPKId implements Serializable {
    private long planId;
    private Date planDate; // 格式: yyyy-mm-dd
}

import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;
import javax.persistence.*;
import java.util.HashSet;
import java.util.Set;

@Data
@AllArgsConstructor
@NoArgsConstructor
@Entity
@Table(name = "plans")
public class Plans {
    @EmbeddedId
    private PlansPKId plansPKId;

    @Column
    private String planName;

    @Column
    private String weekday;

    @ManyToMany
    @JoinTable(name = "Plan_Meds", joinColumns = {
            @JoinColumn(name = "planDate", referencedColumnName = "planDate"),
            @JoinColumn(name = "planId", referencedColumnName = "planId") }, inverseJoinColumns = @JoinColumn(name = "planId")) // 修正：这里inverseJoinColumns应该是Meds的id
    private Set assignedMeds = new HashSet<>();
}

2. 使用EmbeddedId类型进行findById查询 JpaRepository接口的第二个泛型参数指定了实体的主键类型。对于复合主键，这个类型应该就是我们定义的@Embeddable类。步骤： Eclipse导入Android或其他的JAVA项目的正确方法 WORD版本文档主要讲述的是Eclipse导入Android或其他的JAVA项目的正确方法；希望本文档会给有需要的朋友带来帮助；感兴趣的朋友可以过来看看下载定义Repository接口：将PlansPKId作为JpaRepository的ID类型。

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

@Repository
public interface PlansRepository extends JpaRepository {
}

调用findById方法：在查询时，需要创建一个PlansPKId的实例作为参数传递给findById。

import java.util.Date; // 假设传入的planDate是java.util.Date类型
import java.util.Optional;

// ... 在某个服务类中
public Plans findPlanByCompositeKey(long planId, Date planDate) {
    PlansPKId compositeId = new PlansPKId(planId, planDate);
    Optional optionalPlans = plansRepo.findById(compositeId);
    // 推荐使用orElseThrow进行健壮的Optional处理
    return optionalPlans.orElseThrow(() -> new RuntimeException("Plan not found with id " + planId + " and date " + planDate));
}

3. 利用派生查询方法 Spring Data JPA能够根据方法名自动生成查询。对于复合主键，可以通过引用EmbeddedId类的字段来构建查询方法。步骤：定义派生查询方法：方法名遵循findBy + EmbeddedId属性名 + EmbeddedId属性内的字段名的模式。

import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.stereotype.Repository;
import java.util.Date;
import java.util.Optional;

@Repository
public interface PlansRepository extends JpaRepository {
    // 根据复合主键的planId和planDate字段查找
    Optional findByPlansPKIdPlanIdAndPlansPKIdPlanDate(long planId, Date planDate);
}

调用方法：

import java.util.Date;
import java.util.Optional;

// ... 在某个服务类中
public Plans findPlanByDerivedQuery(long planId, Date planDate) {
    Optional optionalPlans = plansRepo.findByPlansPKIdPlanIdAndPlansPKIdPlanDate(planId, planDate);
    return optionalPlans.orElseThrow(() -> new RuntimeException("Plan not found with id " + planId + " and date " + planDate));
}

这种方法的缺点是当复合主键字段较多时，方法名可能会变得非常冗长。 4. 使用自定义JPQL查询如果派生查询方法名过长或需要更复杂的查询逻辑，可以使用@Query注解定义JPQL（Java Persistence Query Language）查询。步骤：定义自定义查询方法：使用@Query注解编写JPQL，并通过@Param注解将方法参数绑定到查询中的命名参数。

import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.data.jpa.repository.Query;
import org.springframework.data.repository.query.Param;
import org.springframework.stereotype.Repository;
import java.util.Date;
import java.util.Optional;

@Repository
public interface PlansRepository extends JpaRepository {
    @Query("select p from Plans p where p.plansPKId.planId = :planId and p.plansPKId.planDate = :planDate")
    Optional findByCompositeId(@Param("planId") long planId, @Param("planDate") Date planDate);
}

调用方法：

import java.util.Date;
import java.util.Optional;

// ... 在某个服务类中
public Plans findPlanByCustomQuery(long planId, Date planDate) {
    Optional optionalPlans = plansRepo.findByCompositeId(planId, planDate);
    return optionalPlans.orElseThrow(() -> new RuntimeException("Plan not found with id " + planId + " and date " + planDate));
}

这种方法提供了最大的灵活性，并且可以使方法名更具可读性。 5. 最佳实践与注意事项 5.1 现代化日期时间API 强烈建议使用 java .time包下的日期时间API（如LocalDate, LocalDateTime, ZonedDateTime）代替传统的java.util.Date。java.time提供了更好的线程安全性、不变性、清晰的语义和更强大的功能。示例：将PlansPKId中的Date替换为LocalDate

import java.time.LocalDate; // 导入LocalDate

@Data
@AllArgsConstructor
@NoArgsConstructor
@EqualsAndHashCode
@Embeddable
public class PlansPKId implements Serializable {
    private long planId;
    private LocalDate planDate; // 使用LocalDate
}

5.2 健壮的Optional处理与优雅的异常管理直接调用Optional.get()而不检查其是否存在是非常危险的，可能导致NoSuchElementException。推荐使用orElseThrow()结合自定义异常来提供更清晰、更友好的错误信息和HTTP 状态码。实现步骤：定义一个抽象的NotFoundException基类：

import java.util.Map;
import java.util.stream.Collectors;

public abstract class NotFoundException extends RuntimeException {

    protected NotFoundException(final String object, final String identifierName, final Object identifier) {
        super(String.format("No %s found with %s %s", object, identifierName, identifier));
    }

    protected NotFoundException(final String object, final Map identifiers) {
        super(String.format("No %s found with %s", object,
                identifiers.entrySet().stream()
                        .map(entry -> String.format("%s %s", entry.getKey(), entry.getValue()))
                        .collect(Collectors.joining(" and "))));
    }
}

为特定实体创建具体的NotFoundException子类：

import java.util.Map;
import java.util.function.Supplier;

public class PlansNotFoundException extends NotFoundException {

    private PlansNotFoundException(final Map identifiers) {
        super("plans", identifiers);
    }

    public static Supplier idAndDate(final long planId, final Date planDate) {
        // 注意：如果使用LocalDate，这里也应传入LocalDate
        return () -> new PlansNotFoundException(Map.of("id", planId, "date", planDate));
    }
}

public class MedsNotFoundException extends NotFoundException {

    private MedsNotFoundException(final String identifierName, final Object identifier) {
        super("meds", identifierName, identifier);
    }

    public static Supplier id(final long id) {
        return () -> new MedsNotFoundException("id", id);
    }
}

在服务层中使用orElseThrow ：

import java.util.Date;
import java.util.Optional;
import org.springframework.stereotype.Service;

@Service
public class AssignService { // 假设这是您的服务层

    private final PlansRepository plansRepo;
    private final MedsRepository medsRepo; // 假设有MedsRepository

    public AssignService(PlansRepository plansRepo, MedsRepository medsRepo) {
        this.plansRepo = plansRepo;
        this.medsRepo = medsRepo;
    }

    public Plans assignPlansToMeds(Long id, Long planId, Date planDate) {
        // 使用orElseThrow结合自定义异常
        Meds meds = medsRepo.findById(id)
                            .orElseThrow(MedsNotFoundException.id(id));

        Plans plans = plansRepo.findById(new PlansPKId(planId, planDate))
                               .orElseThrow(PlansNotFoundException.idAndDate(planId, planDate));

        // ... 后续业务逻辑
        plans.getAssignedMeds().add(meds);
        return plansRepo.save(plans);
    }
}

通过这种方式，当实体未找到时，会抛出特定的NotFoundException子类。结合Spring的@ControllerAdvice，可以将这些异常统一处理为HTTP 404 Not Found响应，并返回包含有意义错误信息的消息体，极大提升API的用户体验和可维护性。总结处理Spring Data JPA中的复合主键查询有多种策略，包括直接使用EmbeddedId类型与findById、利用派生查询方法以及自定义JPQL查询。每种方法都有其适用场景，开发者应根据具体需求和代码可读性进行选择。同时，遵循使用现代日期时间API和健壮的Optional处理（特别是结合自定义异常）的最佳实践，将有助于构建更稳定、更易于维护的Spring Data JPA应用程序。

相关文章