Quarkus 入门

流程

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

   mvn --version

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

3. 要生成项目，请输入以下命令之一：

   注意

   Apple macOS 和 Microsoft Windows 是不支持的生产环境。

   • 如果使用 Linux 或 Apple macOS，请输入以下命令：

     mvn io.quarkus:quarkus-maven-plugin:1.11.7.Final-redhat-00009:create \
         -DprojectGroupId=org.acme \
         -DprojectArtifactId=getting-started \
         -DplatformGroupId=com.redhat.quarkus \
         -DplatformVersion=1.11.7.Final-redhat-00009 \
         -DclassName="org.acme.quickstart.GreetingResource" \
         -Dpath="/hello"
     cd getting-started

   • 如果使用 Microsoft Windows 命令行，请输入以下命令：

     mvn io.quarkus:quarkus-maven-plugin:1.11.7.Final-redhat-00009:create -DprojectGroupId=org.acme -DprojectArtifactId=getting-started -DplatformGroupId=com.redhat.quarkus -DplatformVersion=1.11.7.Final-redhat-00009 -DclassName="org.acme.quickstart.GreetingResource" -Dpath="/hello"

   • 如果使用 Microsoft Windows Powershell，请输入以下命令：

     mvn io.quarkus:quarkus-maven-plugin:1.11.7.Final-redhat-00009:create "-DprojectGroupId=org.acme" "-DprojectArtifactId=getting-started" "-DplatformVersion=1.11.7.Final-redhat-00009" "-DplatformGroupId=com.redhat.quarkus" "-DclassName=org.acme.quickstart.GreetingResource" "-Dpath=/hello"

     这些命令在 ./getting-started 目录中创建以下元素：

     • Maven 项目目录结构
     • /hello上公开的 org.acme.quickstart.GreetingResource 资源
     • 以原生模式和 JVM 模式测试应用程序的相关单元测试
     • 在启动应用程序后，一个可在 http://localhost:8080 上访问的登录页面
     • src/main/docker 目录中的 Dockerfile.jvm、Dockerfile.native 和 Dockerfile.fast-jar 文件
     • 应用程序配置文件

4. 创建目录结构后，在文本编辑器中打开 pom.xml 文件并检查文件的内容：

   <dependencyManagement>
       <dependencies>
           <dependency>
               <groupId>com.redhat.quarkus</groupId>
               <artifactId>quarkus-universe-bom</artifactId>
               <version>${quarkus.version}</version>
               <type>pom</type>
               <scope>import</scope>
           </dependency>
       </dependencies>
   </dependencyManagement>
   
   <build>
     <plugins>
       <plugin>
         <groupId>io.quarkus</groupId>
         <artifactId>quarkus-maven-plugin</artifactId>
         <version>${quarkus-plugin.version}</version>
         <executions>
           <execution>
             <goals>
               <goal>build</goal>
               <goal>generate-code</goal>
               <goal>generate-code-tests</goal>
             </goals>
           </execution>
         </executions>
       </plugin>
    </plugins>
   </build>

   Quarkus BOM 包含在 pom.xml 文件的 &lt ;dependencyManagement > 部分。因此，您不需要列出 pom.xml 文件中的单个 Quarkus 依赖项版本。另外，您可以看到 quarkus-maven-plugin 插件，该插件负责打包应用程序并提供开发模式。

5. 检查 pom.xml 文件中的 quarkus-resteasy 依赖项。这个依赖关系可让您开发 REST 应用程序：

       <dependency>
           <groupId>io.quarkus</groupId>
           <artifactId>quarkus-resteasy</artifactId>
       </dependency>

6. 查看 src/main/java/org/acme/quickstart/GreetingResource.java 文件：

   package org.acme.quickstart;
   
   import javax.ws.rs.GET;
   import javax.ws.rs.Path;
   import javax.ws.rs.Produces;
   import javax.ws.rs.core.MediaType;
   
   @Path("/hello")
   public class GreetingResource {
   
       @GET
       @Produces(MediaType.TEXT_PLAIN)
       public String hello() {
           return "hello";
       }
   }

   此文件包含一个简单的 REST 端点，它将 hello 返回 hello 作为您发送到 /hello 端点的请求。

   注意

   使用 Quarkus 时，支持 JAX-RS 的应用类，但不是必需的。另外，只创建一个 GreetingResource 类的实例，而不是每个请求的一个实例。您可以使用不同的 *Scoped 注解来配置此功能，如 ApplicationScoped、RequestScoped 等。

流程

