CUBA Studio 用户向导

前言

本手册提供了 CUBA Studio IDE 以及其功能的参考信息，CUBA Studio IDE 有助于提高基于 CUBA 框架的应用程序的开发效率。

CUBA Studio 基于开源的 IntelliJ Platform，并通过以下 CUBA 特有的功能对其进行扩展：

创建 Gradle 构建脚本的脚手架代码。
创建数据模型、数据库架构和 CRUD UI 的脚手架代码。
WYSIWYG 界面布局设计工具。
对开发人员友好的功能，加快编码过程，包括：动作(action) 、推断(intention) 、检查(inspection)、引用(reference)。
轻松支持国际化。
为现有的（或遗留的）数据库创建数据模型和 UI 界面。
热（重新）部署。
使用 CUBA 框架和扩展的版本升级更加容易。

IntelliJ Platform 为 CUBA Studio 提供了强大的基础。包含很多可以提升 CUBA 开发者生产力的功能，比如非常人性化的用户界面，智能代码补齐，安全的代码重构，后台代码检查，内置的版本控制以及对 Gradle 的集成。如果您之前没有使用过 IntelliJ IDEA，我们强烈推荐您访问其网站的学习 & 支持部分，快速了解其基本功能。

发行说明

版本 15

支持通过环境变量配置数据库连接参数（支持 CUBA 版本大于 7.2.7）。能避免将这种敏感信息保存在版本控制中。参考用环境变量做连接参数了解细节。
CUBA 项目树添加了新的 All Sources 部分。这里展示项目模块中未按文件类型过滤的所有源文件。开发者可以在这里找到那些没有包含在特定项目部分（服务、界面控制器、实体等）中的文件或类。
支持按照月份对数据库更新脚本进行组织。对于大型项目团队来说，目前仅按照年份目录对数据库更新脚本进行分组可能不方便。所以我们添加了新的配置：CUBA → Settings → Group update scripts by。当这个设置改为 MONTH 时，新的更新脚本会按照月份目录进行分组（比如 /2020/10/、/2020/11/ 等）。注意，目前已经存在的更新脚本无法重新分组。
添加了 zipProject Gradle 任务的 UI，可以通过主菜单 CUBA → Advanced → Zip Project 调用。该任务用来打包代码，以便发送。
目前的 Subscribe to Event 和 Install Delegate 对话框合并成了一个，这样方便使用。
修改平台版本的功能从 Project Properties 迁移到了单独的对话框内。单独的对话框现在也显示相关平台版本的 release notes。
改进了安装试用版和正式版商业扩展插件的 UI。一些复杂的情况也能自动处理（比如，商业扩展插件上传至自定义的仓库）。
支持显示标准操作的描述。描述显示在创建操作和创建表格向导的对话框中，表格创建向导中以 tooltip 展示。
为一个常见问题添加了探查器，即，当用户手动在 build.gradle 添加 appComponent 依赖，却忘了在 web.xml 文件注册扩展插件。
支持在 IDE 中修改 ~/.gradle/gradle.properties 文件。使用主菜单的 CUBA → Advanced → Edit Gradle properties 操作修改 Gradle 全局设置。
Studio 独立版中的 IDE 升级到 IntelliJ 社区版 2020.2。之前下载的独立版不会自动升级，您需要从 CUBA 平台网页手动下载并更新。
其他小改进和 bug fixes：
- Studio 15.0 解决的问题

版本 14

添加了能跟踪附加数据存储数据库 schema 改动的功能（平台版本 7.2.0 以上）。要为数据存储启用自动生成迁移脚本的功能 - 使用 Data Store Properties 对话框的单选按钮组：

支持以下数据库 schema 管理模式：
1. Disabled - Studio 不跟踪该存储的数据库结构变化。这是默认模式，以前版本的 Studio 也是这个行为。
2. Update Only - Studio 能生成数据库更新脚本并能根据数据模型更新数据库。但是，Studio 没法重新创建数据库。该模式应该用在数据库不是由 CUBA 完全控制的场景，比如，数据库是与其他应用程序共享的。
3. Create and Update - Studio 创建完整的 初始化 和更新数据库的脚本，并提供从头创建数据库的能力。该模式可用在数据库由 CUBA 应用程序完全控制的场景。
如果您的项目有附加数据存储，并且启用了数据库 schema 管理，则 Database Scripts 窗口会显示所有数据存储的脚本：

还有，New CUBA Entity 对话框可以在注册新实体的时候指定数据存储了：
添加了新的设计时角色可视化设计器（平台版本 7.2.0 以上）。用这个界面可以方便的构建角色定义，指定角色配置，比如界面和菜单权限、实体 CRUD 权限、实体属性权限以及特殊权限。
设计时角色定义现在在 CUBA 项目树的 Security 部分展示。

如需创建新的角色定义，使用 Security 的右键菜单 New → Role：
支持可视化编辑特殊权限和分类配置。该功能集成在设计时角色编辑器内的 Specific 标签页：
支持在 CUBA 项目树的 Logging 展示本地调试 Tomcat 服务的日志文件：
支持自定义应用程序日志配置文件的功能（平台版本 7.2.0 以上）。如需创建自定义的 logback.xml 文件，使用 CUBA 项目树中 Logging 部分的 Generate Logback Configuration File 操作：

可按需修改生成的配置文件。本地 Tomcat 调试服务会使用该文件。在 WAR Settings 和 UberJAR Settings 窗口也会用作默认的日志配置文件。
中间件和 Web 集成测试也显示在 CUBA 项目树，位于 Business Logic → Tests 部分。
支持创建新的集成测试类。如需创建测试类，使用 Tests 部分的操作：New → Integration Test (Middleware) or Integration Test (Web)：
支持自定义界面模板。在 Create CUBA Screen 向导的第一步点击 Copy template 按钮创建自己的界面模板。模板文件会复制到项目，可以手动修改。自定义的界面模板展示在 CUBA 项目树的 Generic UI → Screens → Custom Templates 部分：

可以修改界面控制器和描述的模板文件，通过扩展 settings.xml 文件甚至可以为向导添加新的参数。New → Screen 向导的第一步中，Project Templates 标签页可以选择自定义的界面模板：
支持创建 EntityPersistingEvent 事件监听器的脚手架代码，操作添加至 Subscribe to Event 向导窗口：
New CUBA Bean 对话框支持开发者设定目标模块，除了在 core 生成 Spring bean 之外，还可以在 global，web 和 portal 模块生成：
Create CUBA Screen 向导界面做了扩展，增加了配置实体浏览界面和编辑界面的视图步骤。开发者现在可以直接在向导中选择需要的属性而无需另打开窗口选择了。选择的属性也会决定在浏览表格组件和编辑界面展示哪些字段：
在界面设计器支持 Form - 表单 创建向导。当用户在界面布局放置 Form 时会显示。这个葵花矿支持选择已有的或配置新的数据容器，同时可以设置 Form 的其他属性：
界面设计器的 Component Palette 面板允许开发者从工具箱拖拽组件至源代码。选中的组件会作为子组件添加至选中的 XML 标签。
简化了主菜单从 Composite 至 Single 模式的切换。菜单设计器现在支持开发者复制从平台和扩展组件继承的菜单项至项目配置文件。
实体设计器增加了额外的 DDL 生成设置。开发者现在可以为特定实体选择一种数据库脚本生成的模式：Create and drop，Create only，Disabled。现在还能设置那些没有实体字段的数据库列或约束，这样 Studio 不会 drop 掉它们。
提升了 Add new attributes to existing screens 功能和易用性，之前只能在源码的快捷操作中使用。现在可以在源码编辑器顶部的快捷操作面板使用了：

在实体属性表格上也添加了 Add to Screens 按钮完成相同的功能：
代码检查功能增加了检测 System.out.println 或 System.err.println 的使用。为开发者提供了快速修复（按下 Alt+Enter / Option+Enter），转换为使用注入或静态 SLF4J Logger 的语句：
代码检查为 "Entity is created by calling constructor" 添加了快速修复。按下 Alt+Enter / Option+Enter 可转换为调用 DataManager#create(Entity.class) 方法：
代码检查为 "GUI component is created by calling constructor" 添加了快速修复。按下 Alt+Enter / Option+Enter 可转换为调用 UiComponents#create(Component.class) 方法：
在界面设计器支持自定义组件 UI 元数据。通过在组件定义中添加特定的注解，可以将扩展插件或者项目中自定义的 UI 组件集成到 Studio 的界面设计器。参阅开发者手册了解跟多关于 UI 元数据的内容。
添加了对 CUBA 商店的支持。现在可以点击工具栏的 CUBA User Profile 按钮登录您的 CUBA 账号：

登录之后，您可以在 Marketplace 窗口下载和安装商业扩展插件的试用版。
大大缩短了 Generate Database Scripts 操作的处理时间。另外，CUBA Application 运行配置启动时的数据库结构检查时间也缩短了不少。
Studio 现在用 MariaDB connector 连接至 MySQL 和 MariaDB 数据库。因此，如果选择使用 MySQL，无需再手动下载驱动了。如果在某些情况下必须要使用 MySQL 驱动，可以在连接串添加 disableMariaDbDriver 参数启用。
Standalone 版本的 Studio 增加了默认内存使用的大小。现在默认使用 -Xmx1200m，以前是 -Xmx768m。
Standalone 版本的 Studio 升级到 IntelliJ Community 2019.3。之前下载的独立版本不会自动升级，需要从 CUBA 网站重新下载。
为中国区开发者做了下列基础设施的提升：
- 添加了新的 CUBA 仓库 https://nexus.cuba-platform.cn/repository/cuba/，位于中国。
- 市场内的扩展插件信息翻译成了中文。
- 优化了 Studio 使用的外部资源的位置，已达到更好的网络访问效果。
移除了 JxBrowser 浏览器。现在 Studio 使用 JavaFX 展示内嵌的 web 网页。显著减少了插件包的大小。
其他很多小的改进和 bug fix：

版本 13

界面设计器的布局重新排布了，主要为了以下目的：

高效的使用 IDE 窗口的空间。
便于在 XML 描述源码和布局预览之间切换。
允许熟练的开发者在查看和编辑 XML 代码时使用设计器的功能。

对界面设计器做了如下变更和改进：

界面设计器的面板修改为独立的 IDE 工具窗口。Component Hierarchy 展示在 IDE 的右上角，与之前一样。Component Palette 展示在 IDE 的右下角。Component Inspector 展示在 IDE 的左下角并包含属性和处理器标签页。

当在编辑器打开界面描述时，这些工具窗口会自动打开。当在编辑器切换界面描述文件时，工具窗口的内容会随之改变。有时当您打开其他的 IDE 工具窗口（比如 Gradle、Persistence 等），设计器的面板会被隐藏，可以通过点击位于左右的 IDE 工具窗口按钮重新打开。

保留在左下角展示 Component Inspector 是为了满足熟悉之前布局的开发者们。如果需要将该面板移至右侧，点击面板标题的 Move to Right Bottom 即可。
布局预览面板现在与界面描述的源码编辑面板共享编辑器的空间。去掉了原来的 Text 和 Designer 标签组。现在在界面描述的右上部添加了四个按钮用于切换界面预览模式：
1. Editor only - 在编辑器只显示源码。
2. Editor and Preview - 编辑器空间分割，包含源码和预览。
3. Preview only - 只显示预览（与之前版本的界面设计器布局类似）。
4. Preview in Window - 源码在编辑器展示，但是预览通过单独的窗口展示，可以将预览窗口移至其他显示设备。
当编辑 XML 代码时会激活设计器面板，面板会与编辑器同步交互。熟练开发者们通过编辑 XML 源码切换和修改界面描述，他们现在也能获得界面设计器的编辑功能帮助：
1. 当编辑器的光标从一个 XML 标签移至另一个标签时，会在 Component Hierarchy 和 Component Inspector 面板自动选中对应的组件。
2. 在层级面板点击元素会将源码编辑器的光标移至对应的 XML 标签。
3. 可以从工具箱拖拽新组件至层级树，当编辑器只显示源码时，也可以在左下角的探查面板修改组件的排序和编辑组件属性。源码会直接同步所有改动。
界面编辑器现在能在 Component Hierarchy 树中展示表格（或数据网格）的列。作为这个改动的一部分，删除了之前的几个用来编辑列和操作的弹窗。现在可以在 Component Inspector 面板直接查看和编辑列、操作属性以及事件处理器。添加新的列或者操作也变得更加容易了。当选中一个表格、表格的一列或者操作， Component Inspector 会显示 + Add 按钮。点击该按钮可以添加列或者操作。
界面设计器还添加了组件创建向导对话框。添加数据容器、表格、网格、表格的列、表格操作以及表单的字段组件变得更加容易了。

当为界面添加上面提及的任何一个组件时，会弹出一个对话框用来指定最重要的组件属性。比如，当为界面添加数据网格时，可以选择已有的数据容器或者创建新的数据容器，能设置组件 id 并且为网格选择一组标准操作和按钮。
界面设计器的 Component Hierarchy 面板添加了可以铜鼓输入文字查找组件的功能：
Component Hierarchy 面板的右键菜单也添加了额外的转换功能。现在可以快速的将 TextField 组件转换为 TextArea 或者其他组件：
Component Hierarchy 面板右键菜单的 Inject to Controller 操作现在支持可以同时注入多个选中的组件。

其他功能和改进：

添加了对 Kotlin 编程语言的支持。在项目创建向导中，如果选择的平台版本为 7.2.0 或更新版本，则可以选择 Kotlin 为项目的编程语言。CUBA 项目的所有元素：实体、界面、服务都可以用 Kotlin 生成。Studio 的可视化设计器、智能自动补全、自动检查以及热部署也都支持 Kotlin。
对于使用平台 7.2.0 或更新版本的项目，对 Hot Deploy 机制做了重写（支持所有语言），主要是为了支持 Kotlin。如果在 Java、Groovy 项目中遇到了热部署的问题，可以切换至之前的机制，通过关闭这个设置：CUBA → Settings → Project Settings → Hot deploy compiled classes。
扩展了 CUBA 项目创建向导。在几个步骤之间重新安排了各个字段，并且添加了新的字段：模块前缀、支持的语言、地区、主数据存储属性。
CUBA Application 运行配置添加了两个额外的配置：Command line arguments - 命令行参数 和 Environment Variables - 环境变量。这些设置会在 Tomcat 运行调试模式 CUBA 应用程序的时候生效。比如，通过设置命令行参数，可以配置非默认时区：-Duser.timezone=Europe/London 或者增加内存：-Xmx1500m。
为登录界面设计了新模板，新的布局和设计可以在基于 CUBA 7.2.0 或最新的版本的项目中使用。新的登录界面样式可以查看 GitHub 了解。如需在项目中添加新的登录窗口，可以在 New → Screen 向导中选择 Login screen with branding image 模板。
在 Project Properties 对话框中添加了修改项目工件版本的功能：
在服务和 Spring bean 源码的编辑器顶部操作面板中添加了 Inject 操作。之前只能在通用菜单（Alt+Insert）使用。
在 Data Store Properties 窗口添加了方便配置数据库连接的对话框。为 Connection params 字段添加了一个 “铅笔” 按钮，点击这个按钮，会弹出一个窗口用于配置连接参数。Studio 会考虑数据库特定的分隔符将参数转换为连接字符串：
Locales 对话框现在能根据可用的语言给出提示并根据选择的语言自动填充地区代码：
扩展了 Attribute is not included into the view - 属性未包含在视图中 的代码检查。现在还会检查关联了持久化属性的非持久化属性，这种关联是通过 @MetaProperty#related 注解参数指定的。
改进了 Studio 处理 Gradle 项目同步失败的行为。现在 CUBA 主菜单会一直显示，并包含附加的菜单项：
1. Re-Import Gradle Project 菜单项，可以用来处理一次性的网络访问故障。
2. Restore Project to the Latest State 菜单项，能将 Gradle 构建脚本恢复到上次成功导入的状态，这可以放置无意的或者错误的脚本修改。
独立版 Studio IDE 升级到 IntelliJ Community Edition 2019.2。之前下载的独立版 Studio IDE 不会自动升级，需要从 CUBA Platform 网站下载新的版本。
很多其他的小改进和问题修复：

版本 12

使用原生 IntelliJ UI 组件重新实现了界面设计器。新的设计器响应更快，打开也更快。设计器有了很多改进，下面会提到一些。
为设计器添加了一个新的 Handlers 标签页，放置在 Palette 和 Properies 标签页旁边。展示已有的方法以及所有可以使用的事件监听器和选中组件的代理方法。如要生成处理方法，只需双击相应的条目即可。
在界面设计器的顶部操作面板添加了 Preview 操作。能打开一个正在编辑的界面的预览窗口。该预览窗口的画布能跟踪 XML 编辑的改动，按照其布局变化自动更新预览界面。
在界面设计器的层级树的右键菜单中，添加了 Inject to controller 和 Go to XML 操作。
在层级树和组件工具箱的右键菜单中添加了 CUBA Documentation 操作。这些操作能打开 CUBA 开发者手册中相应的组件章节。
Form 组件的 Properties 标签页添加了 Add Column 按钮。
在 Validator 和 Formatter 界面设计器对话框中，添加了 class 字段类名的自动完成功能。
添加了各种应用程序事件监听器的脚手架代码功能。可以通过两种方式使用：
1. 打开已有的 Spring Bean，在源码编辑器顶部的操作面板中点击 Subscribe to event
2. 右键点击 CUBA 项目树的 Middleware，选择 New → Event Listener。
添加了项目级别的界面生成选项支持。这些设置会被用在 New → Screen… 界面向导中。如要修改这些设置，可以打开主菜单的 CUBA → Settings → Screen Generation Settings 进行修改。目前支持下列界面设置：
1. 表单组件的字段宽度（默认 450px），在实体编辑界面使用
2. 编辑器的操作按钮在界面底部，在 “全屏” 模式（非对话框模式）打开的实体编辑器中使用
3. 强制以模态窗打开编辑界面，以对话框模式打开的实体编辑器使用
在界面创建向导中可以设置该界面的菜单项名称。
可以为没有 id 的组件添加处理器脚手架代码。Studio 会在需要的时候要求开发者输入组件 id。
为界面控制器的操作面板添加了 Main Menu 操作。该操作可以将当前界面添加至主菜单或者配置导航至主菜单。
优化了 CUBA 项目树中 Deployment 部分的构建 WAR 和 UberJAR 的 UI。如果启用了相应的构建配置，现在只需通过双击 Build WAR 或 Build UberJAR 条目直接构建 WAR 或 UberJar。并且在项目树的 WAR/UberJAR Settings 元素旁边显示相应工件的配置文件（single-war-web.xml，logback.xml，jetty-env.xml 等），方便访问。
添加了能创建新的数据库创建、更新脚本的操作。在 CUBA 项目树的 Data Stores → Main Data Store 右键菜单中：
1. 初始化脚本： New → Database init script
2. 更新脚本： New → Database update script
在从界面控制器调用的 Install Delegate 对话框中，现在可以为表格的列生成 formatter、自定义列生成器或者 value provider。
为界面 XML 描述中的 icon 属性添加了自动提示，并在侧边糙提供图标预览。
为 LookupField 组件的 XML 属性 optionsEnum 添加自动提示。
UI 组件的 Quick Documentation 弹窗现在提供了至 CUBA 文档的链接：
实体设计器中的本地化语言对话框现在能为 Bean 验证自动生成消息键值，比如 "playground_Rank.queueSize.validation.Digits" 或 "playground_Tariff.taxType.validation.NotNull"。
为 Microsoft SQL Server (2012+) 数据库类型添加了 Integrated Security 选项的支持。注意，只对基于 CUBA 7.1.0+ 的项目有效。
大型项目的性能进一步提升（数据模型设计，view.xml 静态分析，CUBA 项目树）
最低支持的 IntelliJ IDEA 版本提升到了 2019.1。意味着如果您使用更早版本的 IDEA（或者 CUBA Studio），将无法升级 CUBA 插件至新版本。
很多其他的小改进和问题修复：

