使用 Apache Maven 开发并编译 Quarkus 应用程序

流程

1. 在命令终端中，输入以下命令验证 Maven 是否使用 OpenJDK 11 或 17，以及 Maven 版本是否为 3.8.x，其中 x 是 6 或更高版本：

   mvn --version

2. 如果前面的命令没有返回 OpenJDK 11 或 17，请将到 OpenJDK 11 或 17 的路径添加到 PATH 环境变量中，然后再次输入前面的命令。

3. 要使用 Quarkus Maven 插件创建项目，请使用以下方法之一：

   • 输入以下命令：

     mvn com.redhat.quarkus.platform:quarkus-maven-plugin:2.13.9.SP2-redhat-00003:create \
         -DprojectGroupId=<project_group_id> \
         -DprojectArtifactId=<project_artifact_id> \
         -DplatformGroupId=com.redhat.quarkus.platform \
         -DplatformArtifactId=quarkus-bom \
         -DplatformVersion=2.13.9.SP2-redhat-00003

     在这个命令中，替换以下值：

     • <project_group_id > : 项目的唯一标识符
     • <project_artifact_id > : 项目名称和项目目录的名称

   • 以互动模式创建项目：

     mvn com.redhat.quarkus.platform:quarkus-maven-plugin:2.13.9.SP2-redhat-00003:create

     出现提示时，输入所需的属性值。

     注意

     您还可以输入以下命令使用项目属性的默认值创建项目：

     mvn com.redhat.quarkus.platform:quarkus-maven-plugin:2.13.9.SP2-redhat-00003:create -B

   • 使用 Quarkus CLI 创建项目：

     quarkus create app my-groupId:my-artifactId

     • 您还可以通过以下方式获取可用选项列表：

       quarkus create app --help

流程

1. 在文本编辑器中打开 pom.xml 文件。

2. 添加包含以下项目的配置属性：

   • Quarkus Maven 插件版本
   • Quarkus BOM groupID,artifactID, 和 version
   • Maven Surefire 插件版本

   <properties>
       <quarkus.platform.version>2.13.9.SP2-redhat-00003</quarkus.platform.version>
       <quarkus.platform.artifact-id>quarkus-bom</quarkus.platform.artifact-id>
       <quarkus.platform.group-id>com.redhat.quarkus.platform</quarkus.platform.group-id>
       <surefire-plugin.version>3.0.0-M5</surefire-plugin.version>
   </properties>

3. 添加 Quarkus GAV （组、工件、版本），并使用 quarkus-bom 文件省略不同 Quarkus 依赖项的版本：

   <dependencyManagement>
       <dependencies>
         <dependency>
           <groupId>${quarkus.platform.group-id}</groupId>
           <artifactId>${quarkus.platform.artifact-id}</artifactId>
           <version>${quarkus.platform.version}</version>
           <type>pom</type>
           <scope>import</scope>
         </dependency>
       </dependencies>
     </dependencyManagement>

4. 添加 Quarkus Maven 插件：

   <build>
       <plugins>
           <plugin>
               <groupId>${quarkus.platform.group-id}</groupId>
               <artifactId>quarkus-maven-plugin</artifactId>
               <version>${quarkus.platform.version}</version>
               <executions>
                   <execution>
                       <goals>
                           <goal>build</goal>
                       </goals>
                   </execution>
               </executions>
           </plugin>
           <plugin>
               <artifactId>maven-surefire-plugin</artifactId>
               <version>${surefire-plugin.version}</version>
               <configuration>
                   <systemPropertyVariables>
                       <java.util.logging.manager>org.jboss.logmanager.LogManager</java.util.logging.manager>
                       <maven.home>${maven.home}</maven.home>
                   </systemPropertyVariables>
               </configuration>
           </plugin>
       </plugins>
   </build>

   注意

   maven-surefire-plugin 运行应用程序的单元测试。

