实体设计器

Studio 提供一个可视化设计器，用于简化 实体 的创建过程，因此，不需要记住实体创建的所有规则和注解。

此功能需要快速开发版或企业版 订阅。如果没有订阅，请尝试 试用版。

JPA 实体设计器

使用 Jmix 工具窗口 中的菜单新建 JPA 实体。

entity tree

JPA 实体创建会弹出 New JPA Entity 对话框。

entity create

填写下列字段：

  • Class - 类名称。必须符合 Java 名称规范。

  • Package - 类所属的包名。字段默认展示自动获取的包名。可以进行修改，点击 OK 后 Studio 会创建相应的包。

  • Entity type - 选择实体类型：

    • Entity - 数据模型 实体。

    • MappedSuperclass - 超级父类，不与任何特定数据库表关联。这种类使用了 @MappedSuperclass 注解。

    • Embeddable - 一个可嵌入的持久化实体。这种类使用 @Embeddable 注解。

  • Parent - 新建类的父类。

  • Id type - 选择实体主键的类型：

    • UUID - UUID 类型的标识符。

    • Long - Long 类型的标识符。强烈建议添加 UUID 特性，这样能启用一些优化并且支持在分布式环境唯一确定实体实例。

    • Integer - Integer 类型的标识符。强烈建议添加 UUID 特性，这样能启用一些优化并且支持在分布式环境唯一确定实体实例。

    • String - String 类型的标识符。强烈建议添加 UUID 特性，这样能启用一些优化并且支持在分布式环境唯一确定实体实例。具体的类实现中，必须要有一个字符串类型的字段使用 @Id JPA 注解。

    • Embedded - 主键是组合键。此时，具体类实现类中需要必须要有一个用于表示键值的可嵌入类型字段，使用 @EmbeddedId JPA 注解。

  • Id value - 当使用 UUID id 类型时，该字段会启用，并且设置为 Generated By Jmix（由 Jmix 自动生成）值。一般情况下，Id value 下拉框有下列选项：

    • Generated By Jmix， 实体的 id 具有 @JmixGeneratedValue 注解。

    • Identity column，仅适用于 id 类型为 Integer 和 Long。实体的 id 带有 @GeneratedValue JPA 注解，使用 GenerationType.IDENTITY 策略。Identity column 用于自增式标识符。强烈建议添加 UUID 特性，这样能启用一些优化并且支持在分布式环境唯一确定实体实例。

    • Assigned by user - 由用户设置 id。适合 Integer、Long、String 和 Embedded id 类型。

  • Id length 会在选择 String 类型时出现。指定字符串的最大长度。默认为 255。

  • Composite id type 会在选择 Embedded 类型时出现。选择可嵌入实体作为组合键值。

  • 在 Traits 复选框组中，选择需要的实体 特性。

然后点击 OK。

Studio 为新建的实体展示实体编辑器，其中有三个标签页（底部）：

  • Text 包含实体的源代码。

  • Designer 显示实体结构。这里可以为实体添加属性，设置实例名称、继承 策略和实体验证，这都是通过图形界面完成，不需要编写 Java 代码。

  • Indexes displays indexes and allows you to create new ones.

操作面板

操作面板位于实体编辑器的顶部。可以使用下列操作：

  • Screens - 导航至当前实体的已有界面或者创建 新界面。

    entity designer create screen

  • Event Listeners - 导航至当前实体的已有的 事件监听器 或新建监听器：

    entity designer create listener

  • Lifecycle Callbacks - 添加生命周期回调方法的桩代码：

    entity designer lifecycle callbacks

Designer 标签页

Designer 标签页展示实体的结构：

entity designer designer

除了在 JPA 实体设计器 对话框中的那些字段外，Designer 标签页还包含下列字段：

  • 实例名称 下拉框。

  • DB view 复选框。使用这个复选框可以将一个 JPA 实体映射至数据库视图（view）。这种实体类使用 @DbView 注解。

  • DDL Generation Settings 按钮打开 @DdlGeneration 注解值的可视化结构展示：

    ddl generation

  • Traits 按钮打开包含 实体特性 的对话框：

    traits

  • 在 Inheritance 下拉框中，可以选择 继承 策略。

Attributes 面板包含管理实体属性的操作：

  • Add（add）按钮打开 New Attribute 对话框。

  • 点击 Copy（copy）按钮复制已有属性用于创建新属性。

  • Add to Screens（add attribute to screens）按钮打开一个对话框，显示能展示目前实体的所有界面，在这里选择需要展示当前选中属性的界面。

    attributes collection modified

  • 点击 Remove（remove）按钮删除选择的属性。

  • 使用 Up（move up）/Down（move down）按钮对属性进行排序。

