Spring Data JPA 复合主键查询与最佳实践-java教程-PHP中文网

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

心靈之曲

发布： 2025-12-12 11:03:18

原创

950人浏览过

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

本文深入探讨了在 spring data jpa 中处理复合主键的策略。我们将学习如何正确配置 `jparepository` 以支持 `embeddedid`，并介绍三种查询复合主键实体的方法：使用 `findbyid` 配合 `embeddedid` 对象、通过方法名派生查询，以及利用 `@query` 注解自定义 jpql。此外，文章还将强调使用现代日期时间 api 和构建健壮的 `optional` 错误处理机制等关键最佳实践，以提升代码质量和可维护性。

理解 JPA 复合主键

在关系型数据库中，有时一个表的主键由多个列共同组成，这就是复合主键。在 JPA 中，我们通常通过 @EmbeddedId 和 @Embeddable 注解来定义复合主键。@Embeddable 注解用于标记一个类作为可嵌入的组件，它包含了构成复合主键的所有字段。而 @EmbeddedId 则用于实体类中，声明该实体使用一个嵌入式对象作为其主键。

以下是一个复合主键 PlansPKId 的定义示例，它由 planId 和 planDate 组成：

@Data
@AllArgsConstructor
@NoArgsConstructor
@EqualsAndHashCode
@Embeddable
public class PlansPKId implements Serializable {

    private long planId;

    private Date planDate; // format: yyyy-mm-dd
}

登录后复制

相应的 Plans 实体将使用 @EmbeddedId 来引用这个复合主键类：

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

    @Column
    private String planName;

    @Column
    private String weekday;

    // ... 其他字段和关联关系
}

登录后复制

Spring Data JPA 复合主键查询策略

在使用 Spring Data JPA 时，JpaRepository 的 findById() 方法只接受一个参数作为实体的主键类型。这意味着，如果您的实体使用了复合主键，您不能直接将构成复合主键的多个字段作为参数传递给 findById()。相反，您需要将整个复合主键对象作为 ID 类型传递。

1. 使用 findById() 配合 EmbeddedId 对象

这是处理复合主键最直接的方式。您需要将 JpaRepository 的第二个泛型参数（ID 类型）设置为您的复合主键类 (PlansPKId)。

首先，定义您的仓库接口：

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

@Repository
public interface PlansRepository extends JpaRepository<Plans, PlansPKId> {
}

登录后复制

然后，在您的业务逻辑中，通过创建一个 PlansPKId 实例并将其传递给 findById() 方法来查询实体：

import java.util.Date;

// ...
public Plans assignPlansToMeds(Long id, Long planId, Date planDate) {
    // ...
    Plans plans = plansRepo.findById(new PlansPKId(planId, planDate))
                           .orElseThrow(() -> new PlansNotFoundException(planId, planDate)); // 见下文错误处理部分
    // ...
    return plansRepo.save(plans);
}

登录后复制

注意事项: 每次查询都需要创建 PlansPKId 的新实例。

2. 通过方法名派生查询

Spring Data JPA 提供了强大的功能，可以根据仓库接口中的方法名自动生成查询。对于复合主键，您可以通过引用嵌入式 ID 对象的属性来构建查询方法名。

例如，如果您想根据 planId 和 planDate 查询 Plans 实体，可以定义如下方法：

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<Plans, PlansPKId> {
    Optional<Plans> findByPlansPKIdPlanIdAndPlansPKIdPlanDate(long planId, Date planDate);
}

登录后复制

Spring Data JPA 会自动解析 PlansPKIdPlanId 和 PlansPKIdPlanDate，并生成相应的查询。 注意事项: 这种方法可能导致方法名过长且难以阅读，尤其当复合主键包含更多字段时。

3. 使用 @Query 注解自定义 JPQL 查询

当您需要更灵活的查询或者希望方法名更简洁时，可以使用 @Query 注解来定义 JPQL (Java Persistence Query Language) 或原生 SQL 查询。

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<Plans, PlansPKId> {

    @Query("select p from Plans p where p.plansPKId.planId = :planId and p.plansPKId.planDate = :planDate")
    Optional<Plans> findByCompositeId(@Param("planId") long planId, @Param("planDate") Date planDate);
}

登录后复制

