创建第一个应用程序

了解如何创建Hello World Quarkus应用程序。本指南涵盖:

  • 引导应用程序

  • 创建Jakarta REST端点

  • 注射豆类

  • 功能测试

  • 应用程序的打包

1.前提条件

要完成本指南,您需要:

验证Maven是否使用了预期的Java

如果您安装了多个JDK,Maven不一定会选择预期的java你可能会得到意想不到的结果。您可以通过运行mvn—版本.

2.架构

在本指南中,我们创建了一个简单的应用程序,用于你好端点。为了证明依赖项注入,此端点使用招呼豆子。

建筑

本指南还涵盖端点的测试。

3.解决方案

我们建议您按照引导项目然后逐步创建应用程序。

然而,您可以直接进入完成的示例。

下载档案文件或克隆git存储库:

git克隆https://github.com/quarkusio/quarkus-quickstarts.git

解决方案位于开始 目录.

4.引导项目

创建新Quarkus项目的最简单方法是打开终端并运行以下命令:

CLI(命令行界面)
quarkus create app org.acme:入门\--extension=“最新”cd获取启动

要创建Gradle项目,请添加--梯度--gradle-kotlin-dsl公司选项。

有关如何安装和使用Quarkus CLI的更多信息,请参阅Quarkus CLI(Quarkus命令行界面)指南。

马文
mvn-io.quarkus.platform:quarkus-maven插件:3.9.4:创建\-DprojectGroupId=org.acme\-DprojectArtifactId=开始\-Dextensions='rest'cd获取启动

要创建Gradle项目,请添加-DbuildTool=渐变-DbuildTool=渐变kotlin dsl选项。

对于Windows用户:

  • 如果使用cmd,(不要使用反斜杠\并将所有内容放在同一条线上)

  • 如果使用Powershell,请包装-D类参数用双引号括起来,例如。“-DprojectArtifactId=开始”

它在中生成以下内容./getting-started:

  • Maven构造

  • 一个org.acme网站。问候语资源资源公开于/你好

  • 相关的单元测试

  • 可在上访问的登录页http://localhost:8080启动应用程序后

  • 例子Dockerfile文件两个文件本地的联合虚拟机模式src/main/docker

  • 应用程序配置文件

生成后,请查看pom.xml(pom.xml).您将发现Quarkus BOM的导入,允许您忽略不同Quarkus依赖项的版本。此外,您可以看到夸库斯·马文·普鲁金负责应用程序的打包,并提供开发模式。

<依赖性管理><依赖项><依赖性><groupId>${quarkus.platform.group-id}</groupId><artifactId>${quarkus.platform.artifact-id}<version>${quarkus.platform.version}<type>pom</type><scope>导入</scope></依赖性></依赖项></dependencyManagement><构建><插件><插件><groupId>${quarkus.platform.group-id}</groupId><artifactId>quarkus maven插件</artifactId><version>${quarkus.platform.version}<extensions>true</extensions><执行><执行><目标><goal>构建</goal><goal>生成代码生成代码测试</目标></执行></执行></plugin></插件></构建>

在Gradle项目中,您会发现类似的设置:

  • Quarkus Gradle插件

  • 一个强制平台Quarkus BOM指令

如果我们关注依赖项部分,您可以看到允许开发REST应用程序的扩展:

pom.xml(pom.xml)
<依赖性><groupId>io.quarkus</groupId><artifactId>quarkus-rest</artifactId></依赖性>
建筑.gradle
实现(“io.quarkus:quarkus-rest”)

4.1. 雅加达REST资源

在项目创建过程中src/main/java/org/acme/GreetingResource.java已创建包含以下内容的文件:

软件包org.acme;导入jakarta.ws.rs.GET;导入jakarta.ws.rs.Path;导入jakarta.ws.rs.Produces;导入jakarta.ws.rs.core。媒体类型;@路径(“/hello”)公共课问候资源{@GET(获取)@产品(MediaType.TEXT_PLAIN)public字符串hello(){return“来自Quarkus REST的Hello”;}}

这是一个非常简单的REST端点,将“Hello from Quarkus REST”返回到“/Hello”上的请求。