版本 11

添加了 "CUBA Add-ons" 界面，可以通过该界面管理项目中的扩展插件。可以在 CUBA 项目树双击 Project → Add-ons 或者从主菜单的 CUBA → Marketplace… 打开该界面。关于该界面的详细描述请参阅此章节。
添加了欢迎界面。简化了访问通用项目设置和操作的流程，并带有文档和社区网页的链接。
添加了管理第三方依赖库的 UI。在 Project Properties Editor 可以使用。
实体设计器已经使用 IntelliJ UI 组件进行了重构。新设计器有如下好处：
1. 更好的响应体验，打开速度更快
2. 对实体和其属性的改动会立即反馈到源代码
3. 集成了 IntelliJ 智能重构技术，比如 安全删除 实体属性
实施了实体属性的 安全删除 重构技术。如要开始重构，从实体设计器删除属性或在源码中右键点击该属性选择 Refactor → Safe Delete…。该重构动作会在视图、界面和其他的配置文件里面搜索此属性的使用情况。并能自动删除安全的地方，对需要手动修复的地方给出警告。
数据存储配置已经从 Project Properties 界面移出。现在数据存储配置可以在 CUBA 项目树的 Data Stores 部分查看和编辑。主数据存储的设置可以从主菜单 CUBA → Main Data Store Settings… 打开。请参考管理数据存储章节了解细节。
能使用 HSQLDB InMemory 作为附加数据存储。
支持使用 MariaDB 作为主或附加数据存储。
支持使用 Amazon Redshift 作为附加数据存储。
在实体源码编辑器的操作面板添加了 Add attribute。
支持 EntityChangedEvent 监听的操作也添加到了实体源码编辑器的操作面板。可以用来创建新的监听器或者导航至已经存在的监听器方法。
添加了 创建 CUBA EntityChangedEvent 监听器 脚手架代码的对话框。现在可以在一个类里面创建多个监听方法并选择两个额外的事件。
在实体设计器中支持更多的 BeanValidation 2.0 注解：@NotEmpty、@Positive、@PastOrPresent 以及其它。
当为实体添加属性时，实体设计器能自动识别属性名称是否能作为实体名称显示（name、caption、title 等），如果此时还未有实体名称的话，会自动生成 @NamePattern 注解。
视图设计器现在可以为已经存在视图更名，并对使用该视图的地方进行名称替换。
IDEA 的 Inject 'xxx' 快速修复提示现在可以根据变量名注入 bean - 扩展了其实现，可用于界面控制器和 Spring bean 的上下文中。使用该快速提示的方法示例：

要使用该功能，在 Spring bean 或者 CUBA 界面控制器中输入需要注入的 bean 的变量名。然后按下 Alt+Enter，在提示框选择 Inject 'beanName'。bean 的类名根据变量名自动关联，所以变量名必须跟 bean 接口的名称一致。比如：dataManager、fileStorageService、messageBundle 和 clusterManagerAPI，这些变量名会被识别并成功注入对应的 CUBA bean。
添加了 Java 代码检查器，检查使用 getMessage 和 formatMessage 方法指定的本地化字符串是否存在。

MessageBundle、Messages 和 AbstractWindow（旧界面）类的 getMessage 和 formatMessage 会使用该检查。如果指定键值的消息在指定的消息包中不存在，消息键值会高亮为红色。

如果按下 Alt+Enter 并选择 Create message in the message bundle 进行快速修复，Studio 会打开 Localization Message 对话框，用来为所有配置的项目 locale 输入本地化消息。
Studio 中独立的 IDE 版本已经升级至 IntelliJ Community platform 2019.1。之前下载的独立版本不会自动升级，您需要从 CUBA Platform 网站重新下载。
包含该版本的 IntelliJ IDEA 的 CUBA 插件已经上传至主插件（稳定）频道。所以不需要单独设置额外的插件仓库了。如果您使用的是之前版本的 CUBA Studio 插件，现在可以从 Custom Plugin Repositories - 自定义插件仓库 列表中移除 https://plugins.jetbrains.com/plugins/haulmont/list 了。自定义仓库列表在这里：File → Settings → Plugins → "gear" icon → Manage Plugin Repositories
其它很多小的改进和缺陷修复：

版本 10

实体、界面控制器和界面描述的代码编辑器顶部现在提供了一个工具栏，通过这个工具栏可以快速访问 CUBA 提供的操作、在相关文件之间快速跳转：

通过面板的按钮可以很快的切换到相关的 DDL 脚本、视图和界面。另外，还可以创建新视图、新界面以及JPA生命周期回调方法。

这些操作在 IDEA 的 “intentions” 菜单也同样提供了，这个菜单可以通过快捷键 Alt+Enter (Option+Enter) 调出：
实现了为 EntityChangedEvent 监听器创建脚手架代码的功能。在 CUBA 项目树选择一个实体类、包、或者最外层的 Middleware 节点，然后点击右键菜单中的 New > EntityChangedEvent Listener。Studio 会在 core 模块创建 Spring bean，带有两个监听器方法：分别在事务提交前和后收到通知。
实现了为 JMX bean 创建脚手架代码的功能。在 CUBA 项目树选择 Middleware 节点或者 Beans 节点下的一个包，然后点击右键菜单的 New > JMX Bean。
实现了为配置接口生成脚手架代码的功能。在 CUBA 项目树选择 Project > Config Interfaces 节点，然后点击右键菜单的 New > Configuration Interface。
Inject 对话框现在包含了 Project bean 的选择区域，这里可以注入任何项目中可用的 Spring bean。
使用 Groovy 编写的界面控制器也能使用 Inject 对话框了。
提升了依赖注入的体验：现在如果将光标放在方法体内并调出 Inject 弹窗，注入的字段定义会自动生成在类的顶部，而字段名会自动复制到光标处。
将组件注入控制器 的行为现在也能在组件的 XML 内做了。试试将光标放在XML中一个组件的元素上，然后按下快捷键 Alt+Enter (Option+Enter)。
实现了添加实体索引和唯一约束的可视化编辑器。可以在实体编辑界面的底部找到新的 Indexes 标签页。
实现了检查重复实体名称和表名的功能。如果为多个类定义了相同的实体名或者表名，则会在实体类显示提示。
实现了在实体的字段添加正确 JPA 注解的功能。简化了手动编写实体属性的工作：您在可以添加实体字段并生成 getters/setters 之后在该字段按下 Alt+Enter (Option+Enter)，即可看到相关选项。
在界面控制器代码中，如果注入了界面 XML 中不存在的组件，则会显示提示信息：
在实体类代码里，如果实体类没有 @NamePattern 注解的话，也会显示警告信息：

可以在类名处通过按下 Alt+Enter (Option+Enter) 快捷键修复问题或者屏蔽这个警告。
视图设计器现在使用了主从布局，视图列表在左边，选中的视图编辑在右边。
对基于 CUBA 7.1 以上版本的项目，添加了如下功能：
1. 能使用带侧边菜单和响应式侧边菜单的主界面模板。
2. 支持向声明式打开的界面和 fragments 传递属性参数。
3. 支持 REST API 扩展组件。
所有解决的问题：
- Studio 10.1 解决的问题
- Studio 10.0 解决的问题

版本 9

破坏性更改：Studio 现在使用 HSQL 2.4.1。当打开一个使用 HSQL 数据库的项目时，Studio 会提示升级项目文件 build.gradle 中的 HSQL 版本。如果同意，项目可以正确的用 Studio v.9+ 继续工作。但是，要注意以下问题：

带有新 HSQL 驱动的应用程序如果在带有旧 HSQL 驱动的之前版本 Studio 打开的话，有可能启动不了。

基于 CUBA 7.1 之前的使用 HSQL 的项目，计划任务会失效，因为之前版本的数据库表有一列叫 PERIOD，现在在 HSQL 2.4.1 中已经是保留字了。在 CUBA 7.1 里面重命名了该列。

Tip

如果您使用的是 CUBA 7.0 或者更低的版本，而且在开发阶段需要使用 HSQL 和计划任务，可以按照下面的步骤在 Studio 使用 HSQL 2.2.9:

退出 Studio。
复制 cuba-studio 目录：
- Windows 系统：从 C:\Program Files\Haulmont\CUBA Studio 2018.3\plugins\ 复制到 %userprofile%\.CubaStudio2018.3\config\plugins\
- MacOS 系统：从 /Applications/CUBA Studio.app/Contents/plugins/ 复制到 ~/Library/Application Support/CubaStudio2018.3/
在拷贝的 cuba-studio/lib 目录中，使用 hsqldb-2.2.9.jar 替换 hsqldb-2.4.1.jar。可以在这里下载。
启动 Studio 并打开项目。
在 build.gradle 中使用 def hsql = 'org.hsqldb:hsqldb:2.2.9' 替换 def hsql = 'org.hsqldb:hsqldb:2.4.1'。

至此，Studio 和项目都会使用 HSQL 2.2.9，基于 CUBA 7.0 和更低版本的应用程序便能在 HSQL 使用计划任务了。

热部署机制现在能同时部署更改的类依赖的所有类，这样不会在打开修改了的界面时弹出 ClassCastException。
当选择 MySQL 或者 Oracle 数据库时，Studio 会展示一个对话框，这里可以点击链接到供应商网站下载 JDBC 驱动，然后可以上传驱动至项目和 Studio。上传驱动结束后，需要重启 Studio。

可以使用 CUBA > Database Proprietary Drivers 配置页移除上传的驱动。
在 Create CUBA Screen 向导中可以在浏览界面和主从界面模板的 Table type 字段选择 DataGrid 和 TreeDataGrid。
在 Create CUBA Screen 向导添加了 Extend an existing screen 和 Entity fragment 模板。
在可视化编辑器中 Undo/Redo 操作能正常工作。
在界面设计器中，数据加载器的查询语句添加了自动完成功能。
界面设计器在画布右上角添加了一个按钮，用来切换至界面控制器。
在基于新 API 的界面 XML 描述中使用 invoke 和 datasource 属性时，会给出警告。
如果在 Project Properties 窗口添加了 Groovy 支持，则可以在 Create CUBA Screen 向导中的 Advanced > Controller language 字段选择 Groovy。
Groovy 写的 Services 能在 CUBA 项目树中显示。
项目打开时会弹出有框架新版本的提示。
微调了代码编辑器中侧边栏的图标。
不管有没有重构，都可以在实体设计界面自由更改实体属性的类型。
添加了枚举类型设计界面。
视图设计器使用原生 IntelliJ UI 重写。
数据模型生成器包含使用新 API 的界面模板。
所有解决了的问题：
- Studio 9.1 解决的问题
- Studio 9.0 解决的问题

版本 8

现在第一次打开项目是通过导入向导来做了。参阅打开现有项目了解细节。
项目模型现在保存在 .idea 文件夹的一个文件内，所以不会每次在打开项目时进行 Gradle 同步。
通过 Run/Debug Configuration 编辑器现在可以选择运行应用程序服务的 JDK 版本。在 Configuration 标签页有 JVM 字段。默认使用 JAVA_HOME 环境变量的值。
可以通过标准的 Refactor > Rename 操作来对视图进行重命名。在 CUBA 项目树中可以在视图元素上调用这个操作，也可以在 views.xml 文件的视图 XML 定义中的 name 属性调用这个操作或者在界面 XML 描述中任何引用该视图的地方调用。
可以在界面设计器中数据容器的 view 字段调用视图编辑器。
实现了在界面描述的 <fragment> XML 元素中对 screen 属性的自动完成功能以及使用参考功能。
为菜单标题实现了本地化名称编辑器。在 CUBA 项目树中点击 Generic UI > Web Menu，切换到 Structure 标签页，选择一个菜单项然后在 Caption 字段点击 edit 即可。
如果枚举值没有本地化名称，编辑器则会出现警告。如果发现该警告，可以使用 Create message in the message bundle 快速修复来创建默认名称。
实现了在配置接口中声明应用程序属性时，能自动完成其名称。当定义 app.properties 或 web-app.properties 内的属性时，按下 Ctrl+Space 即可。
所有解决了的问题：
- Studio 8.2 解决的问题
- Studio 8.0-8.1 解决的问题

版本 7

如果你的项目基于 CUBA 6.10 ，并使用了 BPM 、图表、全文搜索或报表等高级扩展组件，则需要在 ~/.gradle/gradle.properties 文件中设置 premium 仓库的访问凭据，如开发人员手册所述。 Studio不会将凭据传递给Gradle。
所有解决了的问题：

1. 安装

在安装 CUBA Studio 之前，确保系统满足 CUBA 开发人员手册安装部分中说明的要求。

有两种不同的安装 CUBA Studio 的形式：作为操作系统上独立的 IDE 安装或者作为已经安装的 IntelliJ IDEA 的插件安装。独立的 Studio IDE 是 IntelliJ IDEA 社区版的特殊版本，包含了 CUBA 插件。如果之前没有用过 IntelliJ IDEA，推荐使用独立 IDE 版本。

IDE 版本对应于使用的 IntelliJ IDEA 的版本，比如，2020.2。CUBA 插件有自己独立的版本号，从 15 开始。

可以从 https://www.cuba-platform.cn/tools/ 下载适用于 Windows、macOS 和 Linux 的独立 IDE 的安装程序。插件可以通过 IntelliJ 插件仓库下载（参考下面）。

在 Windows 上安装

下载 cuba-studio-VERSION.exe 安装程序。
运行安装程序并按照其说明操作：选择安装位置、启动器类型、文件夹名称，然后完成安装。
启动已安装的应用程序，参考这里了解更多信息。

在 macOS 上安装

下载 cuba-studio-VERSION.dmg 安装程序。
双击安装程序，然后将 CUBA Studio.app 拖放到 Applications 文件夹。如果有以前版本的 Studio 并且想保留它，请在出现的对话框中选择 Keep Both。
启动 CUBA Studio 应用程序，参阅这里了解更多信息。

在 Linux 上安装

安装所需的依赖：
```
$ sudo apt-get install libgconf-2-4
```
下载 cuba-studio-VERSION.tar.gz 存档。
将存档移动到适当的文件夹，例如 ~/lib 并将其解压：
```
$ tar -xvf cuba-studio-VERSION.tar.gz
```

转到 bin 目录并启动应用程序：

$ cd ~/lib/cuba-studio-VERSION/bin
$ ./cuba-studio.sh

首次启动 IDE

当第一次启动独立的 CUBA Studio IDE，Studio 会询问一些问题：

在第一个 Complete Installation 对话框中，选择 Do not import settings 然后点击 OK。
在下一个 Customize CUBA Studio 对话框中，可以点击 Skip Remaining and Set Defaults 以使用默认设置。因为之后随时可以自定义这些环境。
参阅入门部分了解如何启动一个新项目或者打开已有项目。

IntelliJ IDEA 插件安装

启动 IntelliJ IDEA 2020.2 或者更新的版本。
打开 Plugins 对话框。
切换到 Marketplace 标签页
在搜索栏输入 "CUBA"，可以在搜索结果看到 CUBA 插件。
点击 Install ，之后按照 IDE 的步骤继续安装。

1.2. 离线模式

可以在没有联网的情况下使用 Studio 开发项目，前提是所有项目所需的依赖已经下载过，比如，项目已经打开并且使用当前的 Studio 进行过装配（assemble）。离线模式下，Studio 的部分功能将无法使用，比如无法修改 CUBA 平台的版本或者浏览 CUBA 的插件市场。

要使用里面模式，打开 IDE 右边的 Gradle 工具窗口，然后点击 Toggle Offline Mode 按钮：

在离线模式中，Gradle 使用缓存的依赖执行所有的项目构建任务。并且不会尝试访问网络下载新的依赖。如果所需的依赖在缓存中不存在，构建执行则会失败。

1.3. 非标准 Studio 版本

有时需要在 IDE 中使用一个非标准的 Studio build。想试用最新的 Studio 功能或者参与 Beta 版本的测试。使用非标准的 Studio build 需要在 IntelliJ IDEA 中安装特定的插件版本。

Tip	非标准的 Studio 版本在商业订阅的需求上与稳定版一样。

Beta 发布版

Beta Studio 发布版会在下一个 Studio 的主版本发布之前的几周发布。这些版本也已经测试过，但是还可能包含一些未解决的问题。Beta 版本主要是为了：

为感兴趣的用户提供新 Studio 功能的前期试用。
帮助 CUBA 团队在更广泛的工作区和项目基础上测试即将发布的新 Studio 版本并提供反馈。

如需试用 Beta 版本，需要按照以下步骤操作：

打开主菜单 → File → Settings → Plugins 对话框。
点击图标，然后选择 Manage Plugin Repositories。
点击 + (Add) 然后在仓库 URL 地址字段输入： https://plugins.jetbrains.com/plugins/beta/list
切换至 Marketplace 标签页。您应当能看见 CUBA 插件升级至 BETA 版本的请求。
点击 Update。
根据提示重启 IDE。

如果需要切换会稳定的插件版本，按照以下步骤：

打开主菜单 → File → Settings → Plugins 对话框。
卸载 CUBA 插件。
点击图标并选择 Manage Plugin Repositories。
从列表移除 “beta” 仓库。
重新安装 CUBA 插件，会从稳定版的仓库安装。

夜间版本

Nightly Studio builds 会作为持续集成流程的一部分每天晚上发布。这些版本包含最新改动。如果想做第一个吃螃蟹的人，可以切换到夜间版本，获得最新的功能、提升以及支持即将发布的新 CUBA 平台版本。

Warning

夜间版本包含一些未经 QA 测试的改动。因此这些 build 可能包含严重的功能性缺陷。

如需用夜间版本，需要按照以下步骤操作：

打开主菜单 → File → Settings → Plugins 对话框。
点击图标，然后选择 Manage Plugin Repositories。
点击 + (Add) 然后在仓库 URL 地址字段输入： https://plugins.jetbrains.com/plugins/haulmont_nightly/list
切换至 Marketplace 标签页。您应当能看见 CUBA 插件升级至 NIGHTLY 版本的请求。
点击 Update。
根据提示重启 IDE。

由于夜间版本是每天晚上发布，您会每天都收到 IDE 发出 “有插件可更新” 的提示。

如果需要切换会稳定的插件版本，按照以下步骤：

打开主菜单 → File → Settings → Plugins 对话框。
卸载 CUBA 插件。
点击图标并选择 Manage Plugin Repositories。
从列表移除 “nightly” 仓库。
重新安装 CUBA 插件，会从稳定版的仓库安装。

从硬盘安装插件

Studio 插件的任何发布版，包括之前的一些版本，都能从插件仓库网站手动下载然后安装到 IntelliJ IDEA。按照下列步骤：