在这种情况下，您可以在 @Query 注解中直接引用 Plans 实体中的 plansPKId 字段，并进一步访问其内部属性 planId 和 planDate。@Param 注解用于将方法参数映射到 JPQL 查询中的命名参数。

Mistral AI

Mistral AI被称为“欧洲版的OpenAI”，也是目前欧洲最强的 LLM 大模型平台

182

查看详情

最佳实践与错误处理

除了选择合适的查询策略外，遵循一些最佳实践对于构建健壮和可维护的 Spring Data JPA 应用至关重要。

1. 使用现代日期时间 API

强烈建议使用 java.time 包下的现代日期时间 API (如 LocalDate, LocalDateTime, ZonedDateTime) 来替代传统的 java.util.Date 和 java.util.Calendar。现代 API 提供了更好的不变性、线程安全性、清晰的语义和更强大的功能。

例如，您可以将 PlansPKId 中的 Date planDate 修改为 LocalDate planDate：

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

@Data
@AllArgsConstructor
@NoArgsConstructor
@EqualsAndHashCode
@Embeddable
public class PlansPKId implements Serializable {

    private long planId;

    private LocalDate planDate; // 推荐使用 LocalDate
}

登录后复制

Spring Data JPA 和 Hibernate 对 java.time 类型有良好的支持，通常无需额外配置。

2. 安全的 Optional 处理与自定义异常

在 Spring Data JPA 中，findById() 方法返回一个 Optional 对象。直接调用 Optional.get() 而不先检查其是否存在是非常危险的，因为它可能在值不存在时抛出 NoSuchElementException。推荐使用 orElseThrow() 方法结合自定义异常来处理实体未找到的情况，这不仅能提供更清晰的错误信息，还能更好地集成到应用程序的异常处理机制中。

首先，定义一个抽象的 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<String, Object> 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 "))));
    }
}

登录后复制

接着，为具体的实体（如 Plans 和 Meds）创建继承自 NotFoundException 的特定异常类：

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

public class PlansNotFoundException extends NotFoundException {

    private PlansNotFoundException(final Map<String, Object> identifiers) {
        super("plans", identifiers);
    }

    public static Supplier<PlansNotFoundException> idAndDate(final long planId, final Date planDate) {
        return () -> new PlansNotFoundException(Map.of("id", planId, "date", planDate));
    }
}

登录后复制

import java.util.function.Supplier;

public class MedsNotFoundException extends NotFoundException {

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

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

登录后复制

现在，您可以在查询时安全地使用 orElseThrow()：

import java.util.Date;

public Plans assignPlansToMeds(Long id, Long planId, Date planDate) {
    // 获取 Meds 实体
    Meds meds = medsRepo.findById(id).orElseThrow(MedsNotFoundException.id(id));

    // 获取 Plans 实体（使用复合主键）
    Plans plans = plansRepo.findById(new PlansPKId(planId, planDate)) // 或 findByCompositeId(planId, planDate)
                           .orElseThrow(PlansNotFoundException.idAndDate(planId, planDate));

    // ... 业务逻辑
    // Set<Meds> medsSet = plans.getAssignedMeds();
    // medsSet.add(meds);
    // plans.setAssignedMeds(medsSet);
    return plansRepo.save(plans);
}

登录后复制

通过这种方式，当实体未找到时，会抛出特定的业务异常，而不是通用的运行时异常。结合 Spring 的 @ControllerAdvice，您可以将这些自定义异常映射到 HTTP 状态码（例如，NotFoundException 映射到 404 Not Found），从而为客户端提供清晰且一致的错误响应。

总结

在 Spring Data JPA 中处理复合主键查询需要对 JpaRepository 的 ID 类型有清晰的理解。无论是通过构造 EmbeddedId 对象、利用方法名派生查询，还是编写自定义 JPQL，都有多种有效的方法来检索数据。同时，遵循使用现代日期时间 API 和实现健壮的 Optional 错误处理机制等最佳实践，将显著提升应用程序的可靠性、可读性和可维护性。选择最适合您项目需求和团队风格的查询策略和最佳实践，是构建高质量 Spring 应用的关键。

以上就是Spring Data JPA 复合主键查询与最佳实践的详细内容，更多请关注php中文网其它相关文章！