与香草雅加达REST的区别

使用Quarkus,无需创建应用程序类。它受支持,但不是必需的。此外,只有一个实例创建了资源的,而不是每个请求一个。您可以使用不同的*范围界定注释(应用程序范围,已请求范围等)。

5.运行应用程序

现在,我们准备运行应用程序:

CLI(命令行界面)
夸克偏差
马文
./mvnw夸克:dev
梯度
./gradlew--console=普通quarkusDev
[信息]--------------------<org.acme:getting-started>---------------------[信息]建筑开始1.0.0-SNAPSHOT[信息]---------------------------------[jar]---------------------------------[信息][信息]---maven-resources-plugin:2.6:resources(default-resource)@getting-started---[信息]使用“UTF-8”编码复制筛选的资源。[信息]跳过不存在的资源目录<path>/getting-started/src/main/resources[信息][信息]---maven-compiler-plugin:3.1:compile(default-compile)@getting-started---[信息]检测到更改-重新编译模块![信息]将2个源文件编译为<path>/getting-started/target/classes[信息][信息]---quarkus-maven-plugin:<版本>:dev(default-cli)@getting-started---侦听地址为5005的传输dt_socket2019-02-28 17:05:22347信息[io.qua.dep.QuarkusAugmentor](main)开始夸克增强2019-02-28 17:05:22635信息[io.qua.dep.QuarkusAugmentor](主)Quarkus增强在288ms内完成2019-02-28 17:05:22770 INFO[io.quarkus](main)quarkus以0.668秒开始。聆听:http://localhost:80802019-02-28 17:05:22771 INFO[io.quarkus](main)已安装功能:[cdi,rest]

启动后,您可以请求提供的端点:

$curl-w“\n”http://localhost:8080/hello来自Quarkus REST的您好

点击CTRL+C组合键停止应用程序,或保持其运行并享受炽热的快速重新加载。

自动添加换行符卷曲-w“\n”

我们正在使用卷曲-w“\n”在本例中,避免终端打印“%”或将结果和下一个命令提示符放在同一行。

6.使用注射

Quarkus中的依赖项注入基于ArC,ArC是为Quarkus架构量身定制的基于CDI的依赖项插入解决方案。如果您是CDI新手,我们建议您阅读CDI简介指南。

Quarkus仅实现CDI功能的子集,并附带非标准功能和特定APIS,您可以在上下文和依赖项注入指南.

ArC依赖于夸克休止所以你手边已经有了。

让我们修改应用程序并添加一个伴生bean。创建src/main/java/org/acme/GreetingService.java包含以下内容的文件:

包装组织;导入jakarta.enterprise.context。应用程序范围;@应用程序范围公共课问候服务{公共字符串问候语(字符串名称){return“hello”+名称;}}

编辑问候语资源类来注入问候语服务并使用它创建新端点:

软件包org.acme;导入jakarta.inject。注入;导入jakarta.ws.rs.GET;导入jakarta.ws.rs.Path;导入jakarta.ws.rs.Produces;导入jakarta.ws.rs.core。媒体类型;@路径(“/hello”)公共课问候资源{@注入问候服务;@GET(获取)@产品(MediaType.TEXT_PLAIN)@路径(“/greeting/{name}”)公共字符串问候语(字符串名称){退货服务。问候语(姓名);}@GET(获取)@产品(MediaType.TEXT_PLAIN)public字符串hello(){return“来自Quarkus REST的Hello”;}}

如果您停止应用程序(请记住,您不必这样做,更改将通过我们的实时重新加载功能自动部署),使用以下命令重新启动应用程序:

CLI(命令行界面)
夸库斯-德夫
马文
./mvnw夸克:dev
梯度
./gradlew--console=普通quarkusDev

然后检查端点是否返回你好quarkus如预期:

$curl-w“\n”http://localhost:8080/你好/问候/夸库斯你好quarkus

7.发展模式

