项目开发

本章节介绍如何创建新项目、打开已有项目以及如何启动应用程序。

创建新项目

Studio 的提供了一个向导可以用来从头创建 Jmix 新项目。

  1. 用主菜单 File → New → Project 打开 New Project 向导。或者可以在 IDE 的欢迎界面点击 New Project。

  2. 在弹窗中选择 Jmix Project。

    new project create

    这一步配置项目的主要设置：

    • 可以使用 Repository 字段提供的默认仓库，或者选择 Custom repository 配置自定义仓库。

    • 如需使用本地仓库的制件，可以勾选 Use local Maven repository。

    • 选择项目中需要使用的 Jmix version。如果没有特殊要求，用最新版即可。

      对于 beta 测试或者尝试 Jmix 的最新功能，你可能需要安装 Jmix 框架的不稳定版，这些版本以 BETA 或 SNAPSHOT 做后缀。勾选 Show unstable versions 复选框便可在 Jmix version 下拉框看到这些版本。

    • 在 Project JDK 字段，默认会选择与你环境变量 JAVA_HOME 一致的 JDK 版本。如果你看到 <No JDK>，那么需要在列表中点击 Add JDK 并选择 JDK 的安装目录。

  3. 下一步中，选择一个模板创建空项目。

    new project templates

  4. 然后可以设置项目名称、位置和语言环境。

    new project name

    • Project name 只能包含拉丁字母、数字和下划线。

    • Project location 是新建项目的文件夹路径。可以输入新路径或者点击字段旁边的按钮进行选择。

    • Base package 是 Java 类和字段的基础包名。请谨慎选择包名，因为一但选择，后续只能手动修改包名和移动类文件，目前 Studio 还不支持自动更换包名。

    • Project id 可选。如果设置了，Studio 会用这个 id 作为实体、表格、bean 名称的前缀。项目 id 不能超过 7 个字母。

    • 使用 Locales 字段打开语言设置编辑器，可以为项目增加更多的语言支持。后续如果需要，也可以再修改。

  5. 点击 Finish 按钮，会在指定的文件夹创建空项目，Studio 会自动使用 Gradle 文件构建项目并对项目建立索引。

    如果是第一次在 Jmix Studio 中编写项目，请 登录 Jmix 账号。

    当项目依赖同步完成，且索引也构建完成之后，可以在 Jmix 工具窗口 查看 Jmix 项目树。

现在可以使用新项目进行开发了。

打开已有项目

按照下列步骤打开已有项目：

  1. 在 IDE 的欢迎窗口点击 Open。

    new project welcome

    如果此时已经打开了其他项目，则可以通过主菜单 File → Open 打开。

  2. 在文件系统对话框中，选择包含 build.gradle 文件的项目根目录，然后点击 OK。

    new project build

    参阅 组合项目，了解如何在单一 IDE 项目中组织多个相关的 扩展组件 以及应用程序。

  3. 在随后的弹窗中，选择 Open as Project。

    new project open

    等待 Gradle 同步和项目索引完成。

    如果是第一次在 Jmix Studio 中编写项目，请 登录 Jmix 账号。

    然后会在 Jmix 工具窗口 展示 Jmix 项目树。 悠闲 如果项目是第一次打开，那么请从主菜单打开 File → Project Structure。

new project structure

  • 确保 Project SDK 字段的值与你的环境变量 JAVA_HOME 的值一致。如果你看到 <No JDK>，那么需要在列表中点击 Add JDK 并选择 JDK 的安装目录，例如，Windows 的 C:\Program Files\BellSoft\LibericaJDK-17 或者 macOS 的 /Library/Java/JavaVirtualMachines/liberica-jdk-17.jdk/Contents/Home。

  • 确保 Project language level 的值与对应的 JDK 版本一致。例如，如果 JDK 是 17，那么这个字段必须是 17 - Sealed types, always-strict floating-point semantics。

另外，如果项目已经打开过，还可以从最近项目打开。可以在 IDE 的欢迎窗口或者从主菜单的 File → Open Recent 打开最近项目。

升级项目

本章节介绍为项目升级至一个较新的 Jmix 版本的过程。

我们建议将你的项目通过版本控制软件进行管理，并在升级前提交所有的改动。这样可以看到升级过程中做了哪些修改，以便由于某些原因导致升级失败后能快速回滚至之前的版本。

  1. 按照 前一节 的描述打开项目。

  2. 在 Jmix 工具窗口，点击 Settings 按钮并选择 Project Properties。

    upgrade tool window

  3. 在 Jmix Project Properties 弹窗中，点击平台版本旁的 Change​ 超链接。

    upgrade properties

  4. 然后从下拉列表选择需要的 Jmix 版本。

    对于 beta 测试或者尝试 Jmix 的最新功能，你可能需要安装 Jmix 框架的不稳定版，这些版本以 SNAPSHOT、BETA 或 RC 做后缀。勾选 Show unstable versions 复选框便可在平台版本下拉框看到这些版本。

    upgrade unstable

    我们不推荐将 SNAPSHOT、BETA 或 RC 版本用于生产环境。

  5. 可以点击 Release Notes 链接切换至文档页面，在文档页面查看新版本增加的功能、改进和 API 的破坏性改动。

    upgrade release notes

  6. 如果是升级到一个新的功能版本，例如，从 2.3.X 升至 2.4.X，则会显示 Migration Required 部分内容。

    upgrade migration required

    点击 More info​ 链接，可以打开一个新的弹窗，展示 Studio 将要自动对项目做的修改内容。

    upgrade more info

  7. 点击 OK 确认升级平台版本，然后在 Project Properties 窗口点击 OK。Studio 会展示迁移窗口。

    upgrade migrate

  8. 点击 Migrate。Studio 会开始自动迁移并运行 Gradle 的 clean 任务。

  9. 如果是升级功能版本，可以在 Release Notes 中查看 Breaking Changes 部分，并对项目做相应的修改。

  10. 通过执行 Jmix Tool Window → Gradle → Assemble 组装你的项目。

    upgrade assemble

    如果编译出错，则需要根据错误信息进行修复。