5. 可选： 要构建原生应用程序，请添加包括 Maven Failsafe 插件 的特定原生配置集：

   <profiles>
       <profile>
           <id>native</id>
           <properties>
               <quarkus.package.type>native</quarkus.package.type>
           </properties>
           <build>
               <plugins>
                   <plugin>
                       <groupId>org.apache.maven.plugins</groupId>
                       <artifactId>maven-failsafe-plugin</artifactId>
                       <version>${surefire-plugin.version}</version>
                       <executions>
                           <execution>
                               <goals>
                                   <goal>integration-test</goal>
                                   <goal>verify</goal>
                               </goals>
                               <configuration>
                                   <systemProperties>
                                       <native.image.path>${project.build.directory}/${project.build.finalName}-runner</native.image.path>
                                   </systemProperties>
                               </configuration>
                           </execution>
                       </executions>
                   </plugin>
               </plugins>
           </build>
       </profile>
   </profiles>

   • 在其名称中包含 IT 的测试，并包含 @NativeImageTest 注释，则针对原生可执行文件运行。
   • 有关原生模式与 JVM 模式的详情，请参阅 Quarkus "Getting Started" 指南中的 Difference between JVM 和 native mode。

流程

1. 在 Web 浏览器中，导航到 https://code.quarkus.redhat.com。

2. 指定项目的基本详情：

   
   1. 输入项目的组名称。name 格式遵循 Java 软件包命名规则，例如 org.acme。
   2. 输入您要用于从项目生成的 Maven 工件的名称，如 code-with-quarkus。

   3. 选择您要用来编译和启动应用程序的构建工具。您选择的构建工具决定了以下设置：

      • 生成的项目的目录结构
      • 您生成的项目中使用的配置文件格式

      • 在生成项目后，会显示用于编译和启动 code.quarkus.redhat.com 的自定义构建脚本和命令。

        注意

        红帽仅支持使用 code.quarkus.redhat.com 创建 Quarkus Maven 项目。

3. 指定应用程序项目的更多详情：

   1. 要显示包含更多应用程序详情的字段，请选择 More options。
   2. 输入您要用于从项目生成的工件的版本。此字段的默认值为 1.0.0-SNAPSHOT。建议使用 语义版本 ；但是，您可以选择指定不同类型的版本控制。

   3. 选择是否希望 code.quarkus.redhat.com 将初学者代码添加到项目中。当您添加标记为"CODE"到项目的扩展时，您可以在生成项目时自动为这些扩展创建示例类和资源文件。但是，如果您没有添加提供示例代码的任何扩展，这个选项不会影响生成的项目。

      
   注意

   code.quarkus.redhat.com 存储库自动使用最新版本的 Red Hat build of Quarkus。您可以在生成项目后手动更改 pom.xml 文件中的 BOM 版本。

4. 选择要使用的扩展。您选择的扩展作为 Quarkus 应用程序的依赖项包含在内。Quarkus 平台还确保这些扩展与将来的版本兼容。

   重要

   不要在同一项目中使用 RESTEasy 和 RESTEasy 主动扩展。

   扩展旁边的 quark 图标( )表示扩展是 Red Hat build of Quarkus 平台发行版本的一部分。红帽建议您使用同一平台中的扩展，因为它们被测试和验证在一起，因此更易于使用和升级。

   您可以启用选项，为标记为 STARTER-CODE 的扩展自动生成初学程序代码。

   

5. 要确认您的选择，请选择 Generate your application。此时会显示以下项目：

   • 下载包含您生成的项目的存档的链接
   • 可用于编译和启动应用程序的自定义命令
6. 要将带有生成的项目文件的存档保存到机器中，请选择 Download the ZIP。
7. 提取存档的内容。

8. 进入包含您提取的项目文件的目录：

   cd <directory_name>

9. 要以开发模式编译并启动应用程序，请使用以下方法之一：

   • 使用 Maven：

     ./mvnw quarkus:dev

   • 使用 Quarkus CLI：

     quarkus dev

流程

1. 进入您的 Quarkus 项目目录。

2. 使用以下方法之一列出所有可用扩展：

   • 使用 Maven：

     ./mvnw quarkus:list-extensions

   • 使用 Quarkus CLI：

     quarkus extension --installable

3. 使用以下方法之一为项目添加扩展：

   • 使用 Maven，输入以下命令，其中 <extension> 是您要添加的扩展的组、工件、版本(GAV)：

     ./mvnw quarkus:add-extension -Dextensions="<extension>"

     例如，要添加 Agroal 扩展，请输入以下命令：

     ./mvnw quarkus:add-extension -Dextensions="io.quarkus:quarkus-agroal"

   • 使用 Quarkus CLI，输入以下命令，其中 <extension> 是您要添加的扩展的组、工件、版本(GAV)：

     quarkus extension add "<extension>"

