实体设计器

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

此功能可在最多 10 个实体和角色的小项目中免费使用。在大项目中,需要快速开发版或企业版 订阅^

JPA 实体设计器

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

new

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 类型为 IntegerLong。实体的 id 带有 @GeneratedValue JPA 注解,使用 GenerationType.IDENTITY 策略。Identity column 用于自增式标识符。强烈建议添加 UUID 特性,这样能启用一些优化并且支持在分布式环境唯一确定实体实例。

    • Assigned by user - 由用户设置 id。适合 IntegerLongStringEmbedded id 类型。

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

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

  • Traits 复选框组中,选择需要的实体 特性

然后点击 OK

Studio 为新建的实体展示实体编辑器,其中有三个标签页(底部):

  • Text 包含实体的源代码。

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

  • Indexes 配置索引。

操作面板

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

  • Views - 导航至当前实体的已有视图或者创建 新视图

    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 下拉框中,可以选择 继承 策略。

  • 使用 Comment 编辑链接可以为实体添加 备注

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

  • Addadd)按钮打开 New Attribute 对话框。

  • 点击 Copycopy)按钮复制已有属性用于创建新属性。

  • Add to Viewsadd attribute to screens)按钮打开一个对话框,显示能展示目前实体的所有视图,在这里选择需要展示当前选中属性的视图。

    attributes collection modified
  • 点击 Removeremove)按钮删除选择的属性。

  • 使用 Upmove up)/Downmove down)按钮对属性进行排序。

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

  • 使用 Name 字段旁的地球仪(globe)按钮可以为属性设置可读的名称。

  • Attribute typeType 下拉框可以选择 实体属性的类型

  • 使用 Comment 编辑链接可以为实体属性添加 备注

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 Views - 打开一个 Add Attributes to Views 对话框,显示能展示目前实体的所有视图,在这里选择需要展示当前选中属性的视图。

    add attribute to views

Indexes 标签页

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

entity designer index

如需创建一个新的索引,点击 Database Indexes 工具栏的 New Indexadd)按钮。Studio 会在索引列表新增一行。

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

在索引的表格行中勾选 UniqueConstraint 复选框。

添加属性

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

entity association

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

entity message

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

entity generate

创建实例名称

当为实体添加某个属性时,Studio 会自动为实体设置一个 实例名称,这个属性的名称需要是这些之一:nametitlecaptionlabelsummarydescriptionfirstNamelastNamemiddleName

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

entity instance editor

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

entity instance text

DTO 实体设计器

如需创建 DTO 实体,在 Jmix Tool Window 中点击 Newadd)→ DTO Entity。弹出 New DTO Entity 对话框。

dto entity

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

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

  • Text 包含 DTO 实体的源码。

  • Designer 展示实体的结构。

枚举设计器

Studio 提供一组操作和可视化设计器,用于设计枚举。点击 Jmix 工具窗口 中的 Newadd)→ Enumeration 创建 枚举

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

entity enum editor
  • Text 包含源代码。

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

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

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

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

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

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

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