启动应用程序

当 Studio 导入 Jmix 项目之后，会创建 Jmix Run/Debug 配置。可以使用主工具栏的按钮运行和停止你的应用程序。

如需运行应用程序并用调试器连接，只需要点击所选的 Jmix Application 配置旁边的调试按钮即可。

run button

运行状态在 Debug 工具窗口的 Console 标签展示。

run link

可以点击控制台输出的链接访问应用程序。

可以点击主工具栏的按钮或者 Debug 窗口的按钮停止应用程序服务。

Changelog 预览窗口

在运行应用程序之前，Studio 会检查项目数据模型和数据库表结构的差异。只要创建了新的实体，Studio 都会为所需的相应数据库改动创建 Liquibase changelog：

changelog preview window

每个 changelog 都由 Studio 生成唯一的文件名。可以在 File name 字段自定义文件名。

窗口的左侧可以预览将要创建的 changesets。点击其中任一的 changeset 都可以查看其内容。在预览界面的左上角还有一些可以修改 changelog 的操作：

changelog preview window actions

支持下列操作：

  • Remove from Changelog 提供下列选项：

    • Remove from Changelog：从当前的 changelog 中移除所选的改动。

    • Remove and Ignore：移除所选的改动并添加至 "Ignored" 列表中，将来不会再生成同样的改动。

  • Restore from Ignored：将 "Ignored" 列表中忽略的改动恢复到 changelog 中。

  • Show Other Actions：可以选择根据危险等级选择改动，以及展开或收起所有改动。

如需保存并启动应用程序，点击 Save and run 按钮。

如果不需要保存 changelog，而仅希望启动应用程序，点击 Discard and run 按钮。

Run/Debug 运行配置

Jmix Run/Debug 配置会在打开 Jmix 项目时自动创建。这个配置简化了直接从 IDE 运行或调试 Jmix 应用程序的过程。另外，在 Jmix 工具窗口右键点击 Jmix 项目并选择 Start Application 时也会自动创建 Jmix Run/Debug 配置。

从 IDE 编辑 “Jmix Application” 的 Run/Debug 配置可以调整应用程序运行的设置。

如需访问配置对话框并修改 Run/Debug 配置，可以在工具栏点击 Jmix 应用程序元素，然后在菜单中选择 Edit Configurations。

run conf

另外，也可以从 IDE 的主菜单 Run → Edit Configurations，然后从列表中选择 Jmix application。

Run/Debug Configurations 对话框：

run dialog

下列这些设置可能是需要修改的：

  • Before launch - 在启动应用程序之前需要执行的任务。Jmix 项目自动配置了下列启动前任务：

    • Clean Hot Deploy Conf Directory - 清理以前运行遗留的热部署文件。

    • Check Liquibase Changelog Includes - 检查根 changelog 文件中的 includes 部分，是否与包含的扩展组件匹配。如果不匹配，则 Studio 会显示通知对话框，提示添加或删除 includes。

    • Check Jmix Database - 检查数据模型和数据库结构的不同，并生成 数据库更改 脚本。如果你不需要每次启动应用程序都检查并生成 Liquibase 脚本，可以删除这个任务（这个任务的功能可以通过 数据存储 的右键菜单手动执行）。

    • Assemble - 创建项目的可发布输出制件，会打包代码和资源文件。

  • Environment variables - Gradle 进程和应用程序需要使用的环境变量。

  • VM options - 传递给 Gradle 进程的 JVM 选项。

    注意，这里的 VM 参数不会直接影响运行的应用程序。如需将参数传递给应用程序的 JVM，需要在 build.gradle 按如下配置 bootRun 任务：

    bootRun {
    if (System.getProperty('jvmArgs')) {
        jvmArgs = (System.getProperty('jvmArgs').split("\\s+") as List)
    }
}

    然后可以在 VM options 字段设置 JVM 选项，示例：

    -DjvmArgs="-Duser.timezone=Europe/London -Dsome.property=somevalue"

使用非默认 JDK

IntelliJ IDEA 和 Gradle 默认都使用 JAVA_HOME 环境变量定义的 JDK 组装和运行 Java 项目。

如需在项目中使用非默认 JDK 而不影响系统的全局设置，请按照下面步骤：

  1. 从主菜单打开 File → Project Structure。

  2. 在 Project → SDK 选择需要的 JDK 版本。

  3. 切换至项目根目录，创建 gradle.properties 文件，包含如下内容：

    # JDK 安装目录
org.gradle.java.home = /Library/Java/JavaVirtualMachines/liberica-jdk-17.jdk/Contents/Home

  4. 在 Gradle 工具窗口（一般在 IDE 右侧边），点击 Reload All Gradle Projects 刷新 Gradle 项目的配置。