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

流程

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

   mvn --version

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

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

   • 输入以下命令：

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

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

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

   • 以互动模式创建项目：

     mvn com.redhat.quarkus.platform:quarkus-maven-plugin:3.2.12.SP1-redhat-00003:create

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

     注意

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

     mvn com.redhat.quarkus.platform:quarkus-maven-plugin:3.2.12.SP1-redhat-00003:create -B

   • 使用 Red Hat build of 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.2.11.Final-redhat-00001</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 插件 的特定原生配置集：

   <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.package.type>native</quarkus.package.type>
           </properties>
       </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 将初学者代码添加到项目中。当您添加标记为 "STARTER-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. 要在 dev 模式中编译并启动应用程序，请使用以下方法之一：

   • 使用 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= 之后输入扩展名称或部分名称。以下示例搜索名称中包含文本的扩展：

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

   这个命令返回以下结果：

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

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

   quarkus extension add 'agroal'

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. 点 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. 编辑您要更改的属性值并保存文件。

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

   属性	描述	类型	default
   quarkus.package.main-class	应用程序的入口点。在大多数情况下，您必须更改这个值。	string	io.quarkus.runner.GeneratedMain
   quarkus.package.type	软件包请求的输出类型，您可以将其设置为 'jar'（将 'fast-jar'）、'legacy-jar' 用于 pre-1.12 默认 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

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: 17.0.7+7, vendor version: Mandrel-23.0.0.0-Final
    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...    [[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
   __  ____  __  _____   ___  __ ____  ______
    --/ __ \/ / / / _ | / _ \/ //_/ / / / __/
    -/ /_/ / /_/ / __ |/ , _/ ,< / /_/ /\ \
   --\___\_\____/_/ |_/_/|_/_/|_|\____/___/
   2023-08-28 14:04:52,681 INFO  [io.quarkus] (main) getting-started 1.0.0-SNAPSHOT native (powered by Red Hat build of Quarkus 3.2.9.Final) started in 0.038s. Listening on: http://0.0.0.0:8081
   2023-08-28 14:04:52,682 INFO  [io.quarkus] (main) Profile prod activated.
   2023-08-28 14:04:52,682 INFO  [io.quarkus] (main) Installed features: [cdi, resteasy-reactive, 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&gt; 是等待时间（以秒为单位）：

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

   注意
   • 除非在 quarkus.test.native-image-profile 属性中修改了，否则会使用 prod 配置集运行原生测试。

流程

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 启动而不暂停。