4. 要搜索特定扩展，请在 -Dextensions= 之后输入扩展名称或部分名称。以下示例搜索名称中包含文本 jdbc、agroal 和 non- existent 的扩展：

   ./mvnw quarkus:add-extension -Dextensions=jdbc,agroal,non-exist-ent

   这个命令返回以下结果：

   ❌ Multiple extensions matching 'jdbc'
       * io.quarkus:quarkus-jdbc-h2
       * io.quarkus:quarkus-jdbc-mariadb
       * io.quarkus:quarkus-jdbc-postgresql
       Be more specific, for example, by using the exact name or the full GAV.
   ✅ Adding extension io.quarkus:quarkus-agroal
   ❌ Cannot find a dependency matching 'non-exist-ent', maybe a typo?
   [...]

CodeReady Studio 或 Eclipse

1. 在 CodeReady Studio 或 Eclipse 中，点 File>*Import*。
2. 选择 Maven → Existing Maven Project。
3. 接下来，选择项目的 root 位置。此时会出现可用模块的列表。
4. 选择生成的项目，然后单击 Finish。

5. 要编译并启动应用程序，请使用以下方法之一：

   • 使用 Maven：

     ./mvnw quarkus:dev

   • 使用 Quarkus CLI：

     quarkus dev

IntelliJ

1. 在 IntelliJ 中，完成以下任务之一：

   • 选择 File > New &gt ; Project from Existing Sources。
   • 在 Welcome 页面上，选择 Import project。
2. 选择项目根目录。
3. 选择 Import project from external model，然后选择 Maven。
4. 检查选项，然后单击 Next。
5. 点 Finish。

6. 要编译并启动应用程序，请使用以下方法之一：

   • 使用 Maven：

     ./mvnw quarkus:dev

   • 使用 Quarkus CLI：

     quarkus dev

Apache NetBeans

1. 选择 File > Open Project。
2. 选择 项目根目录。
3. 单击 Open Project。

4. 要编译并启动应用程序，请使用以下方法之一：

   • 使用 Maven：

     ./mvnw quarkus:dev

   • 使用 Quarkus CLI：

     quarkus dev

Visual Studio Code

1. 安装 Java 扩展包.
2. 在 Visual Studio Code 中，打开您的项目目录。

流程

1. 进入 {project}/src/main/resources 文件夹，并在文本编辑器中打开 application.properties 文件。

2. 编辑您要更改的属性值并保存文件。

   下表列出了您可以更改的属性：

   Expand

   属性	描述	类型	default
   quarkus.package.main-class	应用程序的入口点。在大多数情况下，您必须更改这个值。	string	io.quarkus.runner.GeneratedMain
   quarkus.package.type	软件包请求的输出类型，您可以将其设置为 'jar'（使用 'fast-jar'）、'legacy-jar' 作为 pre-1.12 default jar 打包、'uber-jar'、'native' 或 'native-sources'。	string	jar
   quarkus.package.manifest.add-implementation-entries	确定实施信息是否必须包含在运行程序 JAR 文件的 MANIFEST.MF 文件中。	布尔值	true
   quarkus.package.user-configured-ignored-entries	不得复制到输出工件中的文件。	字符串（列表）
   quarkus.package.runner-suffix	应用到运行程序 JAR 文件的后缀。	string	-runner
   quarkus.package.output-directory	应用构建的输出文件夹。这相对于构建系统目标目录解析。	string
   quarkus.package.output-name	最终工件的名称。	string

   Show more

1. 运行以下命令来测试应用程序：

流程

1. 打开 pom.xml 文件，并验证 native 配置集是否具有以下元素：

   <plugin>
       <groupId>org.apache.maven.plugins</groupId>
       <artifactId>maven-failsafe-plugin</artifactId>
       <version>${surefire-plugin.version}</version>
       <executions>
           <execution>
               <goals>
                   <goal>integration-test</goal>
                   <goal>verify</goal>
               </goals>
               <configuration>
                   <systemPropertyVariables>
                       <native.image.path>${project.build.directory}/${project.build.finalName}-runner</native.image.path>
                       <java.util.logging.manager>org.jboss.logmanager.LogManager</java.util.logging.manager>
                       <maven.home>${maven.home}</maven.home>
                   </systemPropertyVariables>
               </configuration>
           </execution>
       </executions>
   </plugin>

   Maven Failsafe 插件(maven-failsafe-plugin)运行集成测试，并指示生成的原生可执行文件的位置。

