使用 Apache Maven 开发并编译红帽构建的 Quarkus 应用程序

流程

1. 在命令终端中，输入以下命令验证 Maven 是否使用 OpenJDK 17 或 21，并且 Maven 版本是否为 3.9.9 ：

   mvn --version

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

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

   • 使用 Quarkus Maven 插件。输入以下命令：

     mvn com.redhat.quarkus.platform:quarkus-maven-plugin:3.20.0.redhat-00002:create \
         -DprojectGroupId=<project_group_id> \
         -DprojectArtifactId=<project_artifact_id> \
         -DplatformGroupId=com.redhat.quarkus.platform \
         -DplatformArtifactId=quarkus-bom \
         -DplatformVersion=3.20.0.redhat-00002
         -DpackageName=getting.started

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

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

   • 以互动模式创建项目：

     mvn com.redhat.quarkus.platform:quarkus-maven-plugin:3.20.0.redhat-00002:create

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

     注意

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

     mvn com.redhat.quarkus.platform:quarkus-maven-plugin:3.20.0.redhat-00002:create -B

   • 使用 Quarkus CLI。输入以下命令：

     quarkus create app my-groupId:my-artifactId --package-name=getting.started

     • 您还可以使用以下命令获取可用选项列表：

       quarkus create app --help

流程

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

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

   • Maven Compiler 插件版本
   • Quarkus BOM groupID,artifactID, 和 version
   • Maven Surefire 插件版本
   • skipITs 属性

   <properties>
       <compiler-plugin.version>3.11.0</compiler-plugin.version>
       <quarkus.platform.group-id>com.redhat.quarkus.platform</quarkus.platform.group-id>
       <quarkus.platform.artifact-id>quarkus-bom</quarkus.platform.artifact-id>
       <quarkus.platform.version>3.20.0.redhat-00002</quarkus.platform.version>
       <surefire-plugin.version>3.1.2</surefire-plugin.version>
       <skipITs>true</skipITs>
   </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 插件、Maven Compiler 插件和 Maven Surefire 插件：

   <build>
       <plugins>
           <plugin>
               <groupId>${quarkus.platform.group-id}</groupId>
               <artifactId>quarkus-maven-plugin</artifactId>
               <version>${quarkus.platform.version}</version>
               <extensions>true</extensions>
               <executions>
                   <execution>
                       <goals>
                           <goal>build</goal>
                           <goal>generate-code</goal>
                           <goal>generate-code-tests</goal>
                       </goals>
                   </execution>
               </executions>
           </plugin>
           <plugin>
               <artifactId>maven-compiler-plugin</artifactId>
               <version>${compiler-plugin.version}</version>
               <configuration>
                   <compilerArgs>
                       <arg>-parameters</arg>
                   </compilerArgs>
               </configuration>
           </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-plugin 的特定原生配置集：

   <build>
       <plugins>
           ...
           <plugin>
               <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>
       </plugins>
   </build>
   ...
   <profiles>
       <profile>
           <id>native</id>
           <activation>
               <property>
                   <name>native</name>
               </property>
           </activation>
           <properties>
               <skipITs>false</skipITs>
               <quarkus.native.enabled>true</quarkus.native.enabled>
           </properties>
       </profile>
   </profiles>

   • 将 IT 包含在其名称中并包含 @QuarkusIntegrationTest 注释的测试将针对原生可执行文件运行。
   • 有关原生模式与 Java 虚拟机(JVM)模式不同的详细信息，请参阅"使用红帽构建的 Quarkus"指南中的 JVM 和原生构建模式。

流程

1. 在您的 Web 浏览器中，前往 https://code.quarkus.redhat.com。

