项目开发

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

创建新项目

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 的安装目录，例如，Windows 的 C:\Program Files\BellSoft\LibericaJDK-17 或者 macOS 的 /Library/Java/JavaVirtualMachines/liberica-jdk-17.jdk/Contents/Home。

  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

    当打开 组合项目 时，请确保打开的是聚合主项目 <project-name>-all 的 build.gradle 文件：

    open composite project

  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. 如果是升级到一个新的功能版本，例如，从 1.0.X 升至 1.1.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 项目之后，它会创建 Run/Debug 配置。可以使用主工具栏的按钮运行和停止你的应用程序。

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

run button

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

run link

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

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

Run/Debug 运行配置

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

在工具栏点击 Jmix Application 元素，然后在菜单中选择 Edit Configurations 打开配置窗口。

run conf

另外，也可以从主菜单打开：Run → Edit Configurations。

Run/Debug Configurations 对话框：

run dialog

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

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

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

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

  • 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 项目的配置。

问题排查

如果在项目开发中遇到一些莫名其妙的问题，可以尝试关闭再重新打开。如果还是不能解决问题，可以尝试清除缓存再重启 IDE：

  1. 从主菜单打开 File → Invalidate Caches。

  2. 勾选 Delete Jmix Studio templates and artifacts caches。

  3. 点击 Invalidate and Restart。

注意，再次打开项目时，会重新建立项目依赖的索引，会需要一些时间。