在 JetBrains Plugin 仓库打开 CUBA 插件页。
选择需要下载版本的通道（稳定版、Beta 版、夜间版）。
在 Version History 列表中找到需要下载的 build 版本。
点击 Download 开始下载。
在 IDEA 中打开主菜单 → File → Settings → Plugins 对话框。
点击图标并选择 Install Plugin from Disk…。
选择刚下载的 zip 文件，并点击 OK。
根据提示重启 IDE。

2. 更新

更新独立 IDE

可以从网站下载新版的独立 Studio IDE 然后覆盖安装。会保留之前所有的 Studio 设置。

也可以从插件仓库安装 CUBA 插件的自动更新，这样就不用下载和安装整个 IDE 应用程序：

打开 Plugins 对话框。
切换到 Updates 标签页。
如果有可用的更新，就可以在列表中看到。点击 CUBA 插件的 Update ，IDE 将会下载这个插件。
下载完成后，需要重启 IDE 来应用新版的插件。

更新 IntelliJ IDEA 插件

Windows 和 Linux 操作系统上点击 Help > Check for Update，MacOS 上点击 IntelliJ IDEA > Check for Updates。
如果有可用的更新，会在列表中看到。选择 CUBA 插件然后点击 Update 。IDE 将下载这个插件。
下载完成后，需要重启 IDE 来应用新版的插件。

3. 入门

本节介绍如何在 Studio 中创建新项目或打开现有项目并启动应用程序。

3.1. 创建一个新项目

CUBA Studio 提供了一种从零开始创建新 CUBA 项目的简单方法。只需使用 New Project 向导，然后按照以下步骤操作：

在 Welcome to CUBA Studio 窗口中，单击 Create New Project 或使用主菜单 File → New → Project。
选择 CUBA Project.
指定 Project namespace，该命名空间将会作为实体或者数据库表的前缀。命名空间只能由拉丁字母组成，并且尽可能短。这里需要仔细考虑该名称，因为之后如果想修改会需要很多手动操作。
如果需要，可以修改 Root package。这是 Java 类的根包名。也可以之后再调整，但是项目创建阶段生成的类还会使用当前的包名。
如果需要，可以修改 Module prefix。CUBA 项目的模块名称会添加这个作为前缀。模块名前缀可以稍后修改。
在 Project SDK 字段，选择对应环境中设置 JAVA_HOME 的 JDK。如果看到 <No SDK> 这样的值，点击 New 然后选择 JDK 安装的目录，比如在 Windows 是 C:\Java\jdk8u202-b08，macOS 是 /Library/Java/JavaVirtualMachines/jdk8u202-b08/Contents/Home。
选择默认仓库配置，或为项目自定义仓库配置。
选择项目中使用的 Platform version。如果没有特别需求，使用最新的发布版本。
为了做 beta 测试或尝试使用新的 CUBA 平台功能，您也许需要使用一个不稳定的 CUBA 版本，即，以 BETA 或 SNAPSHOT 结尾的版本。需要勾选 Show unstable versions 复选框，才能在 Platform version 的下拉框中看到这些版本。注意，SNAPSHOT 发行版只在 repo.cuba-platform.com 仓库发布。
在 Languages support 下拉框字段选择项目使用的编程语言，或者使用默认的 Java 语言。
使用 Available locales 字段打开 Locales 编辑器对话框，可以为项目添加多地区支持。也可以稍后再修改该配置。
点击 Next。
向导的第二步中，可以配置主数据存储属性，比如，为新项目选择本地的 PostgreSQL 作为数据库。这些属性也可以稍后修改。
点击 Next。
如果需要，可以修改 Project name 字段的值。该名称只能包含拉丁字母、数字和下划线。
Project location 配置新项目的路径。可以输入其他的值或者点击省略号按钮修改这个路径。
单击 Finish。空项目将在指定目录中创建，之后 Studio 会自动通过 Gradle 文件开始构建项目信息并为项目建立索引。
项目同步和建立索引过程完成后，将在 Project 工具窗口中看到 CUBA 项目树。
打开 Gradle 工具窗口，默认固定在右边栏。点击“扳手”图标（Gradle Settings）然后在 Gradle JVM 字段选择 Project SDK。点击 OK。
现在可以开始项目的工作了。

3.2. 打开现有项目

打开已导入的项目

如果在此计算机上已经通过 CUBA Studio 打开过该项目，请执行以下操作：

使用最近项目列表或单击 Open，在文件系统对话框中选择 _ 项目目录 _，然后单击 Open 按钮。
等待 Gradle 同步和项目索引过程完成。只要 CUBA 项目树出现在 Project 工具窗口中，就可以开始使用该项目了。

首次打开项目

如果还没有在此计算机上通过 CUBA Studio 打开该项目，例如，只是通过 VCS 下载了代码，请执行以下操作：

在欢迎窗口，点击 Import Project。如果已经打开了另一个项目，则在主菜单点击 File > New > Project from Existing Sources。
在文件系统的窗口，选择项目的根目录（包含 build.gradle 文件），然后点击 Open 按钮。
在 Import Project 窗口，选择 Import project from external model 单选按钮并在下面的列表中选择 CUBA，然后点击 Next。
在导入向导的下一页点击 Finish。
- 等待 Gradle 同步和项目索引过程完成。CUBA 项目树会出现在 Project 工具窗口中。
在主菜单点击 File > Project Structure。
- 确保 Project SDK 字段的值跟环境中设置的 JAVA_HOME 一致。如果看到 <No SDK> 值，点击 New 然后选择 JDK 安装的目录，比如在 Windows 是 C:\Java\jdk8u202-b08，macOS 是 /Library/Java/JavaVirtualMachines/jdk8u202-b08/Contents/Home。
- 确保 Project language level 字段的值跟 JDK 的版本一致。比如，如果 JDK 是 1.8 语言等级必须是 8 - Lambdas, type annotations, etc.

首次打开基于 CUBA 6.10 的项目

CUBA Studio 支持基于 CUBA 6.10+和 7.0 的项目。可以打开在旧版本的 Studio 中创建的项目，并将其导入到新 Studio 中，进行以下操作：

需要记住 CUBA 6.10 只支持 Java 8，所以 JAVA_HOME 环境变量必须指向 JDK 8 的安装目录。在迁移到 CUBA 7 之后，如果需要可以使用新版本的 JDK。

如果是第一次打开已有的 CUBA 6.10 项目，需要按照下面的步骤：

如果项目使用了 premium 扩展组件（Reports、BPM 等）并且已经有了许可，需要按照文档的描述在 ~/.gradle/gradle.properties 文件内设置 premium 仓库的访问凭证。
在命令行使用 gradlew cleanIdea 任务删除旧的 IntelliJ 项目文件。
如果项目使用 Git 做版本控制，将 .idea 行添加到项目根目录下的 .gitignore 文件中。确保本地 IDE 设置不会在项目的所有开发人员之间共享。
按照上面 首次打开项目 部分所述导入项目。

3.3. 升级项目

本节介绍将项目升级到较新版本 CUBA 的过程。

Tip	建议使用版本控制对项目进行管理，并在升级之前提交所有未提交的改动。这样的话，如果由于某种原因导致升级失败，可以通过版本控制查看执行了哪些更改并快速回滚到以前的版本。

按照前一节中的描述打开项目。
单击主菜单中的 CUBA > Project Properties，或双击 CUBA 项目树中的 Project > Properties。
在 CUBA Project Properties 对话框中，点击 Platform version 标签旁边的 Change… 链接。
显示 Change Platform Version 对话框，在下拉列表中选择需要的 CUBA 版本。
为了做 beta 测试或尝试使用新的 CUBA 平台功能，您也许需要使用一个不稳定的 CUBA 版本，即，以 BETA 或 SNAPSHOT 结尾的版本。需要勾选 Show unstable versions 复选框，才能在 Platform version 的下拉框中看到这些版本。

Tip

只有使用了 repo.cuba-platform.com 仓库才能看到 SNAPSHOT 版本。

Warning

强烈建议不要在生产环境使用 BETA 或 SNAPSHOT 版本。
可以点击 Release Notes 链接，跳转至文档页，显示平台新版本的新功能、提升以及破坏性改动。
如果要升级到较新的功能版本（例如，从 6.10.X 升级到 7.0.X 或从 7.0.Y 升级到 7.1.Y），Change Platform Version 对话框会显示 Migration Required 内容。
- 点击 More info… 链接，可以打开另一个窗口，包含 Studio 将要自动执行的改动：项目结构、构建脚本或独立的项目文件。需要仔细审查这些内容。

点击 OK 确认升级平台版本，然后在 Project Properties 弹窗中点击 OK。
Studio 会自动执行迁移，更新脚本（如果需要）并运行 Gradle clean 和 undeploy 任务。
如果升级到新的功能版本，可能有新的改动使得项目不能运行，请查看 Release Notes 中的 Breaking Changes 部分，并相应地对项目进行修改。
如果您的项目包含 CUBA Add-ons，您也许需要升级到兼容当前 CUBA 版本的合适扩展插件版本：
- 打开 CUBA 项目树的 Project → Add-ons。
- 选择 Updates 标签页。
- 选择所有能升级的插件。
- 点击 Apply & Close.
- 等依赖下载完成并且项目重新建立索引。
尝试通过执行 CUBA > Build Tasks > Assemble 来组装项目。如果编译不通过，可以按照日志输出来修复代码。
执行 CUBA > Update Database 将框架中可能新引入的数据库结构更改合并到项目的数据库中。

3.4. 启用应用程序

当 Studio 导入了一个 CUBA 项目之后，会创建为 CUBA 特定修改的 Run/Debug 配置，目的是用来运行部署了应用的本地 Tomcat 服务。所以为了运行应用程序并能用调试器进行连接，只需要在主工具栏点击选中的 CUBA Application 配置边上的 debug 按钮即可。

在 Debug 工具窗口的 Console 标签页可以看到状态。能通过点击打印在 Server started at 消息之后的链接地址在默认浏览器打开应用程序的图形界面。

也可以通过 CUBA 树部分的 Runs At… 在浏览器打开运行的应用程序：

如果要查看应用程序服务的输出，切换到 catalina.out 标签页：

如果要停止应用程序，可以通过在主菜单选择 Run > Stop 'CUBA Application' 或者点击 Debug 工具窗口的按钮：

推荐在开发中使用 Run/Debug 配置来启动应用程序，但是通过 Studio 的 CUBA 主菜单项也可以控制本地 Tomcat 应用程序服务：

当从 Start Application Server 主菜单命令启动服务时，在 Windows 系统能看到一个控制台窗口显示服务器日志。在 Linux 或者 macOS 系统，不会显示控制台，但是可以在 Terminal 工具窗口通过执行 tail -f deploy/tomcat/logs/app.log 命令查看服务日志。Stop Application Server 命令通过发送 SHUTDOWN 信号给停止端口来停止 Tomcat 服务，停止端口是通过项目属性设置（默认是 8005）。

运行/调试配置

Tomcat 服务中 CUBA Application 运行/调试的配置是能调整的。使用下列方式打开配置对话框：

在工具栏中点击 CUBA Application 元素然后在菜单中选择 Edit Configurations…。
或使用主菜单 → Run → Edit Configurations…

会弹出 Run/Debug Configuration 对话框。您或许希望调整下列配置：

JRE - 启动调试 Tomcat 服务的 Java 运行环境。可以选择和项目 JDK 不同的 JRE，但是需要考虑二进制文件的兼容性需求（比如使用 Java 11 编译的应用程序不能在 Java 8 运行）。
Command line arguments - 传递给调试服务的 JVM 参数。例如，指定 -Xmx1500m 提高服务使用的最大内存数量。
Environment Variables - 调试服务进程可以使用的环境变量。

3.5. 使用非默认 JDK

IntelliJ IDEA 和 Gradle 默认都会使用由 JAVA_HOME 环境变量定义的 Java Development Kit (JDK) 来装配和运行 Java 项目。如需使用非默认的 JDK，又不想修改全局的配置，需要额外几步操作。

我们假设有这样的环境配置：

开发机器的 JAVA_HOME 环境变量指向 JDK 8，但是由于某些原因，您没有办法修改这个配置。
项目中想使用 JDK 11。
您希望能使用新的 Java 11 API，因此项目需要使用 JDK 11 来编译和运行。

请按照以下步骤进行配置：

为 IDEA SDK 添加 JDK 11，如已添加，请忽略这步。点击主菜单 File → Project Structure。在左侧菜单选择 SDKs。点击 + 按钮 → 选择 JDK → 选择 JDK 11 安装目录。点击 OK 保存更改。
当创建新的 CUBA 项目时，在 Project SDK 字段选择 “11”。
对于已有项目，打开主菜单 → File → Project Structure 窗口，然后修改 Project → Project SDK 值。
切换到项目根目录，并创建 gradle.properties 文件，包含以下内容：

# Path to JDK 11
org.gradle.java.home = C:/Java/jdk-11.0.5.10-hotspot

修改项目根目录的 build.gradle 文件。并在 configure([globalModule, coreModule, webModule]) 块最后添加：

configure([globalModule, coreModule, webModule]) {
    ...
    sourceCompatibility = '11'
    targetCompatibility = '11'
}

刷新 Gradle 项目配置：Gradle 工具窗口 → Reimport All Gradle Projects；
修改 CUBA Application 运行配置中的 JRE。打开主菜单 → Run → Edit configurations… → CUBA Application → 修改 JVM 字段的值。

当这些修改完成之后，项目将会使用 JDK 11 进行编译和运行，而不需要修改全局系统配置。

4. Studio 用户界面

本节介绍 CUBA 特有的 IDE 元素的用户界面。有关 IntelliJ IDEA 的所有功能，请参阅文档。

4.1. CUBA 项目树

CUBA 项目树用于展示项目结构及其重要元素，通常在 IDE 左侧的 Project 工具窗口中打开。可以使用 CUBA > Project Tree 主菜单命令或在 Project 工具窗口的顶部下拉列表中选择 CUBA 来切换到项目树。

项目树包含以下元素：

Project
- Properties - 允许配置项目的基本设置。
- Add-ons - 打开界面配置项目中用到的 CUBA 扩展。
- Build Script - 包含两个主要项目脚本： build.gradle （定义构建配置）和 settings.gradle（定义项目名称和模块组）。
- Config Files - 展示项目的重要配置文件，按模块分组。
- Data Stores - 显示并管理项目所连接的数据存储列表。默认情况下，只有 Main 数据存储。
- Deployment - 允许定义项目部署选项。
- Config Interfaces -显示并管理项目的配置接口。
- Logging - 显示日志配置文件以及本地调试服务的日志文件。
Data model - 显示并管理项目的数据模型。
Business Logic - 显示并管理中间件服务、Spring bean 和集成测试。
Generic UI - 包含与项目的用户界面相关的所有内容，例如界面、主题等。
Frontend UI - 包含应用程序中的前端用户界面相关文件。
REST API - 配置 REST API 功能。
Security - 显示并支持可视化构建设计时角色。
All Sources - 展示项目模块中未按文件类型过滤的所有源文件。开发者可以在这里找到那些没有包含在特定项目部分（服务、界面控制器、实体等）中的文件或类。
Runs At… - 允许在外部或嵌入的 Web 浏览器中打开运行中的应用程序。

右键点击树元素能打开右键菜单，可以执行针对当前元素的特定操作。例如，使用 Data Model 项的右键菜单，可以从模型生成数据库脚本、从数据库生成模型以及创建新实体或枚举：

4.2. CUBA 菜单

CUBA 主菜单可以快速访问 IDE 中的 CUBA 特有功能。某些菜单项功能与CUBA 项目树及其右键菜单功能相同。

可以通过右击工具栏并选择 Customize Menus and Toolbars，将常用菜单项添加到主工具栏。在弹出的 Menus and Toolbars 窗口中，展开 Main Toolbar 项并使用 Add Action 按钮添加 Main Menu > CUBA 树中的条目。

4.3. 欢迎界面

在新项目创建时，欢迎界面会自动在工作区打开。也可以通过主菜单 CUBA → Welcome 来打开。

该界面提供主要项目设置、常用操作、文档和社区网页链接的快捷入口。也会显示项目中用到的 CUBA 版本信息和 Studio 版本信息以及商业订阅信息。

4.4. CUBA 设置

如果单击 CUBA > Settings 主菜单项，可以看到在 IDE 的设置中选中了 CUBA 部分。

CUBA 部分包含对所有在 Studio 实例中打开的项目都通用的设置。

Ask before saving DB scripts with DROP statements - 建议不要自动执行包含 DROP 语句的更新脚本。
Show warning if application server port is in use - 打开项目且 Tomcat 端口被占用时显示警告。
Use embedded browser to open application - 如果选中该选项，则双击 Runs At 项目树中的应用程序 URL 时将使用内嵌 Web 浏览器打开项目地址。
Visual designer and embedded browser zoom percentage - 界面设计器的布局预览默认缩放。也可以通过预览面板顶部的一个操作按钮稍后调整。
Enable integration - 如果要将此 IDE 实例与旧的 Studio SE 或 Studio Browser Edition 集成，选中此复选框。这样就可以在新的 IDE 中打开旧 Studio 的项目。另外，这个复选框也会启用与前端生成器命令行工具的通信。
Listening port - 用于集成旧 Studio 和 Frontend Generator 的端口。确保这个值与旧 Studio 的 IDE Port 字段中指定的值相同。

项目设置

下一级的 Project settings 部分包含当前打开的项目的设置。所有非默认值都存储在项目根目录的 studio-intellij.xml 文件中，可以将其添加到版本控制系统，以便在团队中的所有开发人员之间共享项目设置。