1. 要在 development 模式中编译 Quarkus Hello application，从项目目录中输入以下命令：

   ./mvnw compile quarkus:dev

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

   [INFO] --------------------< org.acme:getting-started >---------------------
   [INFO] Building getting-started 1.0.0-SNAPSHOT
   [INFO] --------------------------------[ jar ]---------------------------------
   [INFO]
   [INFO] --- maven-resources-plugin:2.6:resources (default-resources) @ getting-started ---
   [INFO] Using 'UTF-8' encoding to copy filtered resources.
   [INFO] skip non existing resourceDirectory /Users/starksm/Dev/JBoss/Quarkus/starksm64-quarkus-quickstarts/getting-started/src/main/resources
   [INFO]
   [INFO] --- maven-compiler-plugin:3.1:compile (default-compile) @ getting-started ---
   [INFO] Changes detected - recompiling the module!
   [INFO] Compiling 2 source files to /Users/starksm/Dev/JBoss/Quarkus/starksm64-quarkus-quickstarts/getting-started/target/classes
   [INFO]
   [INFO] --- quarkus-maven-plugin:<version>:dev (default-cli) @ getting-started ---
   Listening for transport dt_socket at address: 5005
   2019-02-28 17:05:22,347 INFO  [io.qua.dep.QuarkusAugmentor] (main) Beginning quarkus augmentation
   2019-02-28 17:05:22,635 INFO  [io.qua.dep.QuarkusAugmentor] (main) Quarkus augmentation completed in 288ms
   2019-02-28 17:05:22,770 INFO  [io.quarkus] (main) Quarkus started in 0.668s. Listening on: http://localhost:8080
   2019-02-28 17:05:22,771 INFO  [io.quarkus] (main) Installed features: [cdi, resteasy]

2. 在新终端窗口中输入以下命令，向应用程序提供的端点发送请求：

   curl -w "\n" http://localhost:8080/hello
   hello

   注意

   本例使用 "\n" 属性在 命令的输出之前自动添加新行。这可防止您的终端打印 '%' 字符，或将结果和下一个命令提示符放在同一行中。

3. 按 CTRL+C 停止应用程序。

流程

1. 要修改应用程序并添加相应的 bean，请使用以下内容创建 src/main/java/org/acme/quickstart/GreetingService.java 文件：

   package org.acme.quickstart;
   
   import javax.enterprise.context.ApplicationScoped;
   
   @ApplicationScoped
   public class GreetingService {
   
       public String greeting(String name) {
           return "hello " + name;
       }
   
   }

2. 编辑 src/main/java/org/acme/quickstart/GreetingResource.java 以注入 GreetingService 并创建一个新的端点：

   package org.acme.quickstart;
   
   import javax.inject.Inject;
   import javax.ws.rs.GET;
   import javax.ws.rs.Path;
   import javax.ws.rs.Produces;
   import javax.ws.rs.core.MediaType;
   
   import org.jboss.resteasy.annotations.jaxrs.PathParam;
   
   @Path("/hello")
   public class GreetingResource {
   
       @Inject
       GreetingService service;
   
       @GET
       @Produces(MediaType.TEXT_PLAIN)
       @Path("/greeting/{name}")
       public String greeting(@PathParam String name) {
           return service.greeting(name);
       }
   
       @GET
       @Produces(MediaType.TEXT_PLAIN)
       public String hello() {
           return "hello";
       }
   }

3. 如果停止应用程序，请输入以下命令重启它：

   ./mvnw compile quarkus:dev

4. 要验证端点是否返回 hello quarkus，请在新的终端窗口中输入以下命令：

   curl -w "\n" http://localhost:8080/hello/greeting/quarkus
   hello quarkus

流程

1. 打开生成的 pom.xml 文件并查看内容：

   <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>
          </systemPropertyVariable>
       </configuration>
   </plugin>

   请注意，：

   • 将 java.util.logging.manager 系统属性设置为确保应用程序使用正确的日志管理器进行测试。
   • maven.home 属性指向 settings.xml 文件的位置，您可以在其中存储要应用到项目的自定义 Maven 配置。

2. 编辑 src/test/java/org/acme/quickstart/GreetingResourceTest.java 文件以匹配以下内容：

   package org.acme.quickstart;
   
   import io.quarkus.test.junit.QuarkusTest;
   import org.junit.jupiter.api.Test;
   
   import java.util.UUID;
   
   import static io.restassured.RestAssured.given;
   import static org.hamcrest.CoreMatchers.is;
   
   @QuarkusTest
   public class GreetingResourceTest {
   
       @Test
       public void testHelloEndpoint() {
           given()
             .when().get("/hello")
             .then()
                .statusCode(200)
                .body(is("hello"));
       }
   
       @Test
       public void testGreetingEndpoint() {
           String uuid = UUID.randomUUID().toString();
           given()
             .pathParam("name", uuid)
             .when().get("/hello/greeting/{name}")
             .then()
               .statusCode(200)
               .body(is("hello " + uuid));
       }
   
   }

   注意

   使用 QuarkusTest 运行程序，您可以指示 JUnit 在启动测试前启动应用。

