# Spring Data

> For the complete documentation index, see [llms.txt](https://www.jetbrains.com.cn/help/idea/llms.txt).

[Spring Data JPA](https://spring.io/projects/spring-data-jpa) 是更大的 Spring Data 家族的一部分，使得能够快速实现基于 JPA 的代码库变得容易。 JPA Buddy 提供一个清晰的用户界面，用于生成 Java 和 Kotlin 实体的存储库、投影、查询等。 要启用这些功能，您的项目应包含 [安装指南](jpa-buddy.html)中提到的依赖项。

## 仓库创建

JPA Buddy 提供多种方式创建仓库，使大多数用户使用与 JPA 相关的对象更加方便。 项目中生成存储库的所有可能方法都在以下视频中显示：

[Video](https://www.youtube.com/v/8pHsZ_HvbXs)

> **Note:**
> 您只能为带有字段注释为  `@Id` 的实体创建 Spring Data JPA repository。

在"New JPA Repository"窗口中，您可以设置：

* 将创建库的实体

* 存储库类的名称

* 存储库的父类。 它可以是： * [org.springframework.data.repository](https://docs.spring.io/spring-data/jpa/docs/current/reference/html/#jpa.repositories) 包中的一个库 * 您项目中的任何存储库

* 存储库是否会继承 [JpaSpecificationExecutor](https://docs.spring.io/spring-data/jpa/docs/current/reference/html/#specifications)

* 源根目录

* 创建存储库的包名

![new-jpa-repository](https://resources.jetbrains.com.cn/help/img/idea/2026.3/new-jpa-repository-single.png)

为每个实体一个个创建 Spring Data 仓库可能会成为一项繁琐的工作。 有了 JPA Buddy，您可以加速这一过程。 要同时为多个 JPA 实体创建存储库，您需要执行三个步骤。 在项目树中选择实体，调用 JPA Buddy 向导，然后调整您的选择。 就是这样！ 看看这个功能如何加速开发过程：

[Video](https://www.youtube.com/v/nSusI0dq7nQ)

## JPA 结构存储库

JPA Buddy 将每个实体的所有存储库集中在一个地方，以实现项目内最有效的导航。 无论实体的仓库位于不同项目包还是相同项目包中，这都无关紧要。 与该实体相关的所有存储库都将显示在   仓库  部分。 从这里，您可以快速移动到 repository 实现或创建一个新的实现。

![jpa-structure-repository](https://resources.jetbrains.com.cn/help/img/idea/2026.3/jpa-structure-repository.png)

## 查询/方法生成

Spring Data 提供了使用  `@Query`  注解定义查询的能力。 您可以使用 JPA Palette (1) 或 Editor Toolbar (2) 快速编写它们并避免拼写错误。 请选择以下类型的查询之一，并使用便捷的 UI 进行配置。

![jpa-palette-query](https://resources.jetbrains.com.cn/help/img/idea/2026.3/jpa-palette-query.png)

### 示例

> **Note:**
> 与 @Query 不同，派生查询方法的名称只能根据 [查询命名约定](https://docs.spring.io/spring-data/jpa/docs/current/reference/html/#jpa.query-methods.query-creation) 自动生成或通过指定其 [主题关键字](https://docs.spring.io/spring-data/jpa/docs/current/reference/html/#appendix.query.method.subject) 来生成。

让我们来看一个创建 Find  Collection Query  的例子。

![create-query-find-collection](https://resources.jetbrains.com.cn/help/img/idea/2026.3/create-query-find-collection.png)

在窗口顶部，您可以定义集合和查询返回类型的换行类型。 此外，JPA Buddy 还允许您通过点击  `+`  按钮生成新的 [Projection 接口](#repository-creation)或 [DTO 类](jpa-buddy-dto-generator.html)。

您还可以指定方法名。 不过，如果您将其留空，名称将根据 [查询命名规范](https://docs.spring.io/spring-data/jpa/docs/current/reference/html/#jpa.query-methods.query-creation)自动生成。

窗口中间包含查询条件的表格。

在窗口底部，您可以指定：

* 参数是否会被命名；

* 是否使用 `Pageable` 参数；

* 等等。

最后，您可以指定要按顺序排列查询结果的字段。

对于上述配置，将生成以下查询：

```JAVA
@Query("""
          select distinct o from Owner o
          where upper(o.firstName) like upper(concat(:firstName, '%'))
          and upper(o.lastName) like upper(concat('%', :lastName, '%'))
          order by o.lastName
          """)
      @Async
      CompletableFuture<List<Owner>> findOwners(@Param("firstName") String firstName,
                                                @Param("lastName") @NonNull String lastName,
                                                Pageable pageable);

```

同样的方法适用于派生查询方法。 可以使用 Method prefix 下拉菜单来定义所需的主题关键字并添加别名，而不是使用 Method name 字段。

![derived-query-method-prefix](https://resources.jetbrains.com.cn/help/img/idea/2026.3/derived-query-method-prefix.png)

这允许您自定义生成的查询方法的命名约定，从而在代码中提供灵活性和一致性。

### 实体 意图

JPA Buddy 还在实体属性上提供了直接进入查询/方法创建窗口的意图。 将文本光标放置在所需的属性上，按 `Alt+Enter` (Windows), `⌥ ⏎` (macOS), `⌥ ⏎` (IntelliJ IDEA Classic (macOS)), `⌥ ⏎` (macOS System Shortcuts), `Alt+Enter` (XWin), `Alt+Enter` (GNOME), `Alt+Enter` (KDE), `Alt+Enter` (Emacs), `Alt+Enter` (Sublime Text), `⌥ ⏎` (Sublime Text (macOS)), `Alt+Enter` (Visual Studio), `⌥ ⏎` (Visual Studio (macOS)), `Alt+Enter` (NetBeans), `Ctrl+1` (Eclipse), `⌘ 1` (Eclipse (macOS))，然后点击创建 Spring Data 存储库方法。 在打开的窗口中，选择所需的query/method类型。

[Video](https://www.youtube.com/v/mevqm5DzGRs)

### 未解析的引用

对于倾向于先调用尚不存在的方法、随后再实现它的开发者，JPA Buddy 也能提供帮助。 只需编写所需的签名，然后通过特殊操作进入查询或方法创建向导：

![未解析引用](https://resources.jetbrains.com.cn/help/img/idea/2026.3/unresolved-reference.png)

### 设置

Spring Data 提供了几种用于派生查询方法名称的关键字表达式。 您可以使用 NameContaining、NameIsContaining 或 NameContains——结果是一样的。 一方面，它在方法命名上给了我们一些灵活性。 另一方面，在大团队中，对相同操作使用不同命名可能会使代码审查员和维护人员感到困惑。 如果您的开发团队已经建立了命名标准，您可以配置 JPA Buddy 仅使用批准的关键字来生成方法名称：

![conditions-settings](https://resources.jetbrains.com.cn/help/img/idea/2026.3/conditions-settings.png)

## 现有方法/查询修改

要配置方法或查询，请将光标放在其上并使用 JPA Inspector：

![jpa-inspector](https://resources.jetbrains.com.cn/help/img/idea/2026.3/jpa-inspector.png)

### 实体图支持

在 JPA 2.1 中引入的 EntityGraph 是最受期待的特性之一。 实体图为我们提供了另一层数据获取控制。 JPA Buddy 也支持它们，所以您可以使用方便的 GUI 向导构建图表：

[Video](https://www.youtube.com/v/Duco-QWBXy0)

## 查询重构

### 异步

Spring Data JPA 提供异步运行存储库查询的能力。 要使查询异步化，仅添加 '@Async' 注解是不够的，还需要将返回类型更改为以下之一：

* `Future<ClassName>`

* `CompletableFuture<ClassName>`

* `ListenableFuture<ClassName>`

了解有关异步查询结果的更多信息，请参阅相应的 Spring Data JPA 文档 [页](https://docs.spring.io/spring-data/jpa/docs/current/reference/html/#repositories.query-async)。

要使查询异步，请将文本光标放在您要更改的查询上，并从下拉列表中选择结果返回类型：

![async](https://resources.jetbrains.com.cn/help/img/idea/2026.3/async.png)

### 动态投影

在 Spring Data JPA 中，您可以使用通用 repository 方法在运行时指定投影。 向您的存储库方法添加类型类参数，以便使用相同的查询进行不同的投影。 这使您能够在业务代码中定义首选的返回类型。

要使查询变为通用，请将文本光标放在您要更改的查询上，并勾选"动态投影"框。

![动态投影](https://resources.jetbrains.com.cn/help/img/idea/2026.3/dynamic-projection.png)

### 查询提取

派生查询方法是定义查询的一个方便方式。 但是，随着时间的推移，它们可能会演变成庞大且不可读的结构，您可以将其转换为整洁的  `@Query` -注释方法。 这可以通过 JPA Buddy 轻松实现。 将文本光标置于查询上，然后在 JPA Inspector 中点击"Query extract..."。

[Video](https://www.youtube.com/v/lYZielYtVXI)

### 查询自动完成

对于 IntelliJ IDEA 社区版，JPA Buddy 提供查询自动完成功能（类似于 IntelliJ IDEA 旗舰版提供的功能）。 将文本光标放在查询上，然后在 JPA Inspector 中点击"Query edit..."。

[Video](https://www.youtube.com/v/IQDgQ5_l764)

## 投影

有时您只需要表中的一部分列。 在这种情况下，Spring Data JPA 投影很有用，允许您仅从查询中返回所需的字段。

[Video](https://www.youtube.com/v/xevxVvu_Hbc)

在   新建 Spring 投影  窗口中，您可以：

* 定义源根和包；

* 选择实体类；

* 为投影类设置名称；

* 选择您想要包含的字段。

此外，JPA Buddy 允许您为引用的实体生成 Projections。 选择关联实体，选择投影类型，并选择所需的字段。

![new-spring-projection](https://resources.jetbrains.com.cn/help/img/idea/2026.3/new-spring-projection.png)

对于上述配置，将生成以下投影：

```JAVA
/**
   * A Projection for the {@link Pet} entity
   */
  public interface PetInfo {
  	Integer getId();

  	String getName();

  	LocalDate getBirthDate();

  	PetTypeInfo getType();

  	OwnerInfo getOwner();

  	/**
  	 * A Projection for the {@link PetType} entity
  	 */
  	interface PetTypeInfo {
  		Integer getId();

  		String getName();
  	}

  	/**
  	 * A Projection for the {@link Owner} entity
  	 */
  	interface OwnerInfo {
  		String getFirstName();

  		String getLastName();
  	}
  }

```

### 保持 Projections 与其 JPA 实体同步

随着时间的推移，实体可能会发生变化，您需要相应地更改投影。 JPA Buddy 允许您将实体与其投影进行同步，反之亦然。 请参阅 [DTO Generator](jpa-buddy-dto-generator.html#keep-dtos-in-sync-with-its-jpa-entity) 部分以了解此功能的详细信息。

### 投影声明设置

每个项目可能遵循其自己的代码编写约定。 在工具 -> JPA Buddy -> 投影声明中，您可以配置：

1.  类名后缀。

2.  名称模式正则表达式（当字段为空时功能被禁用）。 如果您对 Projections 使用强制命名约定，此选项很有用。 它允许 JPA Buddy 仅使用 Projection 名称将 Projection 与其 JPA Entity 关联。 要为目标 JPA 实体的简单类名指定占位符，请使用  `(?<entity>.)`  模式。 例如，  `(?<entity>.*(?:Info|Prj|Projection|VO|Vo|View|Request|Browse)`  表示  `MyEntityInfo` 、  `MyEntityPrj` 等。 类将被视为  `MyEntity`  的投影。

3.  类注释。 定义将在 Projection 接口上生成的注释。

4.  评论链接的正则表达式（当字段为空时，该功能被禁用）。 此选项允许 JPA Buddy 将 Projection 与其 JPA Entity 关联。 要在注释中为目标实体的 FQN（Fully Qualified Name）指定占位符，请使用  `(?<entity>.*)`  模式。 那么，如果 regexp 被定义为  `\{@link (?<entity>.*)\} 实体的投影`  它将在以下 Javadoc 注释中解析：

```JAVA
/**
   * A Projection for the {@link Pet} entity
   */

```

![projection-declaration](https://resources.jetbrains.com.cn/help/img/idea/2026.3/projection-declaration.png)

#### 实体及其投影之间的便捷导航

一旦 JPA Buddy 能够将 Projection 接口与实体关联：

* Projection 接口将出现在 JPA 结构面板的 Dto & Projections 部分以及编辑器工具栏（1）中

* 在投影中将出现装订区域图标，以便于导航到其实体(2)

![projection-navigation](https://resources.jetbrains.com.cn/help/img/idea/2026.3/projection-navigation.png)

## 数据库属性的自动生成

如果已 [创建数据源](managing-data-sources.html#create_a_data_source)，可快速将数据库连接详情和其他 Hibernate 专用属性插入到 Spring Boot 配置文件中（  `application.properties`  或  `application.yaml` ）。

> **Note:**
> 此功能仅支持以下数据库：
>
>
>
> * [H2](h2.html)
>
> * [HSQLDB](hsqldb.html)
>
> * [IBM Db2 LUW](ibm-db2-luw.html)
>
> * [MariaDB](mariadb.html)
>
> * [Microsoft SQL 服务器](microsoft-sql-server.html)
>
> * [MySQL](mysql.html)
>
> * [甲骨文](oracle.html)
>
> * [PostgreSQL](postgresql.html)

Procedure: 将数据库属性添加到配置文件中

1. 打开您的  `application.properties`  文件或  `application.yaml`  文件。

2. 按下 `Alt+Insert` (Windows), `⌘ N` (macOS), `⌃ N` (IntelliJ IDEA Classic (macOS)), `⌘ N` (macOS System Shortcuts), `Alt+Insert` (XWin), `Alt+Insert` (GNOME), `Alt+Insert` (KDE), `Alt+Insert` (Emacs), `Alt+Insert` (Sublime Text), `⌘ N` (Sublime Text (macOS)), `Alt+Insert` (Visual Studio), `⌘ ⌃ N` (Visual Studio (macOS)), `Alt+Insert` (NetBeans), `Alt+Insert` (Eclipse), `⌘ N` (Eclipse (macOS))。

3. 在出现的   生成   弹窗中，选择 ![数据源图标](https://resources.jetbrains.com.cn/help/img/idea/2026.3/app.expui.javaee.persistenceEntity.svg)   数据源  。

![生成弹窗并高亮显示数据源选项](https://resources.jetbrains.com.cn/help/img/idea/2026.3/generate-copyright-popup.png)

4. 数据源   对话框将打开。

![数据源对话框](https://resources.jetbrains.com.cn/help/img/idea/2026.3/generate-data-source-dialog.png)

配置这些选项：

* 数据源 ：选择用于数据库连接属性的数据源。

* Hibernate ：配置 [Hibernate](hibernate.html) 专用属性： * DDL 自动 ：指定 Hibernate 在应用程序启动时如何处理现有数据库架构： * （空）：不执行任何操作。 * 验证 ：验证现有架构是否与项目中的实体匹配。 如不匹配，将抛出异常并导致应用程序启动失败 * 更新 ：更新现有架构以匹配项目中的实体。 此选项不会删除现有表或列。 * 创建 ：删除现有架构，并基于项目中的实体创建新架构。 * 创建-删除 ：删除现有架构，基于项目中的实体创建新架构，在应用程序停止时再次删除该架构。 * 显示 SQL ：将 Hibernate 执行的所有 SQL 语句打印到控制台。 * 设置 SQL 格式 ：在控制台和日志中美化显示 SQL 语句以提升可读性。

5. 点击   OK  。

IntelliJ IDEA 会自动将属性插入到配置文件中。

## 审核支持

在大型应用程序中，进行审计是至关重要的。 JPA Buddy 通过为常用审计字段提供注释（如  `@CreatedBy` 、  `@CreatedDate` 、  `@LastModifiedBy` 和  `@LastModifiedDate` ），使其变得轻而易举。 此外，JPA Buddy 会在您忘记将  `@EnableJpaAuditing` 注释添加到您的配置中，或未将 AuditingEntityListener 添加到当前实体时通知您。 这就更没有犯错的余地了！

[Video](https://www.youtube.com/v/1D5zEzLX1iY)

标签：Spring Data、JPA、Projections、审计、DTO、查询、Repository、实体、JPQL、本机查询、动态 Projections

## Blaze Persistence 支持

[Blaze-Persistence](https://persistence.blazebit.com/) 无缝集成了 Spring Data JPA，允许您在利用高级查询和优化功能的同时，从 Spring Data 的便利性和生产力中受益。 JPA Buddy 提供对该框架的支持，以创建 Entity Views 的 Spring Data JPA 存储库，但仅当项目中包含 [相关库](jpa-buddy.html#dependencies)时。

从标准仓库创建窗口创建用于实体视图的 Spring Data JPA 仓库是可用的。 一旦您选择了一个 Entity View，父接口的唯一选项是  `com.blazebit.persistence.spring.data.repository.EntityViewRepository` 或其继任者之一。

![blaze-persistence-spring-data-repository.png](https://resources.jetbrains.com.cn/help/img/idea/2026.3/blaze-persistence-spring-data-repository.png)

```JAVA
import com.blazebit.persistence.spring.data.repository.EntityViewRepository;
import com.example.blazepersistence.view.BaseView;

public interface BaseViewRepository extends EntityViewRepository<BaseView, Long> { }

```

[Video](https://www.youtube.com/v/OWH4Y2onh_A)

## Hibernate Envers 支持

> **Note:**
> 要启用此功能，请将 [相应的依赖项](jpa-buddy.html#dependencies)添加到项目中。

[Video](https://www.youtube.com/v/k5OTgQBmSrg)

JPA Buddy 允许您在创建 JPA 存储库时决定该存储库是否应实现  `RevisionRepository`  接口。 它将自动在仓库声明中插入实体类型、实体 ID 类型和修订号类型。 例如：

```JAVA
@Entity
@Table(name = "book")
public class Book {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    @Column(name = "id", nullable = false)
    private Long id;
}

```

![修订库](https://resources.jetbrains.com.cn/help/img/idea/2026.3/revision-repository.png)

生成的存储库声明：

```JAVA
public interface BookRepository extends JpaRepository<Book, Long>,
          RevisionRepository<Book, Long, Integer> {
 }

```