Check compatibility between data model and database scheme - 在启动应用程序服务时，如果数据模型的当前状态与数据库架构不一致时显示警告信息。
Generate DROP statements in separate update scripts - 为删除实体、属性或更改属性的数据类型的操作生成更安全的更新脚本。这些脚本分为两部分：在第一部分，列或表被重命名为 *__UNUSED，在第二部分对这些对象执行实际的删除操作。
Use NVARCHAR when generating scripts for MS SQL Server -如果启用此选项，对于 Microsoft SQL Server 数据库，使用 NVARCHAR 列类型存储所有 String 属性。
Generate script name in format - 指定 yyMMddHHmm 可以将当前时间添加到生成的数据库更新脚本的名称中，这有助于确保在团队工作中脚本的正确顺序。
Group update scripts by - 定义自动生成的数据库更新脚本如何按照目录分组。如果选择 YEAR，脚本按年份目录分组（2020、2021 等）。如果选择 MONTH，脚本按照下一级的月份目录分组（2020/10、2020/11 等）。对于大型项目来说，后者更加合适。
Do not delete columns started with - 此字段允许为表列指定一个前缀，Studio 将不跟踪具有此前缀的列。一般情况下，如果向映射到实体的表添加了一列，而不将列映射到一个实体属性，Studio 将生成删除此列的更新脚本。如果想避免丢失表中的列，可以在 Database Scripts 对话框中不包含此脚本，这个脚本也不会再次生成。或者通过 Do not delete columns started with 字段为此类列设置一个公共前缀，并相应地命名列。例如，在字段中输入 NOT_MAPPED_ 并将列命名为 NOT_MAPPED_CODE。
Column length for enums with ID of String type - 此字段允许设置数据库列的长度，该列映射到具有 String 类型标识符的枚举类型的属性。例如，如果始终使用只由一个字符组成的短标识符，则可以将此字段设置为 1，以节省数据库空间。
Make plural forms - 根据英语语法构造名词的复数形式。
Repeat entity parent package for screens - 当 Studio 根据模板生成通用 UI 界面时，如果实体位于比 entity 包更深的一个包中，Studio 将为界面添加此包名。例如，如果 Customer 实体位于 com.company.sample.entity.crm 中，则其界面的默认包将是 com.company.sample.web.crm.customer。
Use underscores in generated package names - 如果选中，包名称将包含以下划线分隔的单词，这些单词是根据以驼峰命名法命名的相应实体名称生成。例如，当为 com.company.sample.CustomerGrade 实体生成界面时，界面的包将是 com.company.sample.customer_grade。如果该选项关闭，则包名称为 com.company.sample.customergrade。
Default parent package name for screens - 当根据与实体无关的模板生成通用 UI 时，可以在这里指定使用的默认包名替代"screens"(默认)。如果模板关联了实体，还会在包之前添加实体名称。例如，如果将此字段设置为"ui"并创建一个空白界面，则包的默认值为 com.company.sample.web.ui。
Default entity attribute access modifier - 设置 Studio 在生成实体字段时使用的默认字段修饰符。
Generate entity name with underscore symbol - 如果选择，实体名称将具有 namespace_ClassName 格式，例如 sales_Customer。否则它将是 namespace$ClassName。
Show module prefix migration dialog - 在项目打开时，显示模块定义迁移的弹窗，其中会建议将构建脚本中的模块定义改为新格式 - 用变量定义模块名称前缀。
Instant hot deploy - 此复选框允许关闭热部署。如果启用了热部署，则 Studio 会在应用或保存对视图、界面、消息或主菜单的更改时动态更新已部署的 Web 应用程序的 UI。
Scaffolding language - 在支持 Kotlin 的项目中选择使用何种编程语言生成代码。可选项为：Kotlin、Java 和 Always Ask。如果您的项目混合了 Java / Kotlin 的内容，然后您想控制每次生成实体、服务、界面的脚手架代码，可以选择 Always Ask。该选项只有在项目支持 Kotlin 时才会出现。
Hot deploy compiled classes - 为基于 CUBA 7.2+ 的项目启用新的热部署机制。旧的机制需要复制 Java 源码到 Tomcat 配置目录并使用自定义的类加载器编译这些文件。新的机制会在 IDE 端编译这些文件，因此能热部署 Kotlin 代码。如果在使用新的热部署机制中遇到问题，可以尝试关闭该设置。
Hot Deploy Settings - 打开对话框来自定义热部署目录。例如，可能希望将 Web 门户的 HTML 文件和 JavaScript 文件所在的文件夹添加为部署目录。当更改这些文件时，Studio 会将它们复制到 Tomcat 中的各自对应的目录。因此，只需重新加载 Web 门户页面即可查看更改。
Screen Generation Settings - 影响界面生成的选项。这些设置在 New → Screen… 向导中使用。可用设置有：
- Default form field width - 实体编辑器使用
- Keep editor actions at the bottom - 实体编辑器以“全屏”模式打开时使用。
- Force modal open type for editors - 实体编辑器以“对话框”模式打开时使用。
Fold messages in - 允许控制界面描述和界面控制器中的消息折叠。选中的话，消息键将替换为相应消息包中的实际值。
Message folding locale - 折叠(folding)消息时要使用的本地化消息文件。

4.5. 商业订阅信息

从主菜单 CUBA → Subscription Information 可以打开 Subscription Information 对话框。

该对话框为用户提供如下功能：

申请 CUBA Studio 试用。
输入 Studio 商业订阅 key。
查看当前订阅状态的详细信息。

CUBA Studio 商业订阅能解锁下列功能：

实体设计器
枚举设计器
界面设计器
视图设计器
角色设计器
主题变量可视化编辑器

试用商业订阅

每个新用户可以申请一次商业订阅试用。开发者可以通过试用版评估 Studio 的全部功能，有效期为 28 天。在 Subscription Information 窗口点击 Request Trial，查看您是否满足试用条件：

5. Studio 功能

这部分文档描述了所有能帮助开发 CUBA 应用程序的 Studio 功能。主要是根据能在项目树中看到的项目元素组织相关信息。

5.1. 项目

本节介绍可用于管理项目基础设施的编辑器和命令。

5.1.1. 项目属性编辑界面

Project Properties 编辑界面允许对项目进行配置。可以从 CUBA 主菜单中打开它，也可以通过双击项目树的 Project > Properties 项来打开。

基本设置

Main 选项卡显示基本设置。

Module prefix 字段显示项目模块的名称前缀。后面加上模块的名称决定了项目攻坚的名称，比如 sales-global 模块装配成 sales-global-0.1.jar 工件。如果要重命名模块，可以修改模块名前缀。例如，使用 wages 模块名前缀的基本 CUBA 项目有 wages-global、wages-core 和 wages-web 模块。
Artifact version 字段可以修改项目工件的版本。如果是 final build，可以不勾选 Snapshot，snapshot（快照版本）是可以被同名构建覆盖的版本。
Repositories 表格显示当前在项目中使用的仓库。Studio 扫描这些仓库以寻找可用的平台版本。使用该字段旁边的按钮配置对仓库的访问。有关详细信息，请参阅文档。还可以在 build.gradle 中手动注册包含应用程序组件的其它仓库，并且仓库数量不受限制。
Platform version 显示项目中使用的 CUBA 平台版本。Change… 链接按钮可以用来升级平台版本，升级时会根据需要自动完成项目迁移。参阅升级项目了解更多。
Show unstable versions 复选框可以选择显示不稳定的 CUBA 版本，是指带有 BETA 或 SNAPSHOT 的版本。
Groovy support 复选框可以在应用程序内启用 Groovy 代码，比如，在界面控制器类中。
如果需要更改应用程序服务的路径，请在 Tomcat path 字段中指定新路径。下一次执行 gradlew deploy 或 gradlew start 会将 Tomcat 安装到该位置。
Tomcat ports 分组允许为通过快速部署安装在 deploy/tomcat 文件夹中的 Tomcat 应用程序服务分配非标准端口。
需要特别留意 HTTP port 字段，该字段 Tomcat 监听的 HTTP 连接端口，以及 cuba.webPort 、cuba.webAppUrl 、 cuba.restApiUrl 和 cuba.connectionUrlList 应用程序属性。
在 AJP port 字段中，可以设置 AJP 连接器的端口。
在 Shutdown port 字段中，可以设置 Tomcat 监听的 SHUTDOWN 命令端口。
在 Debug port 字段中，可以设置 Tomcat 监听的 Java 调试器连接端口。如果更改了此端口，还应在 IDE 的调试配置中进行同步更改。
Available locales 字段允许设置应用程序可用的本地化语言。单击该字段旁边的按钮打开语言环境编辑界面。位于编辑界面窗口中的 Locale select visible 复选框控制 cuba.localeSelectVisible 应用程序属性的值。编辑界面还可以为解析和格式化数据定义新的或覆盖已有的格式化字符串。

5.1.2. 项目依赖

Project Properties 对话框的 Dependencies 部分展示并管理项目的第三方依赖（库）。

项目依赖在表格中按照模块分组展示，根据项目中选择模块的不同，一般有三个或更多的模块分组。如果类库是添加到 global 模块，则在整个项目的范围内全局能用，因为其他的 CUBA 项目模块依赖于 global 模块。

表格中的 Type 列展示依赖的类型：

compile - 在编译和运行时使用的库
provided - 只在编译生产版本的应用程序时使用，不能包含在运行时的 classpath 中（比如 JDBC 驱动，Servlet API 的实现等。）
runtime - 只在运行时使用的库
testCompile - 在编译和测试时使用的库
testRuntime - 只在运行时测试使用的库

Text 列以 Gradle 依赖字符串的格式展示库的坐标："group:name:version"。

依赖管理的操作在依赖列表的右侧显示：

Add dependency - 添加新的项目依赖。指定 Maven 依赖声明或 Gradle 依赖坐标。对话框会自动验证依赖声明是否正确。
Remove dependency - 从项目中移除依赖。
Edit dependency - 修改依赖声明的内容。

参阅 Gradle 文档了解更多关于第三方依赖的内容。

添加新的第三方依赖

添加新的第三方依赖需要以下步骤：

找到需要类库的 Maven 依赖声明或者 Gradle dependency string for the required library.

复制依赖声明至剪切板
打开 Project Properties 对话框
选择需要添加依赖的模块，或者用 global 模块声明项目全局依赖。
点击 Dependencies 表格右边的 + 按钮打开 Dependency Editor 对话框。剪贴板的依赖声明会自动粘贴到这里。
点击 Dependency Editor 对话框的 OK 按钮，如果有声明验证错误的话，请手动修复。
点击 CUBA Project Properties 对话框的 OK 按钮应用修改。Studio 会在项目的构建脚本添加必须的声明，并刷新项目配置。
现在可以在代码中使用库中的类了。

Tip	Gradle implementation 'a.b.c' 依赖类型目前还不支持，请使用 compile 'a.b.c' 代替。

添加 JAR 文件依赖

有时您需要添加一个 JAR 文件作为项目的依赖，但是此文件不在任何公共的或内部的 Maven 仓库。此时，需要手动修改 build.gradle 脚本文件。

在项目的根目录创建 lib 文件夹；
将 JAR 文件复制到该文件夹，比如， <my-project>/lib/custom-lib.jar
打开 Gradle 构建脚本：CUBA 项目树 → Build Script → build.gradle；
修改 build.gradle 文件，为 repositories 部分添加 flatDir ：

    repositories {
        maven {
            ...
        }
        flatDir {
            dirs "${project.rootDir}/lib"
        }
     }

修改 build.gradle 的 configure(globalModule) 部分，添加指定的 JAR：

configure(globalModule) {
    ...
    dependencies {
        compile(name: 'custom-lib')
    }
}

刷新 Gradle 项目配置；Gradle 工具窗口 → Reimport All Gradle Projects；
现在可以在代码中使用该库的类。

5.1.3. 管理扩展插件

扩展插件是公共发布的全栈类库，用来对项目进行扩展使用其提供的附加功能。可以参阅 CUBA 开发者手册了解更多关于扩展和应用程序组件的知识。

CUBA Add-ons 对话框可以用来管理 CUBA 项目中引入的扩展插件。可以通过下面的方式打开这个对话框：

在 CUBA 项目树双击 Project → Add-ons
从主菜单项： CUBA → Marketplace…

该对话框有三个标签页： Marketplace、Installed 和 Updates。

5.1.3.1. 扩展插件市场

Marketplace 标签页展示发布的扩展中那些能与项目兼容的扩展插件。

扩展按照类型分组。可以用过滤器查找需要的扩展，比如，"email" 或 "category:Translation"。

点击扩展的标题可以跳转到扩展的详情页，包括概览、兼容性、许可等信息：

如需安装一个或多个扩展，点击它们的 Install 按钮即可然后点击 Apply 或 Apply & Close 按钮。在确认之后，Studio 会对项目的构建脚本和配置文件做必要的修改、下载新的库并刷新 Gradle 项目的配置。

安装商业扩展插件在单独的章节介绍：商业扩展组件安装。

5.1.3.2. 使用坐标安装

扩展的坐标其实就是 Gradle 的依赖字符串，如， "com.mycompany.cuba-addons:myaddon:0.1.5"。这个字符串可以在 CUBA 平台的网站上发布或者由扩展插件的作者自己发布。如果该需要使用坐标（或使用 Gradle 依赖字符串）进行安装，点击 Updates 标签页标题右边的 "Install Add-on Manually" 图标：

5.1.3.3. 已安装的扩展插件

Installed 标签页展示已经安装的关联到当前项目的扩展插件。

已安装的扩展插件按照两种分类进行分组。 Marketplace Add-Ons 是从 CUBA 市场安装的扩展。 Custom Add-Ons 是由第三方开发、发布在第三方仓库或者 Maven 本地仓库的扩展。

如果要在项目中移除关联的扩展，可以选中相应的扩展点击 Delete，或者右键点击扩展，选择 Uninstall。然后在弹出框选择 Apply。Studio 会从项目的依赖移除该扩展并更新项目的配置。

5.1.3.4. 升级扩展插件

Studio 会自动检查项目中引入的扩展是否需要升级。 Updates 标签页显示可以升级的扩展的相关信息。

如果要升级扩展，点击 Update 按钮，然后点击 Apply 或 Apply & Close 按钮。 Studio 会自动升级依赖、下载需要的类库并更新项目配置。

另外，在打开项目之后，也会在界面的右下角显示可用的升级信息：

5.1.4. 商业扩展组件安装

使用 CUBA 商业扩展组件需要进行订阅。可以在 CUBA 商店网页购买。另外，如需评估扩展组件，可以新装特定扩展插件的试用版（有效期 30 天）。

下面介绍以下几种场景的安装方式：

安装试用版扩展组件
已购买扩展组件的自动安装
已购买扩展组件的手动安装

5.1.4.1. 安装试用扩展插件

打开 Marketplace 窗口，比如，从主菜单：CUBA → Marketplace。
找到需要的扩展插件，点击旁边的 Install。
弹出的对话框中点击 Get free trial
如果您还没有登录 CUBA user profile，则点击弹窗中的 Sign In…
注册或者登入 CUBA 网页
阅读介绍并点击 Install Trial
点击 Apply。您的项目即能安装插件的试用版。

当试用版结束后，CUBA Studio 会提示您。保持 CUBA user profile 的登录状态，以免错过提醒。

Warning

注意，一旦试用扩展插件过期，您的项目将无法启动。

CUBA User Profile

如果还未登录，可以通过 CUBA Add-Ons 窗口右上角的 Sign In to CUBA 按钮登录：

将会重定向至浏览器登录。登录之后，IDE 中会收到通知，再次点击上面的按钮能打开一个弹窗，显示您个人信息以及可用的扩展插件试用：

5.1.4.2. 安装购买的扩展插件

购买扩展插件后，您会收到 license key。可能与 Studio premium 的 key 一样，也可能是一个单独的 key（如果您没有订阅 Studio 或者是单独购买的扩展插件）。

打开 Marketplace 窗口，比如通过主菜单：CUBA → Marketplace
找到需要的扩展插件，并点击 Install
在弹窗中输入 license key。
在 Commercial Add-On Installation 弹窗中点击 Install
点击 Apply 或 Apply & Close 按钮，然后在确认弹窗中点击 Continue

确认之后，Studio 会对项目的构建脚本和配置文件做必要的修改，然后下载新的依赖库并刷新 Gradle 项目配置。

5.1.4.3. 手动安装扩展插件

如果自动安装出现了任何问题，或者需要从命令行配置项目构建环境（比如，持续集成），则可以使用该方式进行手动安装商业扩展插件。

购买扩展插件后会收到一个 license key。用这个 key 配置 premium 仓库凭证。

添加 Premium 仓库

打开 build.gradle 文件，在仓库列表中 最后一行 添加：

如果主仓库是 repo.cuba-platform.com，则添加 https://repo.cuba-platform.com/content/groups/premium

buildscript {
    // ...
    repositories {
        // ...
        maven {
            url 'https://repo.cuba-platform.com/content/groups/premium'
            credentials {
                username(rootProject.hasProperty('premiumRepoUser') ?
                        rootProject['premiumRepoUser'] : System.getenv('CUBA_PREMIUM_USER'))
                password(rootProject.hasProperty('premiumRepoPass') ?
                        rootProject['premiumRepoPass'] : System.getenv('CUBA_PREMIUM_PASSWORD'))
            }
        }
    }
}

如果主仓库是 Bintray，则添加 https://cuba-platform.bintray.com/premium

buildscript {
    // ...
    repositories {
        // ...
        maven {
            url 'https://cuba-platform.bintray.com/premium'
            credentials {
                username(rootProject.hasProperty('bintrayPremiumRepoUser') ?
                        rootProject['bintrayPremiumRepoUser'] : System.getenv('CUBA_PREMIUM_USER'))
                password(rootProject.hasProperty('premiumRepoPass') ?
                        rootProject['premiumRepoPass'] : System.getenv('CUBA_PREMIUM_PASSWORD'))
            }
        }
    }
}

提供仓库凭证

您的 license key 包含两部分：短横前的部分为仓库用户名，短横后的部分为密码。比如，如果您的 key 是 111111222222-abcdefabcdef，则 111111222222 是用户名，abcdefabcdef 是密码。如果使用的是 Bintray 仓库，用户名后面需要加上 @cuba-platform。

可以使用下面的一种方式为仓库提供凭证：

推荐的方式是在用户主目录（比如，windows 上：C:\users\john\.gradle\gradle.properties；Mac 上：/Users/helen/.gradle/gradle.properties）创建一个 ~/.gradle/gradle.properties 文件。然后添加下列内容：
```
premiumRepoUser=111111222222
bintrayPremiumRepoUser=111111222222@cuba-platform
premiumRepoPass=abcdefabcdef
```
或者，通过环境变量 CUBA_PREMIUM_USER 和 CUBA_PREMIUM_PASSWORD 设置。
当在命令行运行 Gradle 任务时（比如持续集成环境中），可以用 -P 前缀将变量传递给 Gradle，示例：
```
gradlew assemble -PpremiumRepoUser=111111222222 -PpremiumRepoPass=abcdefabcdef
```

Tip	IDE 中可以通过 CUBA → Advanced → Edit Gradle Properties 菜单打开 `~/.gradle/gradle.properties` 进行编辑。

添加组件

在 build.gradle 文件中的 dependencies 部分按照下面例子的格式指定组件的坐标：

com.haulmont.addon.<addon-name>:<addon-name>-global:<addon-version>

示例：

dependencies {
    //...
    appComponent('com.haulmont.addon.maps:maps-global:1.3.0')
}

在 core、web（以及 portal，如果有的话）模块的 web.xml 文件的 appComponents 上下文中添加扩展插件的标识符，示例：

<context-param>
    <param-name>appComponents</param-name>
    <param-value>com.haulmont.cuba com.haulmont.addon.maps</param-value>
</context-param>

如果是从命令行运行 Gradle，执行 gradlew assemble 后，扩展插件即能安装。

5.1.5. 模块管理

Studio 允许创建、编辑和删除项目的可选模块： core 、 gui 、 web 、 web-toolkit 、 portal 和 front。可以使用 CUBA > Advanced > Manage Modules 主菜单或从项目树的 Project 项的右键菜单中执行此操作。

当您创建一个新项目，默认包含 global、core 和 web 模块。

自动模块管理

注意，在某些情况下，Studio 会自动为您的项目添加模块。

比如，Studio 检测到项目中有两个或多个定义 widgetsets（带有客户端侧 Vaadin 代码的组件）的扩展插件时，会自动添加 web-toolkit 模块。此时，项目中有 web-toolkit 模块才能构建完整的 widgetsets，包含 CUBA 和所有扩展插件使用正确 Vaadin 版本编译的 UI 组件客户端侧代码。

5.1.6. 管理数据存储

5.1.6.1. 主数据存储

主数据存储指定连接至 CUBA 应用程序使用的主数据库的信息。该数据存储包含系统实体，是 CUBA 项目不可缺少的存储。

Main Data Store Properties 窗口展示主数据存储的配置。可以通过以下方式打开该窗口：