3. 要从 Maven 运行这些测试，请输入以下命令：

   ./mvnw test

   注意

   您也可以从 IDE 运行测试。如果您这样做，请确保首先停止应用程序。

   默认情况下，测试在端口 8081 上运行，因此它们不会与正在运行的应用程序冲突。在 Quarkus 中，RestAssured 依赖项被配置为使用这个端口。如果要使用其他客户端，请使用 @TestHTTPResource 注释来直接将测试的应用程序的 URL 直接注入到 Test 类上的字段。此字段可以是类型 String、URL 或 URI。您还可以在此注解中提供测试路径。例如，要测试映射到 /myservlet 的 servlet，请将以下行添加到您的测试中：

   @TestHTTPResource("/myservlet")
   URL testUrl;

4. 如有必要，在 quarkus.http.test-port 配置属性中指定测试端口。

流程

1. 要打包 Quarkus 入门项目，请 在根目录中 输入以下命令：

   ./mvnw package

   此命令在 /target 目录中生成以下 JAR 文件：

   • getting-started-1.0-0-SNAPSHOT.jar ：包含项目的类和资源。这是由 Maven 构建生成的常规构件。

   • getting-started-1.0-0-SNAPSHOT-runner.jar ：是可执行 JAR 文件。请注意，这个文件不是 uber-JAR 文件，因为依赖项被复制到 target/lib 目录中。

     警告

     当应用程序以 development 模式运行时，必须按 CTRL+C 来停止应用程序。当您尝试在启用了开发模式时打包应用程序时，您将遇到端口冲突。

2. 输入以下命令启动应用程序：

   java -jar target/getting-started-1.0-0-SNAPSHOT-runner.jar

   注意

   运行程序 JAR 文件中的 MANIFEST.MF 文件的 Class-Path 条目明确列出了 lib 目录中的 JAR 文件。如果要从其他位置部署应用程序，您必须复制 runner JAR 文件和 lib 目录。

流程

1. 使用 Web 浏览器导航至 https://code.quarkus.redhat.com

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

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

   3. 选择您要用于编译和启动应用程序的构建工具。您选择的构建工具：

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

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

        注意

        红帽只支持使用 code.quarkus.redhat.com 创建 Quarkus Maven 项目。红帽不支持生成 Gradle 项目。

        

3. 指定应用程序项目的其他详情：

   1. 选择 Configure more options 以显示包含更多应用程序详情的字段。
   2. 输入项目生成的工件中使用的版本。此字段的默认值为 15000 SNAPSHOT。建议使用 语义版本，但如果您愿意，可以使用不同类型的版本。

   3. 选择是否想将 code.quarkus.redhat.com 添加示例代码到项目中。当您从扩展列表中添加带有 图标标记的扩展时，您可以在生成项目时启用这个选项为这些扩展自动创建示例类文件和资源文件。当您没有添加提供示例代码的任何扩展时，这个选项不会影响您生成的项目。

      
      注意

      code.quarkus.redhat.com 自动使用 Quarkus 的最新发行版本。您可以在生成项目后手动更改 pom.xml 文件中的 BOM 版本。

4. 从扩展列表中选择您要在应用程序中使用的扩展。所选扩展作为 Quarkus 应用程序的依赖项包括，其版本由 Quarkus 平台管理，以确保其兼容性。

   您可以启用选项，为使用 图标标记的扩展自动生成示例代码。

   

   请注意，红帽为列表上的单个扩展提供了不同级别的支持，这由每个扩展名称旁的标签指定： https://access.redhat.com/articles/3348731

   • 红帽完全支持 SUPPORTED 扩展用于生产环境中的企业应用程序。
   • TECH-PREVIEW 扩展受红帽在生产环境中的支持，在 技术预览功能支持范围 下受到红帽的支持。
   • 红帽在生产环境中不支持 DEV-SUPPORT 扩展，但红帽提供的核心功能则由红帽开发人员用于开发新的应用程序。
   • 红帽不支持在生产环境中使用的未标记扩展。

   • DEPRECATED 扩展计划由提供相同功能的较新的技术或实现替代。

     您可以扩展每个扩展旁的 overflow 菜单( '{}')来访问可用于的额外选项：

     • 在命令行中使用 Quarkus maven 插件，为现有项目添加扩展。
     • 复制 XML 代码片段，将扩展添加到项目的 pom.xml 文件中。
     • 获取每个扩展的 groupId、artifactId 和版本。

     • 打开扩展指南。

       

5. 选择 Generate your application 确认您的选择并显示覆盖屏幕，其中包含包含您生成的项目的存档的下载链接。overlay 屏幕还显示可用于编译和启动应用程序的自定义命令。
6. 选择 Download the ZIP，以使用生成的项目文件将存档保存到您的计算机中。
7. 提取存档的内容。

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

   cd <directory_name>

9. 以开发模式编译并启动应用程序：

   ./mvnw compile quarkus:dev