2. 从可用版本列表中，code.quarkus.redhat.com 应用程序默认选择红帽构建的 Quarkus 的最新版本。

   注意

   code.quarkus.redhat.com 应用程序使用最新版本的红帽构建的 Quarkus，这是首选的选项。但是，在生成项目后，您可以根据需要手动更改为 pom.xml 文件中的更早的 BOM 版本，但不建议这样做。

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

   
   1. 输入项目的组名称。名称格式遵循 Java 软件包命名约定；例如，org.acme。
   2. 输入项目生成的 Maven 工件的名称，如 code-with-quarkus。

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

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

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

        注意

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

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

   1. 要显示包含更多应用程序详情的字段，请选择 More options。

      
   2. 输入您要用于项目生成的工件的版本。此字段的默认值为 1.0.0-SNAPSHOT。首选使用 语义版本，但您可以选择指定不同类型的版本。
   3. 选择是否希望 code.quarkus.redhat.com 将入门代码添加到项目中。将标记为"STARTER-CODE"的扩展添加到项目中时，您可以启用此选项，以便在生成项目时自动为这些扩展创建示例类和资源文件。但是，如果您没有添加提供示例代码的任何扩展，这个选项不会影响生成的项目。
   注意

   code.quarkus.redhat.com 应用程序自动使用最新版本的红帽构建的 Quarkus。但是，如果您需要，可以在生成项目后手动更改为 pom.xml 文件中的较早 BOM 版本，但不建议这样做。

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

   重要

   不要在同一项目中使用 quarkus-rest 和 quarkus-resteasy 扩展。两者都提供相似的功能，但它们的运作方式有所不同。使用 quarkus-rest 是首选的。

   扩展旁边的 quark 图标( )表示扩展是红帽构建的 Quarkus 平台版本的一部分。红帽更喜欢使用来自同一平台的扩展，因为它们经过测试和验证，因此更易于使用和升级。

   对于使用"STARTER-CODE"标记的扩展，您可以启用 选项自动生成初学者代码。

   

6. 要确认您的选择，请选择 Generate your application。出现的对话框显示以下项目：

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

验证

1. 以 dev 模式编译和启动应用程序。如需更多信息，请参阅 编译和启动 Red Hat build of Quarkus Getting Started 项目。
2. 从 Quarkus CLI 软件包并运行 Getting Started 项目。如需更多信息，请参阅打包并运行红帽构建的 Quarkus 入门应用程序。

流程

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. 要搜索特定扩展，请输入扩展名称或部分名称 after -Dextensions=。以下示例搜索在名称中包含文本的扩展：

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

   这个命令返回以下结果：

   [SUCCESS] ✅  Extension io.quarkus:quarkus-agroal has been installed

   同样，使用 Quarkus CLI，您可以输入：

   quarkus extension add 'agroal'

CodeReady Studio or Eclipse

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

5. 使用以下方法之一编译和启动应用程序：

   • 使用 Maven：

     ./mvnw quarkus:dev

   • 使用 Quarkus CLI：

     quarkus dev

IntelliJ

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

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

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. 添加您要更改的属性并保存文件。

   表 1.1. 您可以更改的属性

   属性	描述	类型	default
   quarkus.native.enabled	启用原生镜像生成。当设置为 true 时，应用程序将编译到原生可执行文件中。	布尔值	false
   quarkus.native.sources-only	仅生成原生镜像源，而不构建最终的原生可执行文件。	布尔值	false
   quarkus.package.main-class	指定应用程序的入口点。在大多数情况下，您必须更改这个值。	string	io.quarkus.runner.GeneratedMain
   quarkus.package.jar.enabled	决定是否构建 JAR 文件。设置为 false 以禁用 JAR 创建。	布尔值	true
   quarkus.package.jar.type	定义要构建的 JAR 类型。支持的值有 fast-jar （默认）、uber-jar、mutable-jar 和 legacy-jar （已弃用）。要完全禁用 JAR 生成，请设置 quarkus.package.jar.enabled=false。	string	fast-jar
   quarkus.package.type （已弃用）	已弃用。* 使用 quarkus.package.jar.type 来配置 JAR 类型。* 对于原生构建，将 quarkus.native.enabled 设置为 true。* 对于原生源构建，也将 quarkus.native.sources-only 设置为 true。* JAR 构建可以通过将 quarkus.package.jar.enabled 设置为 false 来禁用。	string	JAR
   quarkus.package.jar.manifest.add-implementation-entries	确定运行程序 JAR 文件的 MANIFEST.MF 中是否包含实施信息。	布尔值	true
   quarkus.package.jar.user-configured-ignored-entries	指定不能复制到输出工件中的文件列表。	字符串（列表）	（无）
   quarkus.package.runner-suffix	指定应用到 runner JAR 文件的后缀。	string	-runner
   quarkus.package.output-directory	指定应用程序构建的输出文件夹。该路径相对于构建系统目标目录解析。	string	（无）
   quarkus.package.output-name	指定最终构建工件的名称。	string	（无）

1. 打开 src/main/resources/application.properties 文件。

2. 添加以下属性：

   quarkus.package.output-name=my-quarkus-custom-app-name

3. 构建应用程序：

   ./mvnw clean package

4. 验证生成的应用程序 JAR 文件是否命名为：

   my-quarkus-custom-app-name.jar

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

流程