在 CUBA 项目树双击 Project → Data Stores → Main Data Store。
从主菜单点击： CUBA → Main Data Store Settings…。

5.1.6.2. 数据存储属性

下列属性可以为主数据存储和附加数据存储配置：

Define JDBC DataSource in - 决定使用哪个组件创建数据库连接池（需要项目基于 CUBA 7.2+）。可选值为：Application 和 JNDI。
- Application - 通过 CUBA 平台使用 HikariCP 库创建和管理连接池。推荐使用该模式。
- JNDI - 通过应用程序服务器创建连接池并放入 JNDI。CUBA 应用程序使用 JNDI 名称从 JNDI registry 获取数据源。
Database type - 数据库服务的类型。Studio 开箱支持 PostgreSQL、Microsoft SQL Server、Oracle、MySQL、MariaDB、Amazon RedShift 以及 HSQLDB。如果需要，也可以集成其他数据库，参阅本章节了解细节。
Database URL - 指定主机、端口以及数据库名称。
Connection params - 指定其他连接参数。连接参数的格式依赖所选的数据库。字符串需要在数据库名称和参数之间包含一个分隔符。比如，指定一个 Microsoft SQL Server 2008+ 实例名称，在该字段使用下列字符串：
```
;instanceName=myinstance
```
可以使用 Connection params 字段旁边的 “铅笔” 按钮方便的输入连接参数。此时，Studio 会使用数据库特定的分隔符将参数组成连接串。
Custom database URL - 指定一个自定义的数据库连接 URL。这里需要提供 Host 和 Database 名称，单独用于创建数据库。
Database user and Password - 数据库连接凭证。
Integrated Security - 当连接至 Microsoft SQL Server 2012+ 数据库时，启用相应的验证选项。

如果是 HSQLDB，Studio 本身会提供数据库服务，并将数据文件保存在 build/hsqldb 文件夹。

5.1.6.3. 用环境变量做连接参数

一些数据库连接参数可以通过环境变量指定。这样开发团队可以避免在版本控制软件中存储这些参数。支持下列参数：

database host,
database port,
database name,
user,
password.

数据存储需要设置 Define JDBC DataSource In 为 Application。

比如，定义环境变量：

PG_DB_HOST=127.0.0.1
PG_DB_NAME=salespg
PG_DB_USER=admin
PG_DB_PASSWORD=admin

重启 IDE 重新获取环境变量。然后修改 core 模块 app.properties 文件内的数据库连接配置：

cuba.dataSourceProvider=application
cuba.dataSource.username=${PG_DB_USER}
cuba.dataSource.password=${PG_DB_PASSWORD}
cuba.dataSource.dbName=${PG_DB_NAME}
cuba.dataSource.host=${PG_DB_HOST}
cuba.dataSource.port=

Studio 对该功能的支持：

Data Store Properties 对话框能正确检测并显示配置值。
Create database、Update database、Generate database scripts 和 Generate Model 操作能从环境变量取值。
调试用的 Tomcat 能从环境变量取值。

检测到的配置值在 Data Store Settings 窗口以只读的形式展示，如需改动，则需要手动修改 app.properties 文件。

5.1.6.4. 附加数据存储

You can add additional data stores to the project in order to store data in separate database, or to allow CUBA application reading data produced by another system.

如需在项目中创建附加数据存储，在 CUBA 项目树右键点击 Data Stores，选择 New → Additional Data Store。项目中注册的附加数据存储作为 Data Stores 部分的子项展示：

当创建或编辑数据存储时，会弹出 Data Store 对话框，有如下字段：

Data store name - 数据存储的名称。只能包含字母和下划线，并且不能与项目名称相同。
Data store type - 数据存储的类型：RdbmsStore 或 Custom，参阅文档了解细节。
DataSource JNDI name - Studio 基于数据存储的名称自动设置。
对于 RdbmsStore，需要指定下面描述的附加的属性。
DB schema management - 选择 Studio 管理数据库和跟踪实体变化的模式。

DB Schema 管理模式

与主数据存储不同，CUBA 应用程序和 Studio 对于附加数据存储的使用，有几种使用模式。

3rd-party database - 第三方数据库。在这个场景中，为 CUBA 应用程序接入一个由其他系统产生的数据库，目的是从数据存储级别做系统集成。此时，数据结构和数据格式都由外部系统完全控制，CUBA 不应当尝试修改或 drop 任何已有的表。不需要重新创建对应实体，而很大程度上可以通过 Studio 的生成模型功能导入。
Shared database - 共享数据库。在这个场景中，也是由于系统集成，为 CUBA 应用程序接入了已存在的数据库。但不一样的是，这里数据库的目的是在多个应用程序之间共享，CUBA 可以创建其自己的表，也可以修改已经存在的表。应用程序操作数据库的边界可以通过数据库角色权限控制。可以用实体设计器创建实体也可以通过生成模型功能导入。Studio 可以更新数据库 schema，但是不能重新创建数据库。
Owned database - 独享数据库。在这个场景中，数据库是计划完全由 CUBA 应用程序控制。Studio 可以重新创建数据库，因为项目的数据库模型有初始化数据库的所有信息。实体通过实体设计器创建。

根据上面介绍的场景，您可以根据需要决定用哪种方式管理数据库结构：

Disabled - Studio 不跟踪该存储的数据库结构变化。这是默认模式，以前版本的 Studio 也是这个行为。如果是接入 第三方 数据库，则推荐使用此模式。
Update Only - Studio 能生成数据库更新脚本并能根据数据模型更新数据库。但是，Studio 没法重新创建数据库。这个模式可以用在共享数据库场景。
Create and Update - Studio 创建完整的 初始化 和更新数据库的脚本，并提供从头创建数据库的能力（使用 Gradle 任务或者 UI 操作）。该模式可用在独享数据库场景。

5.1.6.5. 数据存储操作

在 CUBA 项目树右键点击数据存储可以看到菜单：

根据数据存储的类型和数据库 schema 管理模式，菜单内容会有所不同。

Delete Data Store - 从项目删除该数据存储，包括所有的配置文件及数据库迁移脚本。
Edit Data Store - 打开对话框编辑数据存储设置。
Create Database - 重新创建选择的数据存储。可用在主数据存储和 Create and Update 管理模式的附加数据存储。
Update Database - 更新选择的数据存储，运行那些还没有运行过的更新脚本。可用在主数据存储和 Update only 或 Create and Update 管理模式的附加数据存储。
Generate Database Scripts… - 为选中的数据存储生成 DDL 脚本，通过比较数据模型和数据库 schema 实现。可用在主数据存储和 Update only 或 Create and Update 管理模式的附加数据存储。
Generate Model… - 从选中的数据库生成数据模型。

5.1.6.6. 数据库初始化和更新脚本

主数据存储 和使用 Create and Update 或 Update Only shema 管理模式的附加数据存储可以使用数据库初始化和更新脚本，这些脚本显示在数据存储之下：

Init 脚本包含重新创建数据库的 DDL 和 DML 语句，建立数据库以匹配当前的数据模型状态。
Update 脚本包含更新数据库的脚本，可以对之前任意状态的数据库进行更新，以匹配当前的数据模型状态。

Studio 会根据数据模型的更改自动维护初始化和更新脚本，阅读数据库迁移部分了解更多细节。

如果需要，也可以创建附加的数据库脚本。只需在 CUBA 项目树的 Data Stores → Main Data Store 或 Data Stores → (Name of the additional data store) 部分使用下面的操作：

init → 右键菜单 → New → Database init script
update → 右键菜单 → New → Database update script

5.1.6.7. 附加 JDBC 驱动

当生成数据库迁移脚本时，Studio 会连接至数据库，因此需要数据库对应的 JDBC 驱动。Studio 默认包含下列 DBMS 类型的 JDBC 驱动：

PostgreSQL
HSQLDB
Microsoft SQL Server
MariaDB
MySQL（使用 MariaDB 驱动）

如果是用下列 DBMS 类型，则需要手动下载 JDBC 驱动并添加至 Studio：

Oracle
Amazon RedShift
MySQL（使用适当的驱动）

添加驱动可以通过配置界面操作：主菜单 → CUBA → Settings → Database Proprietary Drivers。

当集成自定义数据库时，需要手动复制驱动至 {USER_HOME}/.haulmont/studio/lib 文件夹（比如，windows：C:\Users\{username}\.haulmont\studio\lib）。此文件夹也可以用来存放已经支持的数据库的其他驱动程序。

手动添加驱动后，别忘了下面的步骤：

重启 IDE。
停止 Gradle daemon（在终端执行 gradlew --stop）。

5.1.7. 部署设置

Studio 中有一些与部署相关的编辑界面，用于对构建部署工件的 Gradle 任务进行设置。可以通过 CUBA > Deployment 主菜单打开这些编辑界面，也可以通过双击项目树中的 Project > Deployment 项来打开。

WAR 设置

WAR Settings 编辑界面允许设置 WAR 文件的构建配置。完成设置后，会在 build.gradle 中创建 buildWar 任务。

Build WAR - 如果选中，buildWar 任务会被配置在 build.gradle 中。
Include JDBC driver - 是否应将 JDBC 驱动程序包含在 WAR 文件中。
Single WAR for Middleware and Web Client - 是否构建将中间件和 Web 客户端应用程序 block 打包到一起的单个 WAR。
Custom web.xml path 指定用于单 WAR 的特定 web.xml 文件。单击 Generate 可自动创建此文件。
Logback configuration file - logback.xml 配置文件相对于项目根目录的路径。单击 Generate 以自动创建此文件。
对基于 CUBA 版本 7.2 及以上版本的项目：
- Custom data store configuration - 可以指定 WAR 工件要使用的自定义数据存储配置。
对基于 CUBA 7.1 及以下版本：
- Include Tomcat’s context.xml - 是否需要再 WAR 文件中包含 context.xml（Tomcat 部署描述文件）。
- Custom context.xml path - 相对于项目根目录指定 context.xml Tomcat 部署描述文件。如果勾选了 Include Tomcat’s context.xml，则启用该配置。点击 Generate 自动创建该文件。
App properties - 要为此部署定义的一组应用程序属性。这些属性会添加到 WAR 内的 /WEB-INF/local.app.properties 文件中。

如果在设置中开启了相应的属性，则会显示 Build WAR 子元素。点击会执行 gradlew buildWar 任务。

Uber JAR 设置

UberJAR Settings 编辑界面允许对 Uber JAR 的构建进行设置。完成设置后，会在 build.gradle 中创建 buildUberJar 任务。

Build Uber JAR - 如果选中，buildUberJar 任务会被配置在 build.gradle 中。
Single Uber JAR - 如果选中，buildUberJar 任务会将所有应用程序模块打包到一起，创建一个 Uber JAR。
Logback configuration file - logback.xml 配置文件相对于项目根目录的路径。单击 Generate 可自动创建此文件。
对基于 CUBA 版本 7.2 及以上版本的项目：
- Custom data store configuration - 可以指定 UberJAR 工件要使用的自定义数据存储配置。
对基于 CUBA 7.1 及以下版本：
- Custom Jetty environment file - 嵌入式 Jetty 服务使用的 jetty-env.xml 配置文件路径，相对于项目根目录。单击 Generate 可自动创建此文件。
App properties -要为此部署定义的一组应用程序属性。这些属性将被添加到 Uber JAR 内的 /WEB-INF/local.app.properties 文件中。
Core port、 Web port、 Portal port 字段允许为相应应用程序块的嵌入式服务设置端口。如果选中 Single Uber JAR，这些字段就不设置了。默认端口值在文档中有描述。在运行 JAR 时可以使用 -port 命令行参数设置端口。

如果在设置中开启了相应的属性，则会显示 Build UberJAR 子元素。点击会执行 gradlew buildUberJar 任务。

5.1.8. 配置接口

使用配置接口机制可以很方便的使用应用程序配置参数，通过 Java 接口方法实现，因此能提供对这些属性类型安全的访问。

Studio 在项目树的 Project → Config Interfaces 部分展示项目中所有的配置接口：

如需创建新的配置接口，在项目树选中 Config Interfaces ，然后在右键菜单中选择 New → Configuration Interface，然后会弹出 New CUBA Config 对话框：

Module - 选择配置接口所在模块
Class - 接口类名称
Package - 接口类包名
Source type - 选择属性值保存的位置：
- DATABASE - 属性值保存在数据库
- APP - 属性值保存在 app.properties 文件
- SYSTEM - 属性值从 JVM 的系统参数获取

可以在开发者手册相应章节了解更多配置接口的信息。

5.1.9. 日志

CUBA 项目树的 Logging 部分有以下目的：

展示本地 Tomcat 调试服务的日志文件
开发者可以创建并修改项目特定的日志配置。

日志文件展示在两个文件夹中，反映它们在文件系统的真实位置。当应用程序部署至生产环境时，也能看到同样的目录结构：

app_home.logs - CUBA 日志文件。这些日志在 logback.xml 配置。
tomcat.logs - Tomcat 日志文件。这些日志在 Tomcat 配置。

这里展示的 logback.xml 是一个自定义的日志配置文件，位于项目根目录的相对路径 etc/logback.xml 下。CUBA 用这个文件作为本地调试的 Tomcat 服务日志配置。默认也会用同一个文件作为 WAR 配置和 UberJar 配置中的日志配置文件。可以创建自定义的日志配置文件，右键点击 CUBA 项目树的 Logging，然后选择 Generate Logback Configuration File… ：

可以修改生成的 logback.xml 文件，比如，可以添加自己的 appender 并且根据类别限定日志的输入。参阅 logback 手册了解更多的日志配置。

5.2. 数据模型

在本节中，我们将介绍如何使用应用程序的数据模型。

5.2.1. 使用实体

创建新实体

在项目树中选择 Data Model 部分或它下面的包，然后从右键菜单中选择 New > Entity。
出现 New CUBA Entity 对话框。在 Entity name 字段中输入实体类的名称，选择实体及其 ID 的类型。
Studio 将创建实体类，根据实体类型的不同在 persistence.xml 或 metadata.xml 中进行注册。创建的类会在源代码编辑界面中打开。

Studio 在实体源码编辑器底部显示 4 个标签页。一起组成实体可视化设计器：

Text 包含源码。
Designer 显示实体设计界面，可以使用图形界面配置实体及其属性，而不用编写 Java 代码。
- Indexes 展示索引，并且可以为选中的实体创建新索引。
DDL Preview 包含相应表及其参考约束的只读 DDL 代码。

Tip	实体设计器只有激活 CUBA Studio 订阅才能使用。

创建实体属性

有多种方法可以向实体添加属性。

使用实体设计器的图形化界面：切换到 Designer 选项卡，单击 Attributes 表下方的 New 并填写 New Attribute 窗口中的必填字段。

Name 字段右边的地球仪按钮用于直接设置属性的用户友好名称。友好名称存储在 messages.properties 文件中，UI 组件默认使用这个文件来获取实体属性名称。如果为应用程序定义了多种语言，可以为所有语言指定本地化名称。
使用从源码打开的独立窗口。在源码中将光标定位在最后一个字段下方，然后按下 Alt+Insert (Cmd+N)。在 Generate 菜单中，选择 Add Attribute。Studio 将显示 New Attribute 窗口，和从图形界面打开的一样。在代码编辑器的操作面板，也可以点击 Add attribute 按钮打开同样的窗口。
还可以手动编写属性字段，生成 getter 和 setter 方法，然后在 Generate 菜单中选择 JPA Annotations，这样可以使用默认参数添加 JPA 注解。

Studio 可以帮助将新增的属性添加到包含该实体的 UI 界面。打开 Text 标签页，然后点击源码编辑器顶部的 Add attributes to screens 操作。Studio 会搜索所有使用当前实体的界面，并分析哪些属性可以添加至这些界面的组件内。然后可以在对话框中选取需要的属性和界面组件：

还有一个类似功能的 Add to Screens 按钮，在实体的 Designer 标签页中 Attributes 表格的上方。

创建实例名称

可以用作另一个实体的引用属性的实体（例如 Customer 可以是 Order 的属性）需要一个 pattern 来生成实例的有意义的名称。此 pattern 由实体类上的 @NamePattern 注解定义。

如果您使用实体设计器编辑实体，可以有两种方式设置实体实例名称：

使用可视化构建器。可以点击 Instance name 字段的铅笔按钮：
自动模式。实体设计器检测到为实体添加下列属性之一时会自动生成实例名称：name、title、caption、label、summary、description、firstName、lastName、middleName。

实例名称还可以从实体的源代码创建，将光标定位在类名称上，按 Alt+Enter（Option+Enter）并选择 Add name pattern（仅当实体没有 @NamePattern 注解时才显示此项）：

按 Enter 键，Studio 将显示实体的所有属性列表。选择一个或多个属性，然后按 Enter 键。Studio 将在实体类上生成 @NamePattern。

为新属性创建消息: 手动创建新的实体属性时，其名称会高亮突出显示，以提醒在相应的消息包中创建用户友好的属性名称：

在突出显示的属性上点击 Alt+Enter（Option+Enter），然后选择 Create message in the message bundle：

DDL 生成设置

Designer 标签页还可以配置 DDL 生成设置，能修改 Studio 为该实体生成数据库迁移脚本的方式。

移除实体: 要移除实体，使用 Safe delete 选项查找并清理对实体的引用：

对实体的一些引用会被自动删除，比如在 persistence.xml 和 metadata.xml 文件中对实体的引用。如果存在对实体的引用，将会弹出一个对话框显示这些引用。点击对话框上的 View Usages 按钮, 可在 Find 工具窗口中查看这些引用，这时可以根据情况点击 Cancel 或 Do Refactor 按钮。

5.2.2. 使用枚举

Studio 提供一组操作和可视化设计器帮助在应用程序中使用枚举。

枚举与实体一并在 CUBA 项目树的 Data Model 部分展示。

创建新的枚举

在项目树中选择 Data Model 或者其下面的一个包名，右键点击后选择 New > Enumeration 。
弹出 New CUBA Enumeration 对话框。在 Class 字段输入枚举类的名称，选择包名，Id 类型（推荐 String）。

Studio 将会创建枚举类，创建的类会在源码编辑器打开。编辑器的底部会显示两个标签页：
- Text 包含源代码。
- Designer 显示枚举设计器，这里可以使用图形界面配置枚举和值（常量），避免写 Java 代码。

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

Name 列用于输入代码中使用的常量名称。这个名称可以后期修改而不影响数据库已经存在的数据。
Value 列用于输入枚举常量的 id。这是数据库保存的实际值。
地球按钮用于为选中的常量设置本地化名称（用户友好名称）。

设计器也提供将枚举的 Id type 从 String 修改为 Integer（或反过来）的功能。只需要打开枚举设计界面然后切换 Id type 的值。Studio 会自动在代码中对使用该枚举的地方做代码迁移。之后，您可以修改已有的枚举常量。注意，这种改动不会对数据库表格已存在的枚举值做改动，需要手动做数据迁移，比如可以通过一个数据库的更新脚本来实现。

5.2.3. 使用视图

视图是对象关系图的一种描述，当实体从数据库加载时，用视图定义需要从数据库加载哪些属性、集合以及子实体。视图可以在界面描述中定义，也可以在单独的 views.xml 共享文件中定义，在后者定义的视图全局可用。

要为实体创建新的共享视图，请在项目树中选择实体，然后在右键菜单中点击 New > View。

