# 实体设计器

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

一旦您 [安装 JPA Buddy](jpa-buddy.html)，您会发现：

1.    编辑器   工具栏

2.    JPA 设计器   工具窗口

![JPA Buddy 可视化工具](https://resources.jetbrains.com.cn/help/img/idea/2026.3/jpa-buddy-interface_without_persistence.png)

> **Tip:**
> 此前，   JPA 资源管理器   工具窗口也是 JPA Buddy 的一部分。 从 IntelliJ IDEA 2024.2 开始，   JPA 资源管理器   的大部分功能都可以在 [Persistence](persistence-tool-window.html) 工具窗口中使用。

您可以在 [designer settings](#designer-settings)中自定义   JPA 设计器  的外观。 您可以将其与其他面板一起显示，作为独立面板，将其集成到标准 IntelliJ IDEA 面板中，或者完全隐藏它。

## 持久性工具窗口

大多数以前在   JPA 结构   中可用的功能现在在 [持续性工具窗口](persistence-tool-window.html) 中都可以使用。 此外，JPA Buddy 向   持久化  工具窗口添加了以下功能：

* 创建 JPA 实体，从 Java 或 Kotlin 类生成 JPA 实体

* 创建 Spring Data JPA Repository 和 Spring Data Projection

* 基于 JPA 实体创建 DTO

* 查看每个实体的 DTO 和投影

![持久性工具窗口](https://resources.jetbrains.com.cn/help/img/idea/2026.3/persistence_tool_window_with_jpa_buddy.png)

> **Note:**
> 您可以在 [可视化设计器设置](#designer-settings)中设置 JPA 结构的可见性。

## JPA Palette

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

JPA Palette 旨在为当前上下文生成适当的代码。 对于实体，它可以是属性或索引；对于仓库——查询方法等。

JPA Palette 为以下功能提供代码生成向导：

* [属性](https://www.youtube.com/embed/8A_ftrU_yYE)

* [生命周期回调](https://www.youtube.com/embed/d77p30UXBzc)

* [索引](https://www.youtube.com/embed/9YVtxVeN9Yk)

* [命名查询](https://www.youtube.com/embed/iV6jTbzjgkE)

* [逆向工程](https://youtu.be/az9ghvGczys)

* [实用工具 – Equals/HashCode/ToString](https://youtu.be/jTdMIOfyx2Q)

> **Note:**
> 您可以在 [可视化设计器设置](#designer-settings) 中设置 JPA Palette 的可见性。

### 关联性能提示

Hibernate 具有许多关系映射类型，但不是所有的都同样高效。

在创建关联时，JPA Buddy 简要解释了当前配置为何效率低下并可能导致性能问题。 请使用   了解详情   按钮查看。

![了解更多](https://resources.jetbrains.com.cn/help/img/idea/2026.3/learn-more.jpeg)

此外，您可以应用 JPA Buddy 建议的优化。 只需从可能的选项的下拉列表中选择：

![建议优化](https://resources.jetbrains.com.cn/help/img/idea/2026.3/suggested-optimizations.jpeg)

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

## JPA 检查器

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

JPA Inspector 旨在编辑现有代码：属性、索引、查询等。

JPA Inspector 允许您在其中配置 JPA 实体和属性。 点击您需要配置的任意元素，然后更改所需的属性：

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

> **Note:**
> 您可以在 [可视化设计器设置](#designer-settings)中设置 JPA Inspector 可见性。

### Hibernate 验证

对于使用 Hibernate Validations 的项目，会出现一个包含您可以应用于所选属性的验证部分：

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

## 编辑器工具栏

编辑器工具栏包含根据文件内容显示的相关操作。 您可以在编辑器窗口顶部找到它。

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

> **Note:**
> 您可以在 [可视化设计器设置](#designer-settings)中设置 Editor Toolbar 的可见性。

## 实体生成

要创建新的 JPA 实体，请右键点击所需的文件夹并选择 New -> JPA Entity (1)。 此外，您可以从 JPA 结构 (2) 选项卡创建一个新的实体：

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

之后会出现以下窗口：

![new-entity](https://resources.jetbrains.com.cn/help/img/idea/2026.3/new-entity.jpeg)

### 语言支持

JPA Buddy 支持 [Java](https://www.java.com/) 和 [Kotlin](https://kotlinlang.org/)。 当 JPA Buddy 检测到您的项目中存在 [Kotlin 依赖](https://kotlinlang.org/docs/maven.html)时，   新建实体  窗口中会出现一个额外选项，允许您选择语言：

![new-entity-language-choose](https://resources.jetbrains.com.cn/help/img/idea/2026.3/new-entity-language-choose.jpeg)

此外，您可以在 Settings -> Tools -> JPA Buddy -> Entity Declaration 中选择在   新建实体   窗口中默认选用的语言：

![settings-scaffolding-language](https://resources.jetbrains.com.cn/help/img/idea/2026.3/settings-scaffolding-language.jpeg)

### ID 及其生成策略

根据 JPA 规范，实体定义需要一个 ID 属性。 JPA Buddy 允许您生成这个属性并选择类型 (1) 和生成策略 (2)。 此外，您可以指定用于  `序列` 生成策略的序列（3）。

![sequence-id.jpeg](https://resources.jetbrains.com.cn/help/img/idea/2026.3/sequence-id.jpeg)

如果您想将嵌入式实体用作 ID，JPA Buddy 会为您提供项目中存在的  `@Embeddable` 实体列表：

![embeddable-entity-as-id](https://resources.jetbrains.com.cn/help/img/idea/2026.3/embeddable-entity-as-id.jpeg)

您还可以通过 JPA Palette (1)、Editor Toolbar (2) 或使用快速修复 ( `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))) (3) 生成 ID 属性。

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

之后，将出现一个具有更全面自定义选项的向导：

![new-id-attribute](https://resources.jetbrains.com.cn/help/img/idea/2026.3/new-id-attribute.jpeg)

请参见下面生成的 ID 示例：

```JAVA
@Id
  @GeneratedValue(
      strategy=GenerationType.SEQUENCE,
      generator = "owners_seq"
  )
  @SequenceGenerator(
      name = "owners_seq",
      sequenceName = "SEQ_OWNER",
      initialValue = 5,
      allocationSize = 10
  )
  @Column(name = "id", nullable = false)
  private Long id;

```

## 提取到 MappedSuperclass

随着您的应用程序增长和 JPA 模型的演变，您可能会意识到某些属性在多个实体中是通用的，应该提取到一个  `@MappedSuperclass`  中以便更好地组织代码。 JPA Buddy 可以轻松将方法和属性连同它们的 JPA 注释提取到 MappedSuperclass 中，并构建一个设计良好的实体层次结构。

要实现此目的，请点击实体的属性，然后导航到实体设计器选项卡并访问操作菜单，或按 `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)) 打开上下文操作菜单。 从此处开始，选择   提取到 MappedSuperclass  ，如下所示：

![ed-extract-to-mappedsuperclass.png](https://resources.jetbrains.com.cn/help/img/idea/2026.3/ed-extract-to-mappedsuperclass.png)

接下来选择要包含在 MappedSuperclass 中的所需属性和方法。 JPA Buddy 将自动把现有注解应用到提取的属性上。 请注意，任何在方法中使用的属性也将包含在内。

![extract-to-mappedsuperclass.png](https://resources.jetbrains.com.cn/help/img/idea/2026.3/extract-to-mappedsuperclass.png)

应用上述参数后，我们的 Pet 实体将从以下生成的类扩展，移除提取的属性：

```JAVA
//Getters and setters are omitted for brevity
  @MappedSuperclass
  public class GenericPet {
      @Id
      @Column(name = "id", nullable = false)
      private Integer id;

      @Column(name = "name", length = Integer.MAX_VALUE)
      private String name;

      @Column(name = "birth_date")
      private LocalDate birthDate;

      @ManyToOne(fetch = FetchType.LAZY, optional = false)
      @JoinColumn(name = "type_id", nullable = false)
      private Type type;

      @Override
      public boolean equals(Object o) {
          if (this == o) return true;
          if (o == null || Hibernate.getClass(this) != Hibernate.getClass(o)) return false;
          Pet pet = (Pet) o;
          return getId() != null && Objects.equals(getId(), pet.getId());
      }

      @Override
      public int hashCode() {
          return getClass().hashCode();
      }
  }

```

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

## Lombok

### 检查

[Lombok](https://projectlombok.org/) 是一个很好的工具，可以使您的 Java 代码简洁且干净。 但是在将 Lombok 与 JPA 结合使用时，有几件事需要考虑。 JPA Buddy 通过一组检查帮助您在 JPA 实体中使用 Lombok 以遵循最佳实践：

避免将  `@EqualsAndHashCode`  和  `@Data`  与 JPA 实体一起使用。

实体本质上是可变的，因此为它们实现 equals() 和 hashCode() 并不是一项简单的任务。 Lombok 提供的实现不太适用于 JPA 实体，可能会导致集合问题和懒加载属性的意外加载。

[Video](https://www.youtube.com/v/E6qZXvz-Fs0)

使用  `@ToString`  时始终排除 lazy 属性

默认情况下，  `@ToString`  包含所有对象字段。 这种方法可能会对 JPA 实体产生不良的副作用：意外加载懒惰属性。 这很容易损害应用程序性能，或者如果发生在事务之外，则导致 LazyInitializationException。

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

请不要忘记将  `@NoArgsConstructor`  添加到具有  `@Builder`  或  `@AllArgsConstructor`  的实体中

他们引入了自己的构造函数，因此编译器不会生成默认的构造函数。 根据规范，所有 JPA 实体都需要无参数构造函数。

![无参构造函数](https://resources.jetbrains.com.cn/help/img/idea/2026.3/no-args-constructor.jpeg)

请查看我们的 [文章](https://www.jpa-buddy.com/blog/lombok-and-jpa-what-may-go-wrong/)，了解更多关于为什么遵守上述规则如此重要的信息。

### 注解

对于使用 Lombok 的项目，JPA Inspector 显示一个部分，您可以向实体添加可能的注解。

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

### 设置

JPA Buddy 提供使用 Lombok 注解生成新实体和属性的可能性。 要配置在创建新实体或属性时要添加的属性，您可以在实体声明窗口的底部选择所需的选项。

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

## Hibernate

### 类型与 JPA 转换器

JPA Buddy 通过 JPA Inspector 帮助您生成 JPA Converter 或 Hibernate Custom Type 的空白：

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

此外，您可以通过 JPA Structure 创建它。 点击 ![添加](https://resources.jetbrains.com.cn/help/img/idea/2026.3/app-client.expui.general.add.svg) 并选择   JPA 转换器   或   Hibernate CustomType  。

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

在“创建自定义类型”窗口中，您可以配置类名称、实体特性类型和数据库列类型。

对于 JPA Converter，您可以定义它是否将自动适用。

![create-custom-type-jpa](https://resources.jetbrains.com.cn/help/img/idea/2026.3/create-custom-type-jpa.jpeg)

对于 Hibernate Custom Type，您可以设置是否允许基于参数更改类型的行为。

![create-custom-type-hibernate](https://resources.jetbrains.com.cn/help/img/idea/2026.3/create-custom-type-hibernate.jpeg)

这是一个生成的 Hibernate Custom Type 示例：

```JAVA
public class BooleanConverter extends AbstractSingleColumnStandardBasicType<Boolean> {
      public BooleanConverter() {
          super(new CharTypeDescriptor(), new BooleanConverterDescriptor());
      }

      @Override
      public String getName() {
          return "BooleanConverter";
      }

      @Override
      public Object resolve(Object value,
                            SharedSessionContractImplementor session,
                            Object owner,
                            Boolean overridingEager) throws HibernateException {
          return null;
      }
  }

```

### 事件系统

Hibernate 事件系统是一个强大的工具，允许您记录或广播更改、在不可逆操作前执行附加检查、在数据状态变化时挂钩业务逻辑等。 对于所有这些情况，Hibernate 提供事件监听器，JPA Buddy 可以帮助您通过几次点击来创建它们：

[Video](https://www.youtube.com/v/TVa-T8aLgbA)

### Envers 支持

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

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

使用 JPA Designer 为 JPA 实体及其字段添加  `@Audited` 注解：

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

#### 修订实体

Hibernate 将所有已审核实体的所有版本存储在单独的表中。 默认情况下，每个新修订版本都会分配一个修订号和时间戳。 如果您想创建一个自定义修订实体并且没有任何实体用  `@RevisionEntity` 注释，JPA Buddy 为此提供了一个方便的对话框。

![revision-entity-action](https://resources.jetbrains.com.cn/help/img/idea/2026.3/revision-entity-action.png)

在  创建修订实体 向导中，JPA Buddy 允许您指定：

1.  父级实体（例如，  `DefaultRevisionEntity`  或  `DefaultTrackingModifyingEntitiesRevisionEntity` ）。

2.  表的名称。

3.  是否创建一个修订监听器或选择一个现有的监听器。

4.  如果未指定父节点，则需要修订号和时间戳字段。

5.  实体将要保存的源根和包。

![create-revision-entity-wizard](https://resources.jetbrains.com.cn/help/img/idea/2026.3/create-revision-entity-wizard.png)

给定的配置将生成以下代码：

```JAVA
public class CustomRevisionEntityListener implements RevisionListener {
      @Override
      public void newRevision(Object revisionEntity) {
          CustomRevisionEntity customRevisionEntity = (CustomRevisionEntity) revisionEntity;
          // TODO ("Not yet implemented")
      }
  }

  @Entity
  @Table(name = "revinfo")
  @RevisionEntity(CustomRevisionEntityListener.class)
  public class CustomRevisionEntity {
      @Id
      @RevisionNumber
      @Column(name = "id", nullable = false)
      private int id;

      @RevisionTimestamp
      @Column(name = "timestamp", nullable = false)
      private long timestamp;

      //getters and setter are omitted
  }

```

## 检查

JPA Buddy 提供了许多有助于编码的检查。 默认情况下，所有检测在所有范围内都启用，并且具有警告严重级别。 您可以在设置 -> 编辑器 -> 检查 -> JPA Buddy 中查看并配置提供的检查完整列表。

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

## 设置

### 命名模板

Java 代码样式可能因项目而异。 此外，在使用外部数据库时，您需要遵循表、列等的命名约定，以便将它们映射到 JPA 实体。 JPA Buddy 为您提供灵活的命名模板配置，这些配置会自动应用于新的实体和属性。

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

> **Note:**
> 指定的名称是逻辑名称，将应用适当的物理命名策略。 即使您以某种方式指定了名称，它也可能以不同的名称保存到数据库中。 详细了解命名策略，请参阅 [我们的文章](https://www.jpa-buddy.com/blog/hibernate-naming-strategies-jpa-specification-vs-springboot-opinionation/)。 JPA Buddy 允许您在 [设置](database-versioning.html)中选择脚本生成的命名策略。

默认情况下，Spring Boot 使用 SpringPhysicalNamingStrategy 配置物理命名策略。 该实现提供与 Hibernate 4 相同的表结构：所有点都被替换为下划线，且 camel casing 也被替换为下划线。 此外，默认情况下，所有表名都是小写生成的。 例如，对于下面的两个实体声明，数据库表的实际名称将是 pet_type。

```JAVA
@Entity
  public class PetType {
      // fields omitted
  }

```

或

```JAVA
@Entity
  @Table(name = "PetType")
  public class PetType {
      // fields omitted
  }

```

### 常量生成

可维护性是任何项目的重要方面，而 JPA 项目通常包含众多涉及 JPQL 或原生查询语句、属性引用、查询和绑定参数名称的字符串。 根据最佳实践，保持持久层结构良好的方法之一是使用常量。 您可以在 [Thorben Janssen](https://thorben-janssen.com/hibernate-best-practices-for-readable-and-maintainable-code/)的文章中了解相关信息。

[Video](https://www.youtube.com/v/xc-ayDDdjss)

JPA Buddy 为实体、表和列名称提供常量生成。 您还可以选择放置常量的位置。

![常量生成](https://resources.jetbrains.com.cn/help/img/idea/2026.3/constants-generation.jpeg)

### 设计器设置

JPA Buddy 在默认模式下配备了功能丰富的工具窗口。 然而，对于屏幕较小的用户来说，工具窗口可能会占用大量的水平空间。 在这种情况下，JPA Buddy 提供了 [minimalistic mode](jpa-buddy-minimalistic-mode.html) 作为一个选项。 此外，JPA Buddy 提供了设置，您可以微调主要视觉元素的外观：

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