# DTO Generator

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

DTO（数据传输对象）是一个在进程之间传递数据的对象。 用于 JPA 实体的 DTO 通常包含实体属性的一个子集。 例如，如果您只需要通过 REST API 暴露实体的几个属性，您可以将实体映射到包含这些属性的 DTO，并且只序列化它们。 基本上，DTO 使您能够将表示层/业务逻辑层与数据访问层解耦。

JPA Buddy 提供通过可视化设计器从 JPA 实体生成 DTO：

[Video](https://www.youtube.com/v/qpnM_k-TGFk)

## DTO 生成选项

在创建 DTOs 时，JPA Buddy 提供了以下选项供您选择：

* Java record — 生成一个 DTO 作为 Java record，提供 DTO 的简洁且不可变的表示，并自动实现 `equals()` 、 `hashCode()` 和 `toString()` 。

* 全参数构造函数——生成一个接受 DTO 所有字段参数的构造函数。

* equals() 和 hashCode()——根据其字段生成 DTO 的 `equals()` 方法和 `hashCode()` 方法。

* toString() – 为 DTO 生成 `toString()` 方法，提供其字段的字符串表示。

* 默认情况下，生成的 DTO 是不可变的，带有 final 字段并且没有 setters。 如果您需要带有私有字段和设置器的可变 DTO，您可以检查此选项。

* 流式 setter – 选择 Mutable 选项时，此选项可用。 它允许生成的 setters 返回 `this` 而不是 `void` ，从而使多个 setter 调用实现方法链。

* 对于 json 忽略未知属性——将 `@JsonIgnoreProperties(ignoreUnknown = true)` 注解应用于 DTO，使其在 JSON 反序列化过程中忽略任何未知属性。 仅当项目中包含 [Jackson Annotations](https://mvnrepository.com/artifact/com.fasterxml.jackson.core/jackson-annotations/2.15.1)依赖项时可用。

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

## Lombok 支持

JPA Buddy 通过以最优方式提供 Lombok 支持来简化 DTOs 的生成。

例如，当您在 DTO generator wizard 中选择  `全实参构造函数` 、  `equals() 与 hashCode()`  和  `toString()`  选项时，JPA Buddy 会将  `@Value`  应用于生成的 DTO，丢弃多余的访问修饰符，以保持代码整洁。

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

```JAVA
@Value
public class OwnerDto implements Serializable {
    String firstName;
    String lastName;
    String telephone;
}

```

如果您需要一个与上述示例中参数相同的 [mutable DTO](https://jpa-buddy.com/documentation/dto-generator/#mutability)，JPA Buddy 将添加  `@Data` 、  `@AllArgsConstructor` 和  `@NoArgsConstructor` 注解。

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

```JAVA
@Data
@AllArgsConstructor
@NoArgsConstructor
public class OwnerDto implements Serializable {
    private String firstName;
    private String lastName;
    private String telephone;
}

```

> **Tip:**
> 要使用此功能，请确保将 [Lombok dependencies](https://mvnrepository.com/artifact/org.projectlombok/lombok) 添加到您的项目中，并在 [DTO Declaration Settings](#dto-declaration-settings) 中启用它。

## 关联的内部 DTO

实体可以通过关联引用其他实体，JPA Buddy 允许您在同一窗口中为引用的实体生成 DTO。 只需检查树中的引用实体，选择 DTO 类型并选择所需的字段。

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

让我们看看可用的 DTO 类型：

* 新类——将在一个单独的文件中创建一个新类。

* 新的嵌套类——将创建一个新的 public static 嵌套类。

* 现有类——您可以选择项目中已存在的 DTO 类。

* Flat – 所有内部类字段将成为顶级类字段。 生成的实体名称将由内部类名称与字段名称组合而成。

## Java 记录支持

如果您在项目中使用 SDK 版本 16 及更高版本，那么 JPA Buddy 将在   Java 记录  向导中的   新建 DTO  提供一个额外的复选框。 要检查项目的 SDK 版本，请打开  `文件 | 项目结构` 。

![项目结构](https://resources.jetbrains.com.cn/help/img/idea/2026.3/project-structure.png)

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

## 从 POJOs 生成实体

JPA Buddy 提供了一项  Entity from POJO  操作，帮助从任何 java/kotlin 类生成 JPA 实体。 如果您按照 API-first 方法开发应用程序，此功能可能会有所帮助：首先为 API 定义 DTOs，然后再实现数据模型。

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

JPA Buddy 的显著功能是能够检测关系的基数，生成相关实体或选择现有实体：

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

## 从任何 Java/Kotlin 类生成 DTO

如今，DTO 模式在软件开发中被广泛使用。 它不仅可以与 JPA 实体一起使用，还可以与常规 POJO 类一起使用。 使用 JPA Buddy，您不仅限于将 DTO 与 JPA 实体一起使用。 您可以从任何 Java 或 Kotlin 类创建 DTO，这为您的代码提供了更多的灵活性和控制权。 例如，查看使用 JPA Buddy 处理 MongoDB 文档是多么容易：

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

## MapStruct 支持

[MapStruct](https://mapstruct.org/) 是一个极大简化映射实现的代码生成器。 如果您的项目包含相应的依赖项，   Mapper 类   字段将出现在   新建 DTO   窗口中。 您可以选择现有的 Mapper 或创建一个新的。

> **Note:**
> 此功能适用于任何领域实体（任意 Java/Kotlin 类），而不仅限于 JPA 实体。

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

JPA Buddy 会分析 MapStruct mappers ，并可以定义哪个 DTO 与哪个实体关联。 正因如此，您可以在对应部分查看 DTO，并通过装订区域图标在实体和 DTO 之间导航。

### 映射方法

同时，如果您希望拥有一个包含所有实体方法的大型 mapper 接口，JPA Buddy 也可以提供帮助。 在这种情况下，在打开的 mapper 类中使用 IntelliJ IDEA   生成菜单   ( `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))) 并为任何实体创建方法。

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

### 通用映射器继承

MapStruct 允许声明泛型 mappers：

```JAVA
public interface EntityMapper<D, E> {
    E toEntity(D dto);

    D toDto(E entity);

    List<E> toEntity(List<D> dtoList);

    List<D> toDto(List<E> entityList);
}

```

这样的映射器作为所有其他映射器的父级使用起来很方便，并且保持它们简洁清晰：

```JAVA
@Mapper(componentModel = "spring")
public interface UserMapper extends EntityMapper<UserDTO, User> {}

```

不过，如果需要，可以轻松地添加复杂的映射逻辑：

```JAVA
@Mapper(unmappedTargetPolicy = ReportingPolicy.IGNORE, componentModel = "spring")
public interface ProjectMapper extends EntityMapper<ProjectDTO, Project> {
    @AfterMapping
    default void linkTasks(@MappingTarget Project project) {
        project.getTasks().forEach(task -> task.setProject(project));
    }
}

```

JPA Buddy 支持泛型 mapper 的继承：

[Video](https://www.youtube.com/v/ZcY-dDWqihg)

### Mapper 声明

JPA Buddy 提供了灵活的映射器声明设置。 要配置命名模式或映射集合命名策略，请打开  `工具 | JPA Buddy | Mapper 声明` :

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

## ModelMapper 支持

[ModelMapper](https://modelmapper.org/) 是将实体转换为 DTO 或反过来转换的最最受欢迎的的库之一。 JPA Buddy 提供许多功能，使映射过程更加简化，包括：

1.

生成自定义映射方法。

2.

提供代码脚手架，以使用后缀自动完成将单个实体或实体集合映射到 DTO 及其反向映射。

3.

启用 ModelMapper bean 实时注入到相关类中。

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

> **Note:**
> JPA Buddy 假定您已在项目中声明了 ModelMapper bean。

## Blaze Persistence 实体视图支持

[Blaze-Persistence](https://persistence.blazebit.com/) 是一个功能强大的 Java 应用程序持久化框架。 它提供高级查询和优化技术，以 Simplify 数据访问开发并提高开发者生产力。 JPA Buddy 支持此框架以为 JPA 实体创建实体视图，只要 [相关库](jpa-buddy.html#dependencies)包含在项目中。

您可以通过以下步骤创建一个 Entity View：

1.   `JPA 结构 | 加号按钮 | Blaze Persistence 实体视图`

2.   `JPA 设计器 | 加号按钮 | Blaze Persistence 实体视图`

3.   `编辑器工具栏 | DTO 和 Spring Data 投影 | 创建 Blaze Persistence 实体视图`

4.   `项目 | 新建 | 其他 | Blaze Persistence 实体视图`

之后，将会打开一个用于创建 Entity View 的对话框。 除了标准的配置选项，如包名或源根，您还可以配置：

1.  父实体视图

2.  将要为其创建实体视图的 JPA 实体

3.  实体视图类名

另外，您可以通过相应的复选框将 Entity View 设置为 creatable 或 updatable。

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

与其他类型的 DTO 类似，JPA Buddy 提供了配置 [关联的内部实体视图](#inner-dtos-for-associations)的功能。

因此，上述配置将生成以下 Entity View：

```JAVA
@EntityView(Person.class)
@UpdatableEntityView
@CreatableEntityView
public interface PersonView extends BaseView {
    @IdMapping
    Long getId();

    void setId(Long id);

    String getName();

    void setName(String name);

    int getAge();

    void setAge(int age);

    @Mapping("posts.id")
    Set<Long> getPostIds();

    void setPostIds(Set<Long> postIds);
}

```

所选的复选框生成了  `@UpdatableEntityView`  及  `@CreatableEntityView`  注释。 请注意，可更新或可创建的实体视图需要一个用 @IdMapping 注解标记的属性。 因此，一旦您勾选其中一个复选框，JPA Buddy 将自动选择实体中带有  `@Id` 注解的属性。 另外，可更新或可创建的实体视图将为所有属性提供设置器。

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

## 保持 DTOs 与 JPA 实体同步

### 重构属性

DTO 常用于 API 控制器级别，以定义客户端所需的字段。 这就是为什么 DTOs 几乎复制了它们实体的结构。 有一些最受欢迎的的框架可以将实体映射到 DTO，并反之亦然：MapStruct 和 ModelMapper。 它们自动映射同名属性。 然而，更改实体中的属性名称通常会导致映射逻辑损坏。 JPA Buddy 帮助开发者重构实体属性及其在 DTO 中的相关字段：

[Video](https://www.youtube.com/v/AY-lB-uKDDE)

### 添加属性

如果您恰好为实体添加了一个新属性，相应的 DTO 可能也需要用这个新字段进行更新。 JPA Buddy 使您能够一次性向所有必需的 DTO 添加一个新字段。 此外，如果您更喜欢手动编写代码而不是使用向导，JPA Buddy 也可以帮助您！ 只需开始输入在您的 DTO 中不存在的字段名称，它将被正确添加到类中。 最棒的是，它甚至可以与 associations 一起使用！

> **Note:**
> 此功能适用于任何领域实体（任意 Java/Kotlin 类），而不仅限于 JPA 实体。

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

## DTO 声明设置

![dto-declarations-preferences](https://resources.jetbrains.com.cn/help/img/idea/2026.3/dto-declarations-preferences.png)

每个项目可能遵循其自己的代码编写约定。 在 工具 | JPA Buddy | DTO Declaration 中，您可以配置：

1.

可序列化类型。

2.

类名后缀。

3.

是否使用 Lombok。

4.

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

```JAVA
//DTO for the {@link io.jpabuddy.demo.entities.Project} entity

```

5.

类名正则表达式。 此选项对遵循必需的 DTOs 命名约定非常有用。 它允许 JPA Buddy 仅使用 DTO 名称将 DTO 与其 JPA 实体关联。 您可以使用  `(?<entity>.)` 模式为目标 JPA 实体的简单类名指定占位符。 例如，  `(?.)Dto`  表示  `MyEntityDto`  类将被视为  `MyEntity`  的 DTO。 当字段为空时，此功能被禁用。

6.

类注释。 定义将在 DTO 类上生成的注释。

### 验证规则

JPA Buddy 提供在其专用的 DTO 生成向导中为 DTO 字段无缝配置 bean 验证约束。 除了从头开始定义验证外，您还可以自动从相应的实体中转移验证，并在同一个向导中管理它们。

![dto-validation-rules](https://resources.jetbrains.com.cn/help/img/idea/2026.3/dto-validation-rules.png)

通过启用或禁用每个约束并自定义验证消息，这一全面的功能使您能够方便地管理DTO字段的所有 bean 验证约束，确保您的应用程序具有一致性和可重用性。

> **Tip:**
> 要启用验证列表，必须包含 [Hibernate Validator](https://mvnrepository.com/artifact/org.hibernate.validator/hibernate-validator) 或 [Spring Boot Starter Validation](https://mvnrepository.com/artifact/org.springframework.boot/spring-boot-starter-validation) 依赖项。

### 在实体及其 DTO 之间方便导航

一旦 JPA Buddy 将一个 DTO 类与其对应的实体关联起来：

* 该 DTO 类将显示在 JPA 结构选项卡中的 DTO & 投影 部分以及编辑器工具栏中（1）

* 在 DTO 类中会出现一个 间距图标，为您提供便捷的方式导航到其关联的实体 (2)

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