会弹出视图编辑对话框，包含以下字段：

Entity name - 要创建视图的实体的名称。
Name - 新视图的名称。
Extends - 内置或自定义视图，新视图会扩展其属性。任何实体都有三种内置视图：
- _local 包含实体的所有本地属性（不引用其它实体的属性），
- _minimal 包含名称模式中列出的属性，
- _base 包括所有本地非系统属性和由 @NamePattern 定义的属性（实际上是 _minimal +_local）。
Configuration file - 用于存储此视图的视图配置文件。默认情况下，Studio 在 global 模块中生成一个 views.xml 文件。

当前实体的完整属性列表显示在字段下方的树中。可以通过选中属性前面的复选框来选择要包含在视图中的属性。

如果视图继承另一个视图，则会选中所有继承的属性，并禁用相对应的复选框。

如果选择引用属性，则右侧面板中会显示以下属性：

Entity - 引用的实体名称。
View - 加载引用实体的可选视图。建议使用已命名视图而不是临时指定视图属性，因为这样可以更容易地维护复杂视图。此外，即使指定了视图名称，仍然可以通过选择属性树中的复选框来添加视图中未包含的属性。
Fetch - 用于引用属性的可选设置，指定如何从数据库中获取相关实体。有关详细信息，请参阅文档。

单击 OK 关闭设计界面后，可以在实体下的项目树中找到新视图：

视图设计器

如果双击项目树中的视图项，Studio 将在代码编辑界面中打开 views.xml 并将光标定位在点击的视图定义处。代码编辑界面底部有两个选项卡：Text 和 Structure。Structure 标签显示此配置文件中定义的视图列表，并能可视化构建视图定义：

可以通过多种方式打开视图的图形设计界面：

在项目树中选择视图，然后单击 Edit View 右键菜单项。
将光标定位在配置文件代码中的视图元素上，按 Alt+Enter（Option+Enter），在弹出菜单中选择 Edit view，然后按 Enter 键。
切换到配置文件代码编辑界面的 Structure 选项卡，选择视图并点击 Edit 按钮。

使用视图设计器可以安全的重命名视图，能自动修改所有用到修改之前视图名称的地方。如需重命名视图，点击 Name 字段右侧的小铅笔按钮编辑即可。

Tip	视图设计器需要激活 CUBA Studio 订阅才能使用。

手动编辑视图

也可以手动修改 views.xml 的源码来编辑视图定义。Studio 对视图配置文件的 XML 结构提供了完善的代码辅助支持。

当在 XML 中编辑视图定义时，使用 Ctrl+Space 启用属性名称自动完成功能：

需要注意高亮的属性，很可能他们不存在：

5.2.4. 数据库迁移

Studio 能够创建 DDL 脚本，以使数据库架构与项目的数据模型保持同步。生成的脚本可以从 Studio 直接执行，也可以由 Gradle 任务执行，还可以在应用程序本身启动时执行。

可以为下列情况创建 DDL 脚本：

主数据存储
附加数据存储，需要使用 Create and Update 或 Update Only schema 管理模式。

有下列操作可以生成 DDL 脚本：

从主菜单选择 CUBA > Generate Database Scripts - 这里是为所有的数据存储生成脚本。
在项目树选择 Data Model 然后点击右键菜单的 Generate Database Scripts - 这里是为所有的数据存储生成脚本。
在 CUBA 项目树选择特定数据存储的节点，然后右键点击，菜单中选择 Generate Database Scripts - 这里只为选中的数据存储生成脚本。

然后 Studio 会打开 Database Scripts 窗口：

左侧的面板按数据存储对脚本做了分组。只有支持 DDL 脚本的数据存储才会显示。

数据库脚本有以下分类：

Updates

Updates 显示用来将数据库更新为数据模型当前状态的脚本。右侧的表格展示脚本列表，底部展示脚本内容。如果您的项目包含未执行的更新脚本，则会在左侧树高亮显示对应节点。更新脚本保存在 modules/core/db/update 或 modules/core/db/update_{additional_data_store_name} 目录。这些脚本具有自动生成的名称，通过前缀定义执行顺序。包含 DROP 语句的脚本以红色突出显示。

可以通过单击 Create 按钮添加任意脚本，添加的脚本后续将与自动生成的脚本一起保存并执行。

单击 Remove 按钮可以编辑或完全删除新生成的脚本。

如果单击 Exclude selected （排除），这时会两个选项：

将脚本移动到手动执行的脚本目录：modules/core/db/update-manually 或 modules/core/db/update-manually_{additional_data_store_name}。然后当运行 Update database 时，脚本不会自动被执行，但可以在需要时手动运行它。此选项对于用于删除先前重命名为 *__UNUSED 的表或列的脚本非常有用。
排除脚本：排除的脚本不会保存到 modules/core/db/update 目录中，而是记录在项目文件夹中的 studio-intellij.xml 文件中。再次生成脚本时，Studio 将忽略与排除脚本相对应的更改。这样就允许数据库架构和实体模型之间存在差异。

例如，可能希望在对应项目实体的一个表中添加数据库字段，但不将其映射到实体属性。当 Studio 生成了从数据库中删除该字段的脚本时，只需将其排除，Studio 将不再生成同样的脚本。

Init Tables

执行 Create Database 时，Init Tables 脚本会在 Init constraints 和 Init data 脚本之前执行，并创建所有的表。开发人员可以编辑脚本，但要需要保留分隔表的注释。该脚本保存在 10.create-db.sql 文件中。

Init Constraints

Init Constraints 脚本在 Init tables 脚本之后执行，创建完整性约束。开发人员可以编辑该脚本，但需要保留分隔表的注释。该脚本保存在 20.create-db.sql 文件中。

Init Data

Init Data 脚本允许插入额外的数据或数据模型中不存在的数据结构信息。在初始化结束时执行。该脚本保存在 30.create-db.sql 文件中。

如果项目包含应用程序组件（扩展），但是此组件不为当前数据库提供 DDL 脚本，Studio 会为组件生成脚本，并在 Init {component} tables 和 Init {component} constraints 部分显示。脚本分别保存在 01.{component}-create-db.sql 和 02.{component}-create-db.sql 文件中。

单击 Save and close 以保存所有生成的脚本。可以在 Project > Data Stores > Main Data Store 项目树部分中找到脚本。

要运行更新脚本，先停止应用程序服务器（如果在运行），然后从 CUBA 主菜单执行 Update Database 或 Update All Databases。如果只想更新一个数据存储，可以在 CUBA 项目树选中该存储节点，然后在右键菜单中选择 Update Database。

如果要使用初始化脚本从头开始重新创建数据库，请执行 Create Database 或 Create All Databases。如果只想重新创建一个数据存储，可以在 CUBA 项目树选中该存储节点，然后在右键菜单中选择 Create Database。

实体 DDL 脚本生成配置

可以在实体级别自定义 Studio 数据库迁移脚本的生成行为。实体设计器的 Designer 标签页能配置当前实体的 DDL generation settings ：

DB script generation mode - 选择合适的模式：
- CREATE_AND_DROP - 默认模式。当生成 DDL 脚本时，Studio 可以在数据库创建表、列以及约束，并且可以在列或约束对应的数据模型属性不存在时 drop 掉列或约束。可以根据数据模型创建 init 和 update 脚本。
- CREATE_ONLY - 在生成 update 脚本时，Studio 不会尝试 drop 列或约束。可以根据数据模型创建 Init 脚本。
- DISABLED - Studio 不为该实体创建任何 init 和 update 脚本。
Unmapped columns - 一组只在数据库存在的列而没有对应的实体属性。Studio 不会尝试 drop 掉这些列。
Unmapped constraints - 一组只在数据库存在的约束而没有对应的实体属性。Studio 不会尝试在 update 脚本中 drop 掉这些约束。

这些设置也可以在源码手动配置，参阅 com.haulmont.cuba.core.global.DdlGeneration 注解（最低要求平台版本：7.1.6 或 7.2.2）。

5.2.5. 生成数据模型

Studio 允许为现有数据库创建数据模型和标准 UI 界面。单击 CUBA > Advanced > Generate Model 主菜单项或在项目树中选择 Project > Data Stores，然后在右键菜单中点击 Generate Model。如果有多个数据存储，Studio 会显示一个对话框，可以选择其一。

然后 Studio 打开 Generate Model from Database 向导。

步骤 1

这是模型生成向导的第一步。

可选步骤：单击 Settings 以设置创建的新实体的 Java 包位置以及实体的系统属性与数据库列的默认映射。

例如，如果数据库中的所有或大多数表包含 Modified 和 ModifiedBy 列，则可以将它们映射到被创建的实体的 Updatable.updateTs 和 Updatable.updatedBy 属性。在这种情况下，无需为每个表单独映射它们。

使用 Exclude columns from mapping 列表可以为所有表设置不需要映射到属性的列。

向导中会列出在项目数据模型中没有对应实体的表。可以使用上面的过滤器字段按名称查找表。

选择要映射到数据模型的表。某些表通过外键依赖于其它表，因此当选择这些表时，它所依赖的所有表也将被选中。如果取消选择一个表，则也会取消选择所有依赖它的表。

可以通过单击右侧的复选框来选择或取消选择所有可用表。

单击 Next。

步骤 2

在此步骤中，可以查看和编辑为所选表的自动生成的映射。

Status 列描述自动映射的结果：

OK - 自动映射成功，所有列都映射到新实体。
Join table - 识别出实体之间的关联，会被映射为多对多关系的连接表。
There are unmapped columns - 某些列无法映射到新实体。
New PK will be created - 该表没有主键。将创建一个新的 UUID 类型的主键。
Composite PK will be replaced - 该表具有复合主键，但没有其它表引用它。复合主键将被替换为 UUID 类型的主键。
Composite PK referenced by other tables - 该表有一个复合主键，一些表引用它。Studio 无法映射此类表。
Unsupported PK type - 该表具有不支持的主键类型。Studio 无法映射此类表。
Choose primary key for DB view - 它是一个数据库视图，应该选择适合作为实体标识符的一列或一组列。在这种情况下，单击 Choose PK 按钮并选择主键的列。

Refresh mapping 按钮允许重新运行所选表的自动映射。例如，可以切换到数据库 SQL 工具，对数据库架构进行一些更改，然后返回到向导并再次执行映射过程。

Edit mapping 按钮打开一个包含映射详细信息的对话框窗口。在这里，可以更改实体名称和实体类要实现的系统接口。根据实现接口的不同，为了兼容 CUBA 的实体，会影响数据库列的创建数量。

当选中的是数据库视图并且需要选择用于实体标识符的列时，将显示 Choose PK 按钮而不是 Edit mapping。

通过单击 Back，可以返回到上一步以选择或取消选择表。

单击 Next 转到下一步。

步骤 3

在此步骤中，可以指定应为新实体创建哪些 UI 界面。

如果取消选中 Create standard screen 复选框，Studio 将不会为新实体生成 UI。

使用 In module 、Package 和 Menu 字段指定界面源代码的位置以及在主菜单中它们的显示位置。

使用 Standard screens 列中的下拉列表选择要生成的界面类型。

可以安全地跳过此步骤，并在完成模型生成过程后为实体生成 UI 界面。

单击 Next 转到下一步。

步骤 4

这是模型生成向导的最后一步。

Import scripts 表包含将在数据库上执行的脚本列表，查看这些脚本，以确认其符合要创建的实体。

在此之前，项目中不会创建任何内容，甚至也不会保存到磁盘中。Studio 实际上只会在点击 Run all scripts 或 Run script 时生成实体和界面并保存脚本。

可以在此页面上查看和编辑脚本，然后运行它们，或者仅保存脚本，稍后通过数据库管理工具来运行。导入脚本保存在 modules/core/db/import 目录中。

5.2.6. 集成自定义数据库

如文档中所述，框架允许使用 EclipseLink ORM 支持的任何 DBMS 作为项目数据库。Studio 可以帮助创建此类集成所需的文件。

在菜单中选择 CUBA > Advanced > Define Custom Database。

在打开的窗口中可以设置新自定义数据库的属性。根据这些属性，Studio 会针对数据库生成设计时和运行时的支撑代码。

DB type id - 用于 cuba.dbmsType 应用程序属性的数据库类型标识符。
DB type name - 要在 Studio 中显示的数据库类型的用户友好名称。

单击 OK 后，Studio 会在 com.haulmont.cuba.core.sys.persistence 中生成 Java 类，并在项目的 com.haulmont.studio.db.{db_id} 包中生成 Groovy 类。自动生成的示例实现适用于 Microsoft SQLServer 数据库，需要适当地对其进行一些修改。

首先，修改 com.haulmont.studio.db.{db_id}.{db_id}DbProperties 类。当此类适配了新的数据库时，将能够在 Studio 中将项目切换到此数据库。重新打开项目在数据库类型下拉列表中查看新数据库。

要在运行时连接到新数据库，请修改 com.haulmont.cuba.core.sys.persistence 包的 {db_id}DbmsFeatures 和 {db_id}DbTypeConverter 类。{db_id}SequenceSupport 类仅用于生成整数标识符和唯一编号。

最后，修改 com.haulmont.studio.db.{db_id}.{db_id}DdlGenerator 类，以便在需要时可以由 Studio 正确生成 init 和 update 数据库脚本。如果不需要为此数据库生成 DDL 脚本，可跳过此步骤。

为主数据存储初始化数据脚本

如果将自定义数据库用作主数据存储，则在生成数据库脚本时，Studio 将为所有应用程序组件（包括 CUBA）创建 init 脚本。这些脚本不包含一些必须的初始化数据，因此必须将以下内容添加到项目的 Init data 脚本中（30.create-db.sql），事实上，对于版本 7.2.0：

insert into SEC_GROUP (ID, CREATE_TS, VERSION, NAME, PARENT_ID)
values ('0fa2b1a5-1d68-4d69-9fbd-dff348347f93', now(), 0, 'Company', null)^

insert into SEC_USER (ID, CREATE_TS, VERSION, LOGIN, LOGIN_LC, PASSWORD, PASSWORD_ENCRYPTION, NAME, GROUP_ID, ACTIVE)
values ('60885987-1b61-4247-94c7-dff348347f93', now(), 0, 'admin', 'admin',
'$2a$10$vQx8b8B7jzZ0rQmtuK4YDOKp7nkmUCFjPx6DMT.voPtetNHFOsaOu', 'bcrypt',
'Administrator', '0fa2b1a5-1d68-4d69-9fbd-dff348347f93', true)^

insert into SEC_USER (ID, CREATE_TS, VERSION, LOGIN, LOGIN_LC, PASSWORD, NAME, GROUP_ID, ACTIVE)
values ('a405db59-e674-4f63-8afe-269dda788fe8', now(), 0, 'anonymous', 'anonymous', null,
'Anonymous', '0fa2b1a5-1d68-4d69-9fbd-dff348347f93', true)^

insert into SEC_USER_ROLE (ID, CREATE_TS, VERSION, USER_ID, ROLE_NAME)
values ('6736effb-9dfc-4430-973a-69868606b09c', current_timestamp, 0, '60885987-1b61-4247-94c7-dff348347f93', 'system-full-access')^

添加 JDBC 驱动

当生成数据库迁移脚本时，Studio 需要对应数据库的 JDBC 驱动。使用自定义数据库，需要手动下载驱动文件并放置于 {USER_HOME}/.haulmont/studio/lib 目录（比如 windows 上：C:\Users\{username}\.haulmont\studio\lib ）。

在文件夹添加完驱动之后，别忘做下面几步：

重启 IDE。
停止 Gradle daemon（在终端执行 gradlew --stop）。

集成 Firebird 数据库示例

集成自定义数据库（Firebird）至 CUBA 和 Studio 的示例可以在这里找到： https://github.com/cuba-labs/firebird-sample 。这个例子也可以作为扩展插件添加至您的项目以支持 Firebird 数据库。

5.3. 业务逻辑

项目树集中在一个地方显示所有中间层服务、Spring bean 以及集成测试。在下面的章节中，我们将介绍如何创建新服务、bean 和测试。

5.3.1. 创建服务

服务是容器管理的组件集，它们构成中间层边界并为客户端层提供接口。服务可以包含业务逻辑本身，也可以将执行委托给托管 Bean。

要创建新服务，请选择 Business Logic 项目树区域，然后在右键菜单中单击 New > Service：

输入服务接口的名称时，将自动生成相应的 bean 名称和服务名称常量：

之后，将在 global 模块中创建服务接口，并在 core 模块中创建其实现。此外，新服务将自动注册在 web-spring.xml 配置文件中。

可以从代码编辑器边栏上的标记轻松地从接口切换到服务 bean 并返回：

一旦在服务接口中创建了方法，Studio 检查器就会建议在 bean 类中进行实现：

5.3.2. 创建 Spring Bean

Studio 在项目树的 Business Logic → Beans 部分显示中间层（包括实体和事务监听器）的所有 Spring beans。Bean 按照它们所属的模块分组：core，global，web，portal。

要创建 Spring bean，选择项目树的 Business Logic → Beans 节点，并在右键菜单中选择 New > Bean：

Module - 选择新建 bean 放置的模块
Class - bean 的类名
Name - bean 的唯一名称。当输入类名后，会自动生成

5.3.3. 创建 JMX Beans

JMX Beans 是一类特殊的 Spring bean。系统管理员用 JMX bean 在运行时查看和更改应用程序的运行状态。这些 bean 通常用来提供统计信息、监控信息、修改配置以及其他一些系统内部操作。

Studio 在项目树的 Business Logic → Beans 与其他 bean 一起展示 JMX bean。JMX bean 可以在项目的 core，global，web 模块创建。

如需创建 JMX bean，在项目树选中 Business Logic → Beans ，然后在右键菜单中选择 New → JMX Bean，然后会弹出 Create JMX Bean 对话框：

Module - 选择新建 bean 放置的模块
Interface Class - bean 接口名称。此接口包含将会开放给 JMX 的方法。名称需要以 MBean 结尾
Bean Class - bean 的类名
Bean Name - bean 的唯一名称。当输入接口名后，会自动生成
Package - bean 包名
Description - bean 描述，将在 JMX 客户端（比如 CUBA 自带的 JMX Console ）展示给用户。

5.3.4. 创建事件监听器

事件监听器是指，在 Spring bean 中，有一个或者多个监听器方法，接收 Event 对象作为参数，并包含对该事件响应的代码。可以在开发者手册中了解更多关于事件和事件监听器的内容。

Studio 可以为多种应用程序事件创建监听器的脚手架代码：

可以生成新的监听器类或者为已有的类添加监听器。

新建监听器类: 要创建新的监听器类，在 CUBA 项目树的 Business Logic 部分点击右键，选择 New → Event Listener 条目。

对话框中可以选择监听器类所在的模块。事件监听器可以位于 web 模块，但是此时只有有限的事件可以使用。选择事件类型，按照向导提供所需的参数并点击 Finish 按钮生成类代码。

为已有类添加监听器方法: 打开已有的 Spring Bean，在代码编辑器顶部的操作面板点击 Subscribe to event：

5.3.5. 创建集成测试

CUBA 应用程序可以用众所周知的方式进行测试：单元测试、集成测试以及界面测试。Studio 为开发者提供下列种类的测试支持：