quarkus:开发在开发模式下运行Quarkus。这可以通过后台编译实现实时重新加载,这意味着当您修改Java文件和/或资源文件并刷新浏览器时,这些更改将自动生效。这也适用于配置属性文件等资源文件。刷新浏览器会触发工作区扫描,如果检测到任何更改,则会重新编译Java文件并重新部署应用程序;然后,重新部署的应用程序将为您的请求提供服务。如果有任何问题通过编译或部署,错误页面会告诉您。

这还将侦听端口上的调试器5005。如果要在运行之前等待调试器附加可以通过-暂停在命令行上。如果你根本不需要调试器,你可以使用-Ddebug=假.

8.测试

好吧,到目前为止还不错,但如果进行一些测试,情况会不会更好一些,以防万一。

在生成的构建文件中,您可以看到2个测试依赖项:

pom.xml(pom.xml)
<依赖性><groupId>io.quarkus</groupId><artifactId>quarkus-junit5</artifactId><scope>测试</依赖性><依赖性><groupId>请放心</groupId><artifactId>重置保险<scope>测试</依赖性>
建筑.gradle
测试实现(“io.quarkus:quarkus-junit5”)testImplementation(“io.rest-assered:rest-assured”)

Quarkus支持J单元5测验。

因此,在Maven的情况下Surefire Maven插件必须设置,因为默认版本不支持JUnit 5:

<插件><artifactId>maven-surefireplugin</artifactId><version>${surefireplugin.version}<配置><systemPropertyVariables><java.util.logging.manager>org.jboss.logmanager。日志管理器</java.util.logging.manager><maven.home>${maven.hame}</maven.home></systemPropertyVariables></配置></plugin>

我们还设置了java.util.logging(登录)系统属性,以确保测试将使用正确的日志管理器和maven.家以确保自定义配置${maven.home}/conf/settings.xml应用(如果有)。

生成的项目包含一个简单的测试。编辑src/test/java/org/acme/GreetingResourceTest.java匹配以下内容:

软件包org.acme;导入io.quarkus.test.junit。Quarkus测试;导入org.junit.jupiter.api。测试;导入java.util。UUID;导入静态io.restsured。RestAssured.given公司;导入静态org.hamcrest。CoreMatchers.is;@Quarkus测试公共类GreetingResourceTest{@测试(1)公共void testHelloEndpoint(){给定().when().get(“/hello”)然后().statusCode(200)(2).body(是(“来自Quarkus REST的Hello”);}@测试公共void testGreetingEndpoint(){字符串uuid=uuid.randomUUID().toString();给予().pathParam(“名称”,uuid).when().get(“/hello/greeting/{name}”)然后().statusCode(200).body(is(“hello”+uuid));}}
1 通过使用Quarkus测试runner,您指示JUnit在测试之前启动应用程序。
2 检查HTTP响应状态代码和内容

这些测试使用重置压力,但可以随意使用您喜爱的库。

您可以使用Maven运行这些:

./mvnw测试

您还可以直接从IDE运行测试(确保先停止应用程序)。

默认情况下,测试将在端口上运行8081这样就不会与正在运行的应用程序冲突。我们自动configure Rest假定使用此端口。如果要使用其他客户端,则应使用@测试HTTPResource注释将被测试应用程序的URL直接注入测试类的字段中。此字段可以是以下类型字符串,统一资源定位地址乌里。也可以为该注释指定测试路径的值。例如,如果我想测试Servlet映射到/我的仆人我只想在测试中添加以下内容:

@TestHTTPResource(“/myservlet”)URL testUrl;

测试端口可以通过控制quarkus.http.test-port网站config属性。Quarkus还创建了一个系统属性已调用测试.url它设置为无法使用注入的情况下的基本测试URL。

9.使用多模块项目或外部模块

Quarkus大量利用Jandex公司在构建时,发现各种类或注释。这方面的一个可立即识别的应用是CDIBean发现。因此,如果未正确设置此生成时间发现,大多数Quarkus扩展将无法正常工作。

由于我们的Maven和Gradle插件,此索引默认在Quarkus配置的项目上创建。

但是,在使用多模块项目时,请务必阅读使用多模块项目的部分马文梯度指南。

如果您计划使用外部模块(例如,所有域对象的外部库),您需要通过添加Jandex插件(如果可以修改的话)使这些模块为索引过程所知或通过夸库斯指数依赖性您的应用程序.属性(在无法修改模块的情况下很有用)。

请务必阅读Bean发现有关更多信息,请参阅CDI指南的第节。

10.打包并运行应用程序

应用程序打包使用:

CLI(命令行界面)
夸库斯构造
马文
./mvnw安装
梯度
./gradlew版本

它在/目标:

  • 启动getting-started-1.0.0-SNAPSHOT.jar-它只包含项目的类和资源,是常规的Maven构建产生的工件-它是可运行的罐子;

  • 这个quarkus-app软件包含quarkus-run.jarjar文件-作为可执行文件罐子.请注意,它不是吕贝尔贾尔作为依赖项被复制到的子目录中quarkus-app/lib/.

您可以使用以下命令运行应用程序:java-jar目标/quarkus-app/quarkus运行.jar

如果要将应用程序部署到某个地方(通常是在容器中),则需要将整个应用程序部署在quarkus-app软件目录。
在运行应用程序之前,不要忘记停止热重新加载模式(点击CTRL+C组合键),否则将发生端口冲突。

默认情况下,当Quarkus应用程序启动时(在常规或开发模式下),它将显示ASCII艺术横幅。可通过设置禁用横幅quarkus.banner.enabled=假在里面应用程序.属性,通过设置-Dquarkus.banner.enabled=假Java系统属性,或通过设置夸克斯_巴纳_启用环境变量到.此外,用户可以通过将横幅文件放置在src/main/resources(src/main/resources)和配置quarkus.banner.path=文件名在里面应用程序.属性.

12.非应用程序端点

各种Quarkus扩展提供非应用程序端点,提供有关应用程序的各种信息。此类扩展的示例有健康,韵律学,开放应用程序接口和信息扩展。

这些非应用程序端点通常可以在/q个前缀如下:

  • /问题/健康

  • /q/指标

  • /q/openapi(开放api)

  • /问题/信息

但用户也可以选择使用专用的管理界面.

12.1. 信息端点

如果应用程序包含quarkus-info(夸克信息)扩展,则Quarkus将默认公开/问题/信息端点,提供有关构建、java版本、版本控制和操作系统的信息。公开信息的详细级别是可配置的。

所有实现信息贡献者将拾取它们的数据并将其附加到端点。

12.1.1. 配置参考

在生成时修复配置属性-所有其他配置属性都可以在运行时重写

Configuration属性

类型

违约

是否将启用信息终结点

环境变量:QUARKUS_INFO_启用

显示更多

布尔值

真的

信息终结点所在的路径

环境变量:夸库信息路径

显示更多

一串

信息

git info是否将包含在info端点中

环境变量:QUARKUS_INFO_GIT_启用

显示更多

布尔值

真的

控制git部分中的信息量

环境变量:夸克US_INFO_GIT_MODE

显示更多

标准,满的

标准

生成信息是否将包含在信息端点中

环境变量:QUARKUS_INFO_BUILD启用

显示更多

布尔值

真的

操作系统信息是否将包含在信息端点中

环境变量:QUARKUS_INFO_OS_启用

显示更多

布尔值

真的

java info是否将包含在info端点中

环境变量:夸克US_INFO_JAVA_ENABLED

显示更多

布尔值

真的

要添加到生成节的其他属性

环境变量:夸克US_INFO_BUILD

显示更多

映射<字符串,字符串>

13.接下来是什么?

本指南介绍了使用Quarkus创建应用程序。然而,还有更多。我们建议通过创建您的第二个Quarkus应用程序,具有开发服务和持久性。您可以学习如何创建本机可执行文件并使用构建本机可执行指南.如果您对反应型产品感兴趣,我们建议您反应式指南入门,在这里您可以看到如何使用Quarkus实现反应式应用程序。

此外工具导向装置文档解释了如何:

  • 在单个命令行中构建项目

  • 启用发展模式(热重新加载)

  • 在您喜爱的IDE中导入项目

  • 等等

相关内容