实体设计器右侧的面板展示所选实体属性的配置：

  • 使用 Name 字段旁的地球仪（main message pack）按钮可以为属性设置可读的名称。

  • Attribute type 和 Type 下拉框可以选择 实体属性的类型。

Validation 面板用于定义 bean 验证 约束。点击所选约束旁边的按钮可以打开编辑器：

email validation

Text 标签页

在 Text 标签页中，可以看到由设计器生成的实体类代码。

entity designer text

如果你之前有 JPA 经验，则可以看到一些熟悉的注解：@Entity、@Table、@Column 等。还有一些是 Jmix 特定的注解。其中最重要的是 @JmixEntity 类注解。一般来说，在 Jmix 中只要使用了 @JmixEntity，任何 POJO 都可以作为实体。

实体类的代码可以手动编辑，编辑结束后切换至 Designer 标签页，会同步展示变化。例如，如果从某个属性删除 nullable = false 和 @NotNull，则设计器中会不再勾选 Mandatory 复选框。

操作面板位于源码编辑器的顶部。除了 上面介绍 的操作外，还有下列操作：

  • Add Attribute - 打开一个 New Attribute 对话框。

  • Add Attributes to Screen - 打开一个 Add Attributes to Screen 对话框，显示能展示目前实体的所有界面，在这里选择需要展示当前选中属性的界面。

    add attribute to screens

Indexes 标签页

Indexes 标签页用于定义实体的 唯一索引。

entity designer index

如需创建一个新的索引，点击 Database Indexes 工具栏的 New Index（add）按钮。Studio 会在索引列表新增一行。

在 Available attributes 列表中选择一个或多个实体属性，点击 arrow right 将选择的属性移至 Selected attributes。

在索引的表格行中勾选 Unique 或 Constraint 复选框。

添加属性

可以点击 Designer 标签页中的 + 按钮添加属性，在弹出的对话框中配置属性。下面的示例中，添加了 Attribute type 为 ASSOCIATION 的 addresses 属性。这里，对于一对多 引用，需要在 Address 实体中创建反向关联属性。

entity association

Name 字段右侧的地球仪按钮可以支持设置属性的用户友好名称。名称保存在 messages.properties 文件中，UI 组件默认使用这里的名称。

entity message

此外，在 Text 标签页时，通过点击顶部或 Generate 弹窗中的 Add attribute 按钮打开属性创建窗口。

entity generate

创建实例名称

当为实体添加某个属性时，Studio 会自动为实体设置一个 实例名称，这个属性的名称需要是这些之一：name、title、caption、label、summary、description、firstName、lastName、middleName。

entity instance auto

当需要使用其他属性生成实例名称时，可以使用可视化构建器，通过点击 Instance name 字段的小铅笔按钮打开。

entity instance editor

实例名称也可以在 Text 标签页创建。将光标放置于类的名称上，按下 Alt+Enter（⌥↩）并选择 Add instance name。

entity instance text

DTO 实体设计器

如需创建 DTO 实体，在 Jmix Tool Window 中点击 New（add）→ DTO Entity。弹出 New DTO Entity 对话框。

dto entity

展示的字段与 JPA 实体 类似。填写完后点击 OK。

Studio 为 DTO 实体展示两个标签页。

  • Text 包含 DTO 实体的源码。

  • Designer 展示实体的结构。

枚举设计器

Studio 提供一组操作和可视化设计器，能帮助使用枚举。通过 Jmix 工具窗口 中的菜单项创建枚举。

entity tree

当枚举创建完成后，会在编辑器打开枚举类，其中有两个标签页。

entity enum editor

  • Text 包含源代码。

  • Designer 展示枚举设计器，可以配置枚举类型和枚举值，使用图形化界面而无需编写 Java 代码。

在 Values 表格使用相关按钮设置枚举值常量。

  • Name 列可以输入代码中使用的枚举常量名称。后续可以修改名称而不影响数据库已经存在的值。

  • Value 列可以输入枚举常量的 id。这是存储在数据的实际值。

地球仪按钮可以用来为选中的枚举常量设置本地化名称。

设计器也支持修改枚举使用的 Id 类型，可以在 String 和 Integer 之间切换。Studio 会自动修复代码中使用的地方。然后，你可以修改枚举常量的值。

这种自动迁移过程不会修改数据库表中已经保存的枚举值，需要手动修改。