中间件集成测试。这种类型的测试用来测试中间件功能：服务，bean，事件监听器，ORM 逻辑以及与数据库通信。中间件测试在一个能连接至数据库的全功能 Spring 容器中运行。
Web 集成测试。这些测试用例运行在 web 客户端 block 的 Spring 容器中。Web 测试容器与中间件测试容器分别独立运行，框架负责创建中间件服务的桩代码。

这两组测试都在 CUBA 项目树的 Business Logic → Tests 部分展示，按模块分组：

如需创建新的集成测试，在项目树选中 Business Logic → Tests ，然后在右键菜单中选择 New → Integration Test (Middleware) 或 Integration Test (Web)：

如果您的项目还没有测试代码根目录或者没有测试容器，Studio 会在创建文件和类之前显示一个额外的确认弹窗。

在这个弹窗中，需要输入以下参数：

Class Name - 测试类名
Package - 测试类的包名
Test container class - 测试容器类名。默认会自动创建 Common 容器，但是也可以创建其他容器类，比如，使用其他的 DBMS 测试应用程序。
Testing library - 选择 JUnit5 或 JUnit4。注意，使用 CUBA 7.1 和以下版本创建的项目，即便迁移到了 CUBA 7.2，也只支持 JUnit4。

5.4. 通用 UI

Studio 提供了许多有助于在应用程序中使用通用 UI 的功能。

在项目树中，可以看到 Generic UI 的以下元素：

Web Menu 打开主菜单的图形编辑界面。
Main Message Pack 部分包含主菜单项和通用 UI 元素的消息。
Screens 部分显示已有的应用程序界面。
Themes 用于管理应用程序的可视化展现。

5.4.1. 创建和移除界面

要创建新的 Generic UI 界面，请在项目树中选择 Generic UI，然后在右键菜单中选择 New > Screen。如果要为实体创建 CRUD 界面，请在项目树中选择此实体，然后在右键菜单中点击 New > Screen ：

Studio 将显示可用模板的列表。该列表分为两部分：Screen Templates 和 Legacy Screen Templates。前者包含框架版本 7 以上可用于新界面 API 的模板，而后者包含也可用于版本 6 的界面模板。

如果为在项目树中选中的实体创建界面，则 Entity 字段会自动填充：

Advanced 部分允许修改自动生成的界面描述和控制器名称以及界面 ID。当某个实体有多个界面时，这很有用。

Entity browser view 和 Entity editor view 的向导步骤中，可以选择需要展示在数据表格或者编辑界面表单中的数据。这些选中的属性也会作为实体视图用来加载实体至界面：

点击 Finish 之后，会自动创建界面 XML 描述，Java 控制器以及消息包文件，并在源码编辑器打开。对于不使用 UiDescriptor 或 @UiController 注解的遗留界面，界面描述文件会在 web-screens.xml 文件中注册。

移除界面

移除界面文件时，使用 Safe delete 选项查找并清理对这个界面的引用：

如果 web-menu.xml 和 web-screens.xml 文件中也存在删除界面的引用，则这些引用会被自动删除。如果还有其他引用，则会显示关于这些引用还在使用的警告。点击对话框中的 View Usages，查看 Find 工具窗口中的这些引用，根据需要选择 Cancel 或 Do Refactor：

5.4.1.1. 自定义界面模板

Studio 支持自定义界面模板，可以从标准界面模板复制到项目，然后做自定义修改，比如修改界面描述的模板文件，界面控制器甚至在界面向导中添加新的参数。

选择需要自定义的模板，然后在 Create CUBA Screen 向导的第一步点击 Copy template 按钮，即可创建自己的界面模板。输入自定义模板的代码名称。模板文件会复制到项目，可以手动修改。自定义的界面模板展示在 CUBA 项目树的 Generic UI → Screens → Custom Templates 部分。

可以修改界面控制器和描述的模板文件，通过扩展 settings.xml 文件甚至可以为向导添加新的参数。

New → Screen 向导的第一步中，Project Templates 标签页可以选择自定义的界面模板：

自定义模板示例

示例如下，需要根据向导中输入的参数调整实体浏览界面的宽高：

编辑 settings.xml 添加如下标签：

<property caption="Dialog Width" code="dialogWidth" propertyType="INTEGER" defaultValue="800" preferences="true"/>
<property caption="Dialog Height" code="dialogHeight" propertyType="INTEGER" defaultValue="600" preferences="true"/>

编辑 descriptor.xml，修改 dialogMode 标签声明如下：

<dialogMode height="${dialogHeight}"
            width="${dialogWidth}"/>

如果在界面向导中使用新修改的模板，则能看到向导中新添加的参数：

5.4.2. 使用界面描述

界面 XML 描述编辑器与 Screen Designer 集成在一起。界面设计器展示一组操作面板和工具窗口，可以用来开发界面的布局并以所见即所得的形势设置 UI 组件的属性。您可以直接编辑 XML 或使用设计器的面板生成代码。

Screen Designer 由下列元素组成：

Source code editor - 展示并编辑 XML 源码。
Top actions panel - 提供一些便于访问的操作。
Layout preview panel - 展示交互式的界面布局架构。
Component Hierarchy - 以层级树的形势展示界面元素。
Component Palette - 展示可以添加到当前界面的组件。
Component Inspector - 展示并编辑组件的属性和事件处理器。

Tip	界面设计器面板和工具窗口只有购买了 CUBA Studio 商业订阅才能使用。

顶部操作面板

操作面板位于代码编辑器的顶部。提供下列操作的访问：

Controller - 导航至界面控制器。
<entity class name> - 如果当前界面是实体浏览器或者编辑器时会显示。可以导航至关联的实体。

也可以用侧边栏的标记在界面描述和其控制器之间切换。

工具窗口: Component Hierarchy、Component Palette 和 Component Inspector 面板是 IDE 中独立的工具面板。当在编辑器打开界面描述时，会自动打开这些工具窗口。如果在编辑器中切换界面描述文件，工具窗口的内容也会同步更新。有时候，当打开其他工具窗口时（比如 Gradle、Persistence 等），设计器的某些窗口会被隐藏，可以通过点击 IDE 窗口左右的相应按钮重新打开。

保留在左下角展示 Component Inspector 是为了满足熟悉之前布局的开发者们。如果需要将该面板移至右侧，点击面板标题的 Move to Right Bottom 即可。

设计器面板会在编辑 XML 代码时激活。熟练开发者们通过编辑 XML 源码切换和修改界面描述，他们现在也能获得界面设计器的编辑功能帮助。可以从工具箱拖拽新组件至层级树，当编辑器只显示源码时，也可以在左下角的探查面板修改组件的排序和编辑组件属性。源码会直接同步所有改动。

布局预览面板

Layout Preview - 布局预览面板 展示交互式的界面布局架构。与界面描述的源码编辑面板共享编辑器的空间。现在在界面描述的右上部添加了四个按钮用于切换界面预览模式：

Editor only - 在编辑器只显示源码。
Editor and Preview - 编辑器空间分割，包含源码和预览。
Preview only - 只显示预览。
Preview in Window - 源码在编辑器展示，但是预览通过单独的窗口展示，可以将预览窗口移至其他显示设备。

面板在右上角有一些控制按钮：

100% x 100% 下拉框可以选择固定的 画布大小。画布的大小可以比预览面板大，此时会添加额外的滚动条。例如，如果在开发一个复杂的界面，带有很多控制组件，如果想预览，可以选择 1920 x 1080 画布大小，然后查看布局在大屏上如何展示。
Refresh 按钮重新加载预览界面的内容。
Zoom In、Zoom Out 和 Zoom Reset 按钮更改预览界面的缩放。
最右边的按钮展示自动界面布局问题检测的结果。移动光标至这个图标可以看到发现的问题。

在 Layout Preview 面板中，也可以排布组件以达到需求的布局。组件可以用控制进行缩放和对齐：

水平延展，
垂直延展，
水平、垂直对齐组件。

组件工具箱

Component Palette 工具窗口展示在 IDE 的右下角。显示可用的界面组件：

Containers - 容器；
Components - 组件；
Data Components - 数据组件：containers - 数据容器和 loaders - 数据加载器；
Non-visual - 非可视化组件：actions - 操作、 dialog mode settings - 对话框模式设置，timers - 定时器以及其他辅助的界面元素；
Main window - 主窗口: 主界面特定的组件。

可以通过在搜索框输入名称的方式在工具箱搜素组件。

要在布局中添加一个组件，可以直接从工具箱拖拽组件至: * Component Hierarchy 面板。 * 或者 XML 代码中合适的位置。

在工具箱右键点击组件，可以使用下列操作：

Add to Design - 添加选中的组件至界面，放置位置通过在层级树中选中元素决定。
CUBA Documentation - 打开组件在开发者手册中的文档页。

组件层级树

Component Hierarchy 工具窗口展示在 IDE 的右上角。以树的方式展示布局中的组件结构。

可用拖拽的方式修改树中元素的位置。

右键点击层级树中的元素，可以使用下列操作：

Convert 将组件转换为类似的其他组件。
Wrap 将组件放入建议的容器中。
Go to XML - 切换至源码中相应的 XML 标签。
Inject 将元素注入界面控制器或者导航至已经注入的声明。
Delete、Copy、Cut Paste 删除、复制、剪切、粘贴组件。
CUBA Documentation 打开选中组件的文档。

组件 Inspector

Component Inspector 工具窗口显示在 IDE 的左下角。展示并编辑选中组件的属性：

Properties 面板展示可视化组件的属性。
Handlers 面板展示可以与选中组件关联的事件监听器和组件委托。如要生成所需的处理器方法，只需双击相应的条目。

可以在搜索字段中输入文字快速定位属性：

对于某些选中的元素会显示 + Add 按钮，提供添加子元素的一个快捷方法，比如添加表格操作、列、表单字段。如果所选组件是：

Table、Grid 或其操作和列之一 - 可用：Add → Column, Add → Group, Add → Action
Form 或其列和字段之一 - 可用：Add → Column, Add → Field
DataLoadCoordinator - 可用：Add → onScreenEvent trigger 以及其它触发器

支持自定义 UI 组件

界面设计器可以集成在扩展插件或者项目中的自定义 UI 组件，这些组件需要使用特定的注解。集成之后，可以在 Component Palette - 组件工具箱 展示自定义组件，其属性也可以在 Component Inspector 面板编辑。自定义 UI 组件的支持需要 CUBA 平台版本 7.1.7 或 7.2.5 以上。

参阅开发者手册中相关内容了解关于自定义 UI 组件元数据的更多内容。

源码检查

Studio 会检查界面布局是否存在错误和不一致，并且检查内部和外部引用。出现下列情况，会用警告或高亮显示 XML 元素的方式进行提醒：

由于 XML 错误，无法组装界面布局。
组件属性路径和名称与应用程序数据模型不对应。
组件大小冲突： width 、 height 和 expand 属性值的冲突。
dataContainer 和 dataLoader 属性没有引用任何现有的数据容器或数据加载器。
form 中的字段没有显式定义 property XML 属性：此时，id 将被隐式地用作 property。
form 元素语义错误：字段重复或位于 column 元素之外。
gridLayout 中的列数与指定的数字不匹配。
在扩展界面中出现重复的元素属性，比如父界面和扩展界面中同时定义了完全一样的属性时。
扩展界面中的元素的命名与父界面中不同，或者放置位置不正确。
messagesPack 属性指定的值不是一个有效的包，这个包要至少包含一个 messages_xx.properties 文件。
过时的 XSD 引用。
id 值在界面内不是唯一的。
其它问题。

可以在 Settings 窗口中配置 CUBA 检查器（CUBA > Settings > Editor > Inspections）。

源码意图和生成菜单

意图操作（Intention action）是一个上下文敏感的操作，开发者可以在源码编辑器通过按下 Alt+Enter（Option+Enter）调用。意图操作可以帮助代码重构、代码生成、导航和其他任务。可以在 https://www.jetbrains.com/help/idea/intention-actions.html 阅读更多关于意图操作的内容。

Generate - 自动生成 菜单包含上下文敏感的操作，可以帮助生成各种代码结构。可以通过按下 Alt+Insert（Cmd+N）调出。参阅 https://www.jetbrains.com/help/idea/generating-code.html 了解更多。

Studio 中包含的意图和生成菜单条目提高了使用界面组件的效率。使用 Alt+Insert（Cmd+N）和 Alt+Enter（Option+Enter）查看对于特定 UI 和数据组件的功能。

例如，要为表单组件添加一个新字段，可以将光标移入 form 元素然后执行下列操作的一项：
- 按下 Alt+Insert (Cmd+N)，选择 Add field，然后选择 property 属性的值，
- 输入 field 然后按下 TAB 键，然后选择 property 属性的值。
另一个例子是为一个组件添加新的本地化语言标题。可以在源码中输入还未创建的消息键值。则引用的元素会高亮红色。然后按下 Alt+Enter（Option+Enter）并选择 Create message in the message bundle：

5.4.3. 使用界面控制器

本节介绍 Studio 为界面控制器提供的功能。

利用源码编辑器的边栏图标可以快速切换到相应的 XML 描述文件、定位到注入组件的 XML 定义以及其它导航功能。

顶部操作面板

操作面板位于控制器代码编辑器的顶部。展示下列操作：

Descriptor - 切换至对应的界面描述文件
<entity class name> - 切换至当前浏览界面或者编辑界面关联的实体。
Main Menu - 可以将当前界面加入主菜单或者切换至主菜单配置
Inject - 帮助在控制器类中注入依赖，下面有详细介绍
Generate Handler - 可以订阅各种事件以及生成组件的代理，下面有详细介绍。

依赖注入

依赖注入是在界面控制器代码中获取对可视化组件和 API 端点(api endpoint)的引用的主要方式。当然，也可以编写所需类型的字段并手动进行注解。但是 Studio 提供了一个专用的窗口，这个窗口允许从列表中选择一个对象并自动创建合适的字段。窗口可以通过下列方式打开：

点击顶部操作面板的 Inject 操作，
按下 Alt+Insert（Cmd+N）键，在弹出的 Generate 菜单中选择 Inject…：

以下对象可以被注入到控制器中：

界面 XML 描述中定义的可视化组件和数据组件，
界面 API 接口，
基础设施接口，
中间层服务，
项目中定义的其他 Spring bean，
配置接口，
SLF4J Logger 实例。

事件处理器和代理方法

有两种方式可以在界面控制器添加界面生命周期相关的逻辑和组件行为方法：事件处理器以及组件代理。这两种方式在框架中实现不同，但在 Studio 中用法类似。

使用事件处理器，可以在界面生命周期的各个点执行代码并对用户操作做出响应。处理器是一个用 @Subscribe 注解的控制器方法，使用事件作为输入参数。

使用代理，可以提供代码替换界面中各种机制的标准实现。比如，您可以提供自己的函数用来提交数据或者为表格行选择图标。代理是一个特定签名的控制器方法，并且使用 @Install 注解。

可以在 Studio 中创建事件处理器和代理方法：

点击顶部操作面板的 Generate Handler。
或者按下 Alt+Insert（Cmd+N）键，在弹出的 Generate 菜单中选择 Generate Handler：

每个事件或代理在窗口右侧都提供了描述，这个描述是从事件的 Javadoc 中提取的。

打开的窗口中提供以下事件和代理方法：

表示界面生命周期的控制器事件。
可对按钮点击、表格选择、操作等做出响应的组件事件。
表示此界面的外部框架的生命周期事件处理器。
允许对数据上下文更改做出响应，并在数据提交前后执行代码的数据上下文事件。
允许接收有关数据容器和实体状态更改通知的数据容器事件。
可实现为界面组件自定义加载数据逻辑的数据加载器事件处理器。

5.4.4. 使用应用程序菜单

应用程序菜单配置保存在 web-menu.xml 配置文件中，该文件位于项目的 web 模块。如需修改主菜单配置，可以使用 CUBA 项目树的 Generic UI → Main Menu ：

菜单设计器允许可视化定义应用程序主菜单结构。Structure 选项卡显示图形设计器，可以在 Text 选项卡上编辑菜单的 XML 代码。

Tip	菜单设计器只有激活 CUBA Studio 订阅才能使用。

主菜单模式

菜单可以以两种模式创建：

在 Single mode 中，菜单仅包含当前项目的 web-menu.xml 文件中的菜单项。在这种情况下，需要创建所有菜单项，必要时还需要将应用程序组件中的菜单项也定义进来，这种方式有点麻烦，但好处是可以完全控制菜单结构。
在 Composite mode 中，菜单除了包含当前项目的 web-menu.xml 中的菜单项，还包含所有应用程序组件的菜单配置文件中的菜单项。这种模式可以很方便地包含所有继承的菜单项，可以在菜单结构的任何位置插入当前项目需要的菜单项。继承的菜单项不能被修改。

此外，在 Text 选项卡上，可以为菜单项定义 insertBefore 或 insertAfter 属性。这两个属性定义了当前菜单项的插入位置。在 Composite 模式下，这两个属性有助于将当前项目菜单项与继承的应用程序组件菜单项组合在一起。

例如，如果要将当前项目的菜单结构放在 Administration 菜单项的左侧，可以为当前项目的菜单树的根菜单项设置属性 insertBefore="administration"。

在可视化设计器中，可以在菜单树中拖拽菜单项改变它们在菜单结构中的位置。

菜单配置文件列表通过 cuba.menuConfig 应用程序属性定义，选择菜单模式时会更新此属性。当菜单模式从 Composite 切换至 Single 模式，Studio 建议您保留从平台和扩展插件继承的菜单项：

如果您决定保留继承的菜单项，这些菜单项的结构会复制到您的项目然后就可以自定义这些菜单了（比如，添加图标，修改菜单标题等）。

如果在后来某个时候，您决定将主菜单切换回 Composite 模式，注意，此时您需要手动从项目的菜单配置中移除哪些重复的菜单和菜单项。否则，菜单会没法显示，因为不允许有重复的菜单项。

添加菜单项

如需添加菜单项，选择菜单中已经存在的一项（或选择配置文件以添加顶级菜单）然后点击。会以模态窗形式打开菜单项编辑界面窗口。

新的菜单项创建之后，可以在菜单树中拖拽修改它在菜单结构中的位置。

可以创建以下类型的菜单项：

Screen - 界面

用于打开应用程序界面的菜单项。

Screen 菜单项可以设置下列属性：

Screen - 这个菜单项打开的界面的非唯一 ID。
Open type - 定义界面打开的方式，可以在新的选项卡打开，或者以模态窗的方式打开（NEW_TAB 或 DIALOG）。默认使用 NEW_TAB。

Menu - 菜单

包含其它菜单项（子菜单）的菜单项。

Spring bean

执行 Spring bean 方法的菜单项。Bean 需要存在于 web 模块。

Bean 菜单项可以设置下列属性：

Bean - 可以通过 AppBeans 获取到的 bean 的名称（例如 cuba_Messages）。
Bean method - 要调用的 bean 的方法名称。

Class - 类

指定给定类的一个方法的菜单项。

Class 菜单项可以设置下列属性：

Class - 类的全路径名称，此类需要实现下列接口之一：
- java.lang.Runnable
- java.util.function.Consumer<Map<String, Object>>
- com.haulmont.cuba.gui.config.MenuItemRunnable

Separator - 分隔符

分隔菜单项的水平线

通用参数

下列参数对各种菜单项都适用：