1. 打开 pom.xml 文件，并验证 build 部分是否具有以下元素：

   <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/GreetingResourceIT.java 文件，并验证它是否包含以下内容：

   package org.acme;
   
   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 -Dnative

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

   ./mvnw verify -Dnative
   ....
   
   GraalVM Native Image: Generating 'getting-started-1.0.0-SNAPSHOT-runner' (executable)...
   ========================================================================================================================
   [1/8] Initializing...                                                                                    (6.6s @ 0.22GB)
    Java version: 21.0.4+7-LTS, vendor version: Mandrel-23.1.4.0-1b1
    Graal compiler: optimization level: 2, target machine: x86-64-v3
    C compiler: gcc (redhat, x86_64, 13.2.1)
    Garbage collector: Serial GC (max heap size: 80% of RAM)
    2 user-specific feature(s)
    - io.quarkus.runner.Feature: Auto-generated class by Red Hat build of Quarkus from the existing extensions
    - io.quarkus.runtime.graal.DisableLoggingFeature: Disables INFO logging during the analysis phase
   [2/8] Performing analysis...  [******]                                                                  (40.0s @ 2.05GB)
     10,318 (86.40%) of 11,942 types reachable
     15,064 (57.36%) of 26,260 fields reachable
     52,128 (55.75%) of 93,501 methods reachable
      3,298 types,   109 fields, and 2,698 methods registered for reflection
         63 types,    68 fields, and    55 methods registered for JNI access
          4 native libraries: dl, pthread, rt, z
   [3/8] Building universe...                                                                               (5.9s @ 1.31GB)
   [4/8] Parsing methods...      [**]                                                                       (3.7s @ 2.08GB)
   [5/8] Inlining methods...     [***]                                                                      (2.0s @ 1.92GB)
   [6/8] Compiling methods...    [******]                                                                  (34.4s @ 3.25GB)
   [7/8] Layouting methods...    [**]                                                                       (4.1s @ 1.78GB)
   [8/8] Creating image...       [**]                                                                       (4.5s @ 2.31GB)
     20.93MB (48.43%) for code area:    33,233 compilation units
     21.95MB (50.80%) for image heap:  285,664 objects and 8 resources
    337.06kB ( 0.76%) for other data
     43.20MB in total
   
   ....
   
   
   [INFO]
   [INFO] --- maven-failsafe-plugin:3.0.0-M7:integration-test (default) @ getting-started ---
   [INFO] Using auto detected provider org.apache.maven.surefire.junitplatform.JUnitPlatformProvider
   [INFO]
   [INFO] -------------------------------------------------------
   [INFO]  T E S T S
   [INFO] -------------------------------------------------------
   [INFO] Running org.acme.GreetingResourceIT
   __  ____  __  _____   ___  __ ____  ______
    --/ __ \/ / / / _ | / _ \/ //_/ / / / __/
    -/ /_/ / /_/ / __ |/ , _/ ,< / /_/ /\ \
   --\___\_\____/_/ |_/_/|_/_/|_|\____/___/
   2024-09-27 14:04:52,681 INFO  [io.quarkus] (main) getting-started 1.0.0-SNAPSHOT native (powered by Quarkus 3.20.0.redhat-00002) started in 0.038s. Listening on: http://0.0.0.0:8081
   2024-09-27 14:04:52,682 INFO  [io.quarkus] (main) Profile prod activated.
   2024-09-27 14:04:52,682 INFO  [io.quarkus] (main) Installed features: [cdi, rest, smallrye-context-propagation, vertx]
   [INFO] Tests run: 2, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 4.696 s - in org.acme.GreetingResourceIT
   [INFO]
   [INFO] Results:
   [INFO]
   [INFO] Tests run: 2, Failures: 0, Errors: 0, Skipped: 0
   [INFO]
   [INFO]
   [INFO] --- maven-failsafe-plugin:3.0.0-M7:verify (default) @ getting-started ---

   注意

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

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

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

   注意
   • 默认情况下，原生测试使用 prod 配置文件运行，除非在 quarkus.test.native-image-profile 属性中进行了修改。

流程

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

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

   • 使用 Maven：

     ./mvnw quarkus:dev

   • 使用 Quarkus CLI：

     quarkus dev

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

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

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

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

5. 可选： 要在运行应用程序前等待调试器附加，include -Dsuspend:

   ./mvnw quarkus:dev -Dsuspend

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

   ./mvnw quarkus:dev -Ddebug=false

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

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

   • false ：JVM 在禁用调试模式的情况下启动。
   • 正确 ： JVM 以 debug 模式启动，并侦听端口 5005。
   • 客户端: JVM 以客户端模式启动，并尝试连接到 localhost:5005。
   • PORT: JVM 以调试模式启动，并侦听 PORT。

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

   • Y 或 true ：调试模式 JVM 启动暂停。
   • n 或 false ：调试模式 JVM 在不暂停的情况下启动。