2. 打开 src/test/java/org/acme/quickstart/NativeGreetingResourceIT.java 文件，并验证它是否包含以下内容：

   package org.acme.getting.started;
   
   import io.quarkus.test.junit.QuarkusIntegrationTest;
   
   @QuarkusIntegrationTest 

   1

   
   public class GreetingResourceIT extends GreetingResourceTest { 

   2

   
   
       // Execute the same tests but in native mode.
   }

   1

   在测试之前，使用另一个测试运行程序从原生文件启动应用。可执行文件通过使用 Maven Failsafe 插件中配置的 native.image.path 系统属性来检索。

   2

   本例扩展了 GreetingResourceTest，但您也可以创建新的测试。

3. 运行测试：

   ./mvnw verify -Pnative

   以下示例显示了这个命令的输出：

   ./mvnw verify -Pnative
   ...
   [getting-started-1.0-SNAPSHOT-runner:18820]     universe:     587.26 ms
   [getting-started-1.0-SNAPSHOT-runner:18820]      (parse):   2,247.59 ms
   [getting-started-1.0-SNAPSHOT-runner:18820]     (inline):   1,985.70 ms
   [getting-started-1.0-SNAPSHOT-runner:18820]    (compile):  14,922.77 ms
   [getting-started-1.0-SNAPSHOT-runner:18820]      compile:  20,361.28 ms
   [getting-started-1.0-SNAPSHOT-runner:18820]        image:   2,228.30 ms
   [getting-started-1.0-SNAPSHOT-runner:18820]        write:     364.35 ms
   [getting-started-1.0-SNAPSHOT-runner:18820]      [total]:  52,777.76 ms
   [INFO]
   [INFO] --- maven-failsafe-plugin:2.22.1:integration-test (default) @ getting-started ---
   [INFO]
   [INFO] -------------------------------------------------------
   [INFO]  T E S T S
   [INFO] -------------------------------------------------------
   [INFO] Running org.acme.quickstart.NativeGreetingResourceIT
   Executing [/data/home/gsmet/git/quarkus-quickstarts/getting-started/target/getting-started-1.0-SNAPSHOT-runner, -Dquarkus.http.port=8081, -Dtest.url=http://localhost:8081, -Dquarkus.log.file.path=build/quarkus.log]
   2019-04-15 11:33:20,348 INFO  [io.quarkus] (main) Quarkus 999-SNAPSHOT started in 0.002s. Listening on: http://[::]:8081
   2019-04-15 11:33:20,348 INFO  [io.quarkus] (main) Installed features: [cdi, resteasy]
   [INFO] Tests run: 2, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 1.387 s - in org.acme.quickstart.NativeGreetingResourceIT
   ...

   注意

   Quarkus 等待 60 秒，使原生镜像在自动失败原生测试前启动。您可以通过配置 quarkus.test.wait-time 系统属性来更改此持续时间。

   您可以使用以下命令扩展等待时间，其中 < duration&gt; 是等待时间（以秒为单位）：

   ./mvnw verify -Pnative -Dquarkus.test.wait-time=<duration>

流程

1. 切换到包含 Quarkus 应用 pom.xml 文件的目录。

2. 要以开发模式编译并启动 Quarkus 应用程序，请使用以下方法之一：

   • 使用 Maven：

     ./mvnw quarkus:dev

   • 使用 Quarkus CLI：

     quarkus dev

3. 更改您的应用程序并保存文件。

4. 刷新浏览器，以触发工作区扫描。

   如果检测到任何更改，则会重新编译 Java 文件，并重新部署应用程序。然后，重新部署的应用程序会为您的请求提供服务。如果编译或部署存在问题，则会出现错误页面。

   在开发模式中，调试器已被激活，并侦听端口 5005。

5. 可选： 要在运行应用前等待调试器附加，请包括 -Dsuspend ：

   ./mvnw quarkus:dev -Dsuspend

6. 可选： 要防止调试器运行，请包含 -Ddebug=false ：

   ./mvnw quarkus:dev -Ddebug=false

通过配置系统属性来控制调试器

1. 更改 debug 系统属性之一，其中 PORT 是调试器侦听的端口：

   • 错误 ：JVM 在禁用调试模式时启动。
   • true ：JVM 以调试模式启动，并侦听端口 5005。
   • 客户端 ：JVM 在客户端模式中启动，并尝试连接到 localhost:5005。
   • PORT: JVM 以调试模式启动并侦听 PORT。

2. 要在以 debug 模式运行时挂起 JVM，请将 suspend 系统属性的值设置为以下值之一：

   • y 或 true ：调试模式 JVM 启动挂起。
   • n 或 false ：调试模式 JVM 启动而不暂停。