Menu item - 父菜单或父菜单项，当前菜单放在这个菜单（项）内。
Id - 此菜单项的唯一 ID。该属性不是必须的，但是如果需要动态管理菜单配置则推荐设置。
Caption - 菜单显示的本地化名称。点击地球仪按钮可以打开 Localized Message 对话框，能输入所有支持语言的本地化消息。
Shortcut - 触发该菜单项的快捷键。功能键（ALT，CTRL，SHIFT）通过 "-" 分隔，比如，“ALT-C”。
Style name - 为菜单项设置样式名称。参阅 Themes 了解细节。

创建了菜单项之后，在设计器选中菜单项之后，右侧面板可以编辑下面的参数：

Icon - 菜单图标
Description - 鼠标浮于菜单时显示的 tooltip 提示。点击地球仪按钮可以打开 Localized Message 对话框，能输入所有支持语言的本地化消息。
Params - 界面参数，传递给被打开界面控制器的 init() 方法。
Permissions - 可以限制对该菜单的访问。如果用户没有权限访问该菜单项，则不会显示在菜单中。有个更简单访问控制管理办法，就是使用角色的界面权限。

请继续阅读开发者手册的相关内容了解这些参数的更详细解释。

5.4.5. 使用主题

Studio 可以帮助在项目中创建主题扩展和自定义主题。

创建主题扩展或自定义主题时，会在 app-web 模块的 themes 子目录创建特殊的主题目录结构并在 build.gradle 文件添加新的 Gradle 任务支持主题构建。

创建的主题会显示在项目树的 Themes 部分中。

扩展或创建主题后，可以在 SCSS 文件或可视化编辑器中手动修改其变量： * 在新主题的右键菜单中，选择 Open Variables File。 * 通过 CUBA 主菜单：选择 CUBA → Advanced → Manage themes → Edit %ThemeName% Theme Variables。

Tip	主题变量的可视化编辑器只有激活 CUBA Studio 订阅之后才能使用。

5.5. Frontend UI

Studio 可以生成 Frontend UI 模块和组件。使用 @cuba-platform/front-generator npm 包生成代码。

5.5.1. 创建 Frontend UI 模块

在 CUBA 项目树右键点击 Project > Modules 然后选择 Manage modules > Create 'front' module。

Studio 会在 modules/front/generation 目录开始安装 Frontend Generator ，这里需要花费一点时间。然后您会看到一个预选项界面。根据您将要使用的框架选择合适的预选项。也可以展开 Advanced 部分选择使用特定版本的 Frontend Generator 。

Warning

Polymer 预选项已经废弃。

生成的 Frontend UI 应用程序（前端客户端）会在 modules/front 文件夹。

如需删除 front 模块，右键点击 Project > Modules 并选择 Manage modules > Remove 'front' module。

5.5.2. 基于 React 的 Frontend UI 组件

如果您使用 React 模板创建了 front 模块，则可以添加 React 组件。在 CUBA 项目树展开 Data Model，右键点击一个实体，选择 New > Frontend Component。

有下列选项：

Blank component - 空组件
Entity cards - 实体卡片 - 展示实体列表的组件
Entity management - 实体管理 - 展示并且可编辑实体的组件

5.5.2.1. 空组件

我们有一个空的 React 基于类的组件。如果您需要一个“干净状态”的组件用来做自定义，则可以使用空组件。

点击 Next 之后，会显示下面的选项界面。

Directory - 组件生成的目录。
Add to menu - 为生成的组件设置导航菜单。
Component class name - 组件类名。

5.5.2.2. 实体卡片

以卡片的形式展示实体的只读列表。

点击 Next 之后，会显示下面的选项界面。

Directory - 组件生成的目录。
Add to menu - 为生成的组件设置导航菜单。
Entity - 显示在该组件的实体。
Component class name - 组件类名。
Entity view - 该组件使用的视图。

5.5.2.3. 实体管理

指定实体的 CRUD（列表+编辑）界面。如需浏览、添加、删除、编辑实体，则使用该组件。选择该选项可以生成 3 个组件：

Edit component - 用户可以编辑实体实例
List component - 用户可以查看实体列表，并可以为选中的实体打开 Edit component。
CRUD component - 根据路由是否带有 entityId 参数决定渲染成 List component 或 Edit component。

点击 Next 之后，会显示下面的选项界面。

Directory - 组件生成的目录。
Add to menu - 为生成的组件设置导航菜单。
Entity - 该组件的实体。
CRUD component class name - CRUD component 类名
List type - list component 可以用下面的类型（我们称之为列表类型）：
- list
- cards
- table
List component class - List component 类名。
List view - List component 用到的视图。
Edit component class name - Edit component 类名。
Edit view - Edit component 用到的视图。

5.6. REST API

REST API 是一个 CUBA 扩展插件，为应用程序提供 CRUD 操作、执行预定义的 JPQL 查询、执行服务方法以及其他通过 REST web 服务能实现的功能。REST API 也是 frontend UI 与服务器通信的标准方式。参阅官方文档了解更多关于该扩展插件的内容。

需要在项目中使用 REST API，可以通过 Studio 的 CUBA Add-Ons 窗口进行安装。

Studio 对 REST API 功能提供如下支持：

自动生成所需的应用程序属性。
在 CUBA 项目树创建并展示配置文件。
帮助注册需要开放为 REST API 的服务方法。

客户端凭证

当 Studio 为项目添加 REST API 之后，会自动生成唯一的 cuba.rest.client.id 和 cuba.rest.client.secret 应用程序属性，并写入 web-app.properties 文件。REST API 客户端使用这些凭证与服务器做验证。推荐在生产环境修改这两个属性的值。

项目树部分

一旦为项目添加了 REST API 扩展插件，CUBA 项目树便能展示 REST API 部分：

这部分会显示下列配置文件：

rest-queries.xml - 包含预定义的 JPQL 查询。
rest-services.xml - 包含对外开放的服务方法列表，可以通过 REST API 调用。

如果没有看到上面提到的文件，可以手动创建：右键点击 REST API 部分，然后通过 Create REST Queries Configuration 和 Create REST Services Configuration 菜单创建：

创建的配置文件会自动在 web-app.properties 文件注册。之后可以手动修改这两个文件内容。

开放中间件服务方法

如需通过 REST API 调用中间件服务方法，需要在 rest-services.xml 配置文件注册这些服务方法。

使用 Studio 提供的快捷操作可以快速将需要的服务方法添加至注册文件：

打开服务接口类，并将光标移至需要添加的方法处。
按下 Alt+Enter （Option+Enter）列出可用的快捷操作。
选择 Register rest method 操作即可。
选中的方法签名会添加到 rest-services.xml 中，从服务接口快速跳转至 XML，可以点击侧边栏的箭头标记：

5.7. 安全

从版本 7.2.0 开始，除了在运行时创建角色和分组之外，CUBA 中可以定义设计时角色和访问组。目前 Studio 能支持设计时角色定义。

Studio 在 CUBA 项目树的 Security 部分显示用于定义设计时角色的类：

5.7.1. 创建角色定义

右键点击 Security 部分，选择 New → Role 菜单项即可创建新的设计时角色。点击后弹出 New Role 对话框：

Role Name - 角色名称。这是一个代码级别的名称，可以用在代码中。
Class - 定义角色的类名。填写了角色名称后会自动填写该字段。
Security Scope - 选择客户端角色权限的类型：
- GENERIC_UI - 通用用户界面权限。
- REST - REST API 客户端权限。

点击 OK 创建角色定义类。接下来，您可以按照开发者手册的相应章节介绍的规则，在源代码中添加角色权限。激活 CUBA Studio 订阅的用户可以使用可视化设计器设计角色权限。

5.7.2. 使用角色设计器

设计时角色定义的代码编辑器还集成了可视化的 Role Designer - 角色设计器。角色设计器支持可视化的配置角色和必要的角色权限。可以直接编辑代码，也可以用角色设计器生成代码。

角色设计器 是以标签页的形势展示，在代码编辑器底部有切换控制。标签页如下：

Text - 展示并可以编辑 Java/Kotlin 源代码。
Definition - 定义基本的角色属性。
Screens - 定义菜单项和界面权限。
Entities - 定义实体和实体属性的 CRUD 权限。
Specific - 定义角色的特殊权限以及修改项目的特殊权限配置。

Tip	角色设计器只有激活 CUBA Studio 订阅才能使用。

5.7.2.1. Definition 标签页

Definition 标签页可以编辑角色基本属性。

Name - 角色的唯一名称。是代码级别名称，可以用在编码中。
Scope - 客户端角色权限类型：
- GENERIC_UI - 通用用户界面权限。
- REST - REST API 客户端权限。
Default Role - 是否默认角色，默认角色会在创建新用户时自动为用户分配。用这个选项可以为新用户默认体用一组权限许可。
Super Role - 是否超级角色，有该角色的用户会是具有所有权限的超级用户。
Description - 角色描述。会显示在角色浏览界面和编辑界面。

Warning

注意，识别设计时角色是通过数据库角色名称进行识别的，因此，在为任何用户分配了设计时角色之后，就不要再修改角色名称了（否则需要手动更新数据库）。

5.7.2.2. Screens 标签页

角色设计器的 Screens 标签页可以编辑以下应用程序元素的权限：

主菜单项
其他界面（无法从主菜单直接访问的界面）
界面中的 UI 组件。

左侧的树结构展示主菜单项以及项目定义的界面和从平台或扩展插件继承的界面。树中的 Other Screens 分组展示项目中不能通过主菜单直接访问的界面。界面列表可以用顶部的搜索框对名称进行过滤。如果为界面定义了任何组件权限，则组件以子节点的形式展示在界面节点下。

默认拒绝所有菜单项和界面的访问。通过在左侧选择界面、右侧点击 Allow 即可为角色添加能打开对应菜单项或者界面的许可权限。

界面树的顶部有工具栏，包含以下操作：

Add Component Permission (+) - 为选中的界面创建组件权限。
Delete Component Permission (-) - 删除之前定义的组件权限。
Expand All, Collapse All - 收起或展开所有的树节点。
Settings → Show Assigned Only - 显示没有配置权限的所有界面和菜单项的开关。

组件权限

组件权限能用来隐藏界面中的特定 UI 组件或将其标记为只读，不论这些组件是否绑定实体。默认用户能使用所有组件。如需添加组件权限，选中组件所在的界面节点，然后点击 + (Add Component Permission) 按钮，会弹出 Create Component Permission 对话框：

Component - 组件 ID。该字段提供了自动完成功能，按下 Ctrl+Enter 查看所有选项。
Permission - 指定组件权限：
- Modify - 组件可查看、可编辑。
- Deny - 组件隐藏。
- View - 组件可见，但是不能编辑（比如一些表单字段）

点击 OK 完成设置后，组件以子节点的形式展示在界面节点下。

5.7.2.3. Entities 标签页

角色设计器的 Entities 标签页用来编辑实体和实体属性的权限。

面板左侧的表格展示项目中定义的实体以及从平台或者扩展插件中继承的实体。实体列表可以用表格上方的过滤器对名称进行过滤。

实体表格上方还有一个工具栏，包含如下操作：

Show Inherited from Platform and Add-Ons - 隐藏或显示继承实体的开关。
Show Assigned Only - 隐藏或显示所有实体、包括那些没有权限实体的开关。

默认所有的实体操作都是拒绝的。通过表格中的复选框可以为指定实体允许特定的操作（Create，Read，Update，Delete）。

右侧的表格展示所选实体的属性权限。默认拒绝查看和修改所有实体的属性。勾选 View 和 Modify 复选框可以为选中的属性配置需要的权限。

属性表格的通配符 wildcard 可以用来标记所有的属性都可以 View 和 Modify，包括实体将来可能增加的属性。注意，也可以在一个实体中这么组合：用通配符配置大部分属性都可以 Modify，但是勾选少数几个属性可以 View。

Warning

属性权限的通配符配置是很方便，但是需要小心使用。因为一旦使用，将来无法为该实体的新属性添加权限控制，比如新属性不希望当前角色查看或编辑。

实体表格中的 Allow All 选项允许实体的所有 CRUD 操作，并且也允许对实体属性的 Modify，因此，勾选此项则允许角色对该实体的完全访问。

5.7.2.4. Specific 标签页

角色设计器的 Specific 标签页提供下列功能：

为当前编辑的角色设置特殊权限。
编辑项目中特殊权限及其分类的配置。

特殊权限是定义在任意功能上的权限，不必关联至界面或实体 CRUD。特殊权限分类是将语义上相关的权限放在一组。参阅开发者手册中特殊权限， permissions.xml 了解更多细节。

面板左侧的树展示特殊权限及其分类，包含项目中定义的以及从平台和扩展插件继承的。鼠标选中树节点后，直接按键盘输入搜索文本可以在树中查找权限。

面板右侧包含下列配置：

Permission Id - 权限的唯一标识符。
Caption - 权限的本地化显示标题。可以为本项目的权限分类和权限设置。
Allow 和 Deny - 为当前角色赋予或收回权限。

所有特殊权限默认都是拒绝。

表格上方的工具栏提供下列操作：

New → Permission - 声明项目内的新特殊权限。
New → Category - 声明一个新的分类。
Delete - 删除选中的权限或分类。
Expand All, Collapse All - 展开或收起权限树。

定义新特殊权限

如需为项目定义新的特殊权限，首先需要创建一个分类。使用工具栏的 + → Category 操作添加。会弹出 Create Specific Category 对话框：

Id - 分类的唯一 ID。推荐为嵌套的分类使用组合标识符，比如，sales → sales.audit → sales.audit.bills。
Permissions Config - 定义分类的配置文件。
Parent Category - 父分类，如无父分类则留空。

点击 OK 之后，新的分类会添加到树中。选择新分类，用右边面板的 Caption 字段定义本地化标题。

如需创建新权限，使用工具栏的 + → Permission 操作添加。会弹出 Create Specific Permission 对话框：

Id - 权限的唯一标识符。代码中会用这个 ID 检查权限。

点击 OK 之后，权限会添加到树中。选择新权限，用右边面板的 Caption 字段定义本地化标题。

项目中定义的分类和权限会在 web-permissions.xml 注册。可以在树中右键点击然后选择 Jump to Source 跳转至源代码：

6. 与 IntelliJ IDEA 终极版集成

IntelliJ IDEA Ultimate Edition（终极版）是商业 IDE，包含了很多对开发 CUBA 应用程序有用的附加功能：支持 CSS、JavaScript、JPA、Spring、Docker、数据库访问等等。

在终极版中，CUBA Studio 也可以与普通插件一样进行安装。并且能集成一些终极版的功能提升开发体验。

6.1. 关闭有冲突的功能

有些 Studio 的功能会跟 Intellij 终极版或者第三方插件的功能冲突。

比如，为了避免 CUBA Studio 提供的侧边栏图标和 IDEA 终极版中 Spring 插件图标的冲突，可以按照下面的步骤：

在 IDEA 菜单中选择 Settings > Editor > General > Gutter Icons，
反选 Injection points 和 Producers for Disposer methods 选项，
应用更改。

6.2. 启用 JPA 支持

对 JPA (Java Persistence Annotation) 的支持通过 Java EE: EJB、JPA、Servlets 插件提供。

Warning

下面描述的功能不在标准的 CUBA Studio 或者 IntelliJ IDEA 社区版中提供。

JPA 支持提供以下功能，对于开发 CUBA 应用程序能提供帮助：

JPQL 语法高亮、自动补齐以及语法检查，
JPA 控制台（基于 CUBA 7.1+ 的项目），
实体源码中的代码检查，
实体关系图，
其他功能，参阅 JetBrains 网站.

如需使用这些功能，在项目中做以下配置：

为主数据存储配置数据源（Data Source）
为所有的项目模块添加 JPA 切面

Studio 支持快速配置以上几点。下面的介绍是针对 IDEA 2019.2 版本的。

6.2.1. 配置数据源

可以通过 IDE 右侧的 Database 工具窗手动设置数据源。Studio 在项目打开时提供了自动数据源检测：

如果不小心错过了这个消息提示，也可以通过 Event Log 工具窗口访问记录的消息，只需点击屏幕右下角的事件日志按钮即可打开。

点击 Configure 打开已经预填写的 Data Sources and Drivers 对话框。

数据源检测机制会根据主数据存储的设置自动发现配置参数，用来填写驱动和其他连接相关属性。但是也可以手动在 "Data Sources and Drivers" 窗口配置数据库驱动：

点击对话框底部的 Download missing driver files 连接，驱动文件会自动下载。
点击 Test Connection 测试自动发现的连接参数是否正确。如果需要可以修改参数。
将 Save 字段的值设置为 Forever。否则 IDE 重启之后会不记得密码。
点击 OK 按钮关闭对话框。

如果 JPA 切面已经创建，可以通过 Persistence 工具窗口为其分配新建的数据源。在每个切面上点击鼠标右键，选择 Assign Data Sources… → 修改数据源 → OK。

6.2.2. 配置 JPA 切面

项目中的每个模块都需要一个 JPA 切面，否则此模块不能使用 JPQL 语言相关的功能。

JPA 切面自动检测

Studio 能自动检测切面。当第一次打开新项目时，会在 IDE 的右下角提示 Frameworks Detected：

如果项目中已经配置 JPA 切面，则不会弹出此消息。如果想要看到此消息，可以通过主菜单 File → Project Structure 打开对话框移除已有的切面。然后重新打开项目，执行 Gradle 刷新操作（Gradle 工具窗 → Reimport All Gradle Projects 按钮）。

如果不小心错过了这个消息提示，也可以通过 Event Log 工具窗口访问记录的消息，只需点击屏幕右下角的事件日志按钮即可打开：

点击 Configure 链接，会出现 Setup Framework 对话框。

反选 Web 分组内的条目，然后点击 OK：

如需检查切面的配置，打开 IDE 左边的 Persistence 工具窗口。然后展开其中一个节点，比如，app-global 模块匹配的那个节点，然后展开 Entities 子节点。此时能看到项目中定义的实体或者从应用程序组件继承的实体：

JPA 切面手动配置

也可以通过 File → Project Structure 对话框手动配置 JPA 切面。

打开 Project Structure 对话框，
在左侧菜单选择 Facets，
移除所有已经存在的 JPA 切面，
对项目中的所有模块：global、core、gui、web、portal - 做下面的操作：
点击 "+"（添加）图标，
选择 JPA 切面类型，
选择以 “main” 结束的子模块，比如，"sample-sales.app-global.main"。点击 OK。
在对话框的右下角，修改 Default JPA Provider 为 CUBA EclipseLink。
对其他模块重复上述操作。

Tip	别忘了设置底部的 Default JPA Provider 字段为 CUBA EclipseLink，否则 JPA 控制台不会有效。

6.2.3. 功能示例

在配置了 JPA 切面的模块的 Java 和 XML 文件里，JPQL 语法高亮，自动补齐和自动检查：

实体关系图（ER 图）可以从 Persistence 工具窗口打开：右键点击任何模块，选择 Entities → ER Diagram。可以取消顶部 Superclasses 的选择，这样就不会显示通用的基类：

JPA 控制台

Tip	注意，JPA 控制台只有在 CUBA 7.1+ 项目才能使用。

JPA 控制台可以从 Persistence 工具窗口打开：展开任何模块 → 选择 Entities 然后点击 Console 按钮：

会打开控制台窗口。现在可以在开发数据库上执行任何 JPQL 查询操作了：