quarkus
Quarkus – 一个针对OpenJDK HotSpot和GraalVM量身定制的Kubernetes本机Java堆栈,它是从最佳Java库和标准中精制而成的。 –是一个容器优先的框架,针对快速启动时间和低内存消耗进行了优化。 该框架基于许多流行的Java库构建,并且为构建标准REST以及响应式和消息驱动型微服务提供支持。 由于快速的启动时间和较低的内存使用量,Quarkus也可用于在无服务器环境中实现功能。 凭借统一的配置,出色的实时重装功能和工具支持,Quarkus为快速开发应用程序提供了许多可能性。
了解如何开始使用Quarkus和构建PetClinic REST API。
这篇博客文章涵盖:
- 开发环境要求
- 建立新专案
- 使用Java 11开发,构建和运行应用程序
- 使用Postgres和Flyway进行数据源配置
- 分页CRUD服务
- 创建集成测试
- 实时重新加载和调试
- Docker化应用程序(本机和非本机)
关于PetClinic API
我决定重新使用在本博文Spring Boot和Spring Data REST中使用的PetClinic模型。
基本上,它是用于管理虚拟PetClinic的基本CRUD服务:宠物,兽医,来访等。
先决条件
码头工人
Docker将用于运行服务本身的dockerized版本,但也将用于运行PostgreSQL服务器。
带有GraalVM的JDK 11
PetClinic API将使用Java 11构建,因此必须安装JDK 11。 为了构建本机可执行文件,必须存在GraalVM 19.3+,并且由于它是基于OpenJDK 11构建的,因此这将是本教程的最佳选择。 安装(和管理Java SDK的多个版本)最简单的方法是使用SDKMAN!
要支持本机映像,请确保安装所有必需的依赖项。 可以在GraalVM文档中找到更多信息: https ://www.graalvm.org/docs/reference-manual/native-image/
GraalVM官方文档: GraalVM
终奌站
该服务是使用iTerm2和oh-my-zsh在macOS上开发的。 我还将httpie用作默认的HTTP客户端。
IntelliJ
我首选的IDE是IntelliJ,我在从事此项目时就使用了它。
在本文中了解有关我在macOS上使用的工具的更多信息: macOS:(Java)开发人员的基本工具
使用Docker运行PostgreSQL
该应用程序将连接到Postgres服务器,并根据配置文件( dev
, test
, prod
)应用不同的配置。 为此,我们将需要运行三台服务器:每台服务器具有不同的数据库名称,端口和凭据。 为了简化设置,可以利用Docker。
开发数据库
- 创建并运行容器:
$ docker run --name petclinic-db-dev -p 5433 : 5432 -e POSTGRES_DB=petclinic-dev -e POSTGRES_USER=petclinic-dev -e POSTGRES_PASSWORD=petclinic-dev -d postgres:alpine
- 运行先前停止的容器:
$ docker start petclinic-db-dev
测试数据库
- 创建并运行容器:
$ docker run --name petclinic-db-test -p 5434 : 5432 -e POSTGRES_DB=petclinic-test -e POSTGRES_USER=petclinic-test -e POSTGRES_PASSWORD=petclinic-test -d postgres:alpine
- 运行先前停止的容器:
$ docker start petclinic-db-test
产品数据库
- 创建并运行容器:
$ docker run --name petclinic-db -p 5432 : 5432 -e POSTGRES_DB=petclinic -e POSTGRES_USER=petclinic -e POSTGRES_PASSWORD=petclinic -d postgres:alpine
- 运行先前停止的容器:
$ docker start petclinic-db
入门
引导应用程序
您可以在命令行中使用Maven引导应用程序,也可以使用在线生成器。 在线生成器允许探索可以构成Quarkus应用程序的扩展和技术,并且不需要本地Maven安装。 您可以在此处访问生成器: https : //code.quarkus.io
需要以下扩展来构建PetClinic API服务:
- RESTEasy JAX-RS –实现JAX-RS等的REST框架
- RESTEasy Jackson –对RESTEasy的Jackson序列化支持
- SmallRye OpenAPI –使用OpenAPI记录您的REST API – Swagger UI随附
- 带有Panache的Hibernate ORM –在带有Panache的Hibernate ORM中定义持久性模型
- Hibernate Validator –验证进入您的REST端点的数据
- JDBC驱动程序– PostgreSQL – PostgreSQL数据库连接器
- Flyway –处理数据库架构迁移
选择依赖项后,您可以下载zip,解压缩并开始开发服务。
下载的项目具有标准的Maven项目布局。 它包含Maven包装器,因此无需本地Maven安装即可开发项目。 您还会注意到src/main/docker
带有本机和JVM映像的Docker文件。
主配置文件application.properties
位于src/main/resources
。 此文件夹还包含META-INF/resources
文件夹,用于存储应用程序的静态资源,例如index.html
文件。
在
在线生成器默认情况下使用Java 8生成项目,因此要使用Java 11,需要进行一些调整。
- 在生成的项目的
pom.xml
中,更改Java版本:
-
< maven.compiler.source >11</ maven.compiler.source >
-
< maven.compiler.target >11</ maven.compiler.target >
- 在
src/main/docker/Dockerfile.jvm
设置ARG JAVA_PACKAGE=java-11-openjdk-headless
在开发模式下运行项目
进行更改后,您可以启动应用程序。 打开终端,导航到项目的文件夹并运行以下命令:
$ ./mvnw compile quarkus:dev
注意:Quarkus具有三种内置模式: dev
, test
和prod
取决于您如何运行应用程序。
在IntelliJ中开发
在IntelliJ中,您只需打开项目的文件夹或pom.xml
。 ( File > Open
)。 该项目只能使用Maven启动。 这可以通过Maven运行配置来完成,因为没有主类可以启动应用程序,例如在Spring Boot中 。
对我来说,使用Quarkus进行开发时最好的体验是当我在IntelliJ外部的终端中运行应用程序时。
调试
在开发模式下执行Quarkus应用程序时,它将以启用的调试协议(在端口5005上)启动。 要在IntelliJ中调试Quarkus应用程序,您需要通过Run > Attach to Process
调试器附加到正在Run > Attach to Process
。 我没有调试应用程序的麻烦。
注意:可以在禁用调试的开发模式下运行该应用程序: ./mvnw quarkus:dev -Ddebug=false
,但老实说,默认情况下启用调试器时,我没有发现任何性能问题。
实时重载
我认为,实时重新加载是Quarkus最强大的功能。 效果惊人。 基本上,您可以更改源代码中所需的任何内容,执行请求,然后眨眼间即可重新加载应用程序。 我正在重新整理类和程序包,移动文件,添加和删除端点,而所有这些操作都没有一次重启。
数据源配置
所有属性都转到src/main/resources/application.properties
。
默认数据源属性(
quarkus.datasource.url=jdbc:postgresql: //localhost:5432/petclinic quarkus.datasource.driver=org.postgresql.Driver quarkus.datasource.username=petclinic quarkus.datasource.password=petclinic
Dev数据源属性(
要设置模式(或配置文件)的特定属性,请使用%mode
:
%dev.quarkus.datasource.url=jdbc:postgresql: //localhost:5433/petclinic-dev %dev.quarkus.datasource.username=petclinic-dev %dev.quarkus.datasource.password=petclinic-dev
测试数据源属性(
%test.quarkus.datasource.url=jdbc:postgresql: //localhost:5434/petclinic-test %test.quarkus.datasource.username=petclinic-test %test.quarkus.datasource.password=petclinic-test
另请参阅: https : //quarkus.io/guides/datasource
飞路迁移
要使用Flyway,请在src/main/resources
创建db/migration
文件夹,然后添加迁移文件。 我的第一个迁移文件称为V1.0.0__PetClinic.sql
,其中包含该服务的所有架构(DDL)和示例数据。
注意:Quarkus支持SQL导入,可以通过quarkus.hibernate-orm.sql-load-script
为每个配置文件配置SQL导入,但是我无法使其工作。 请参阅我在Github上报告的问题: https : //github.com/quarkusio/quarkus/issues/7358
另请参阅: https : //quarkus.io/guides/flyway
JPA实体
PetClinic的域模型相对简单,但是它包含一些单向和双向关联以及基本继承,这使其比简单的Hello World类型的模型要好一些。
请注意,在此示例中,JPA实体由相应的Panache存储库直接在JAX-RS资源中返回(请参见下文),因此,实体类包含JPA和Jackson批注的混合。
例如:
-
-
-
-
private LocalDateTime date;
-
-
-
private String description;
-
-
-
private Pet pet;
-
-
-
private Vet vet;
-
public Visit() {
-
this .date = LocalDateTime.now();
-
} }
-
uniqueConstraints =
-
-
-
-
inverseJoinColumns =
-
-
private Set<Specialty> specialties;
-
-
-
private Set<Visit> visits; }
所有实体都位于pl.codeleak.samples.petclinic.model
包中。
HibernateORM与Panache
如果您熟悉Spring,我想您已经听说过Spring Data项目。 在我看来, 带有Panache的Hibernate ORM具有相似的目标:通过消除重复和繁琐的工作,简化了JPA的开发。 Panache支持排序,分页, java.util.Optional
和java.utitl.stream.Stream
等。
你有两种方法来工作,以耀目:与创建实体PanacheEntity
或创建库PanacheRepository
。 我在这个项目中尝试了两种方法,但是由于实体中的继承问题,我决定坚持使用老式的方法。
带有Panache的Hibernate ORM的基本存储库定义:
-
public class OwnerRepository implements PanacheRepository<Owner> {
-
List<Owner> findByLastName(String lastName) {
-
return list( “lastName” , lastName);
-
} }
所有存储库都位于pl.codeleak.samples.petclinic.repository
包中。
另请参阅: https : //quarkus.io/guides/hibernate-orm-panache
创建REST API
JAX-RS资源
Quarkus使用带有RESTEasy的JAX-RS。 要创建API端点,我们需要创建JAX-RS资源:
-
-
public static final String RESOURCE_PATH = “/owners” ;
-
-
UriInfo uriInfo;
-
-
OwnerRepository ownerRepository;
-
-
PetRepository petRepository;
-
-
public Response getAll(
-
}
-
-
-
public Response getOne(
-
}
-
-
-
public List<Pet> getPets(
-
}
-
-
-
-
public Response create(
-
} }
依赖注入是通过CDI完成的-上下文和依赖注入 。 资源对象将由Quarkus自动配置。 必须将所有其他依赖项配置为具有CDI批注的依赖项注入。
例如,可以使用@ApplicationScoped
注释存储库,然后使用@Inject
注入存储库:
-
-
List<Owner> findByLastName(String lastName) {
-
return list( “lastName” , lastName);
-
} }
所有资源都位于pl.codeleak.samples.petclinic.api
包中。
另请参阅: https : //quarkus.io/guides/cdi-reference
分页
如前所述,Panache为分页结果提供支持。 我们可以轻松地在我们的资源中轻松利用它:
-
-
return Response.ok(((PanacheRepository) petRepository).findAll()
-
.page(Page.of(pageRequest.getPageNum(), pageRequest.getPageSize()))
-
.list()).build(); }
PageRequest
是一个包含pageNum
和pageSize
查询参数的bean:
-
public class PageRequest {
-
-
-
private int pageNum;
-
-
-
private int pageSize; }
使用httpie可以轻松完成分页请求:
-
$ http get : 8080 /owners pageNum== 0 pageSize== 2 HTTP/ 1.1 200 OK Content-Length: 250 Content-Type: application/json [
-
{
-
“address” : “110 W. Liberty St.” ,
-
“city” : “Madison” ,
-
“firstName” : “George” ,
-
“id” : 1 ,
-
“lastName” : “Franklin” ,
-
“telephone” : “6085551023”
-
},
-
{
-
“address” : “638 Cardinal Ave.” ,
-
“city” : “Sun Prairie” ,
-
“firstName” : “Betty” ,
-
“id” : 2 ,
-
“lastName” : “Davis” ,
-
“telephone” : “6085551749”
-
} ]
交易次数
在JPA中创建新对象需要活动事务。 为了将事务绑定到资源对象中的当前方法,请使用@Transactional
,否则在方法执行期间将引发异常:
-
-
ownerRepository.persist(owner);
-
var location = uriInfo.getAbsolutePathBuilder()
-
.path( “{id}” )
-
.resolveTemplate( “id” , owner.getId())
-
.build();
-
return Response.created(location).build(); }
使用httpie创建新资源:
-
$ http post : 8080 /owners <<< ‘ {
-
“address” : “110 W. Liberty St.” ,
-
“city” : “Madison” ,
-
“firstName” : “George” ,
-
“lastName” : “Franklin” ,
-
“telephone” : “6085551023” }’ HTTP/ 1.1 201 Created Content-Length: 0 Location: http: //localhost:8080/owners/1042
验证方式
该项目使用Hibernate Validator扩展。 通过此扩展,您可以使用标准的Hibernate验证批注(例如@NotBlank
),并且当资源方法的输入参数使用@Valid
注释时,验证将自动触发,并且错误响应将返回给调用该方法的客户端。
以下请求的示例响应:
-
$ http post : 8080 /owners <<< ‘{}’ HTTP/ 1.1 400 Bad Request Content-Length: 626 Content-Type: application/json validation-exception: true {
-
“classViolations” : [],
-
“exception” : null ,
-
“parameterViolations” : [
-
{
-
“constraintType” : “PARAMETER” ,
-
“message” : “must not be empty” ,
-
“path” : “create.owner.address” ,
-
“value” : “”
-
},
-
…
-
{
-
“constraintType” : “PARAMETER” ,
-
“message” : “must not be empty” ,
-
“path” : “create.owner.telephone” ,
-
“value” : “”
-
}
-
],
-
“propertyViolations” : [],
-
“returnValueViolations” : [] }
关于实时重新加载功能的注意事项:您可以对源代码进行任何更改,并使用httpie执行新请求。 该应用程序快速重新加载,您会立即获得结果。 无需重新启动。
另请参阅: https : //quarkus.io/guides/validation
Java 8日期和时间支持
RESTEasy Jackson扩展位于项目中时,在JSON序列化和反序列化期间支持java.util.time
类型。
在以下示例中,访问日期以@JsonFormat
批注提供的格式进行序列化和反序列化:
-
-
-
-
private LocalDateTime date; }
检查如何使用htppie序列化日期:
-
$ http get : 8080 /visits/ 1 HTTP/ 1.1 200 OK Content-Length: 174 Content-Type: application/json {
-
“date” : “2013/01/01 00:00” ,
-
“description” : “rabies shot” ,
-
“id” : 1 ,
-
“pet” : {
-
“birthDate” : “2012/09/04” ,
-
“id” : 7 ,
-
“name” : “Samantha”
-
},
-
“vet” : {
-
“firstName” : “Helen” ,
-
“id” : 2 ,
-
“lastName” : “Leary”
-
} }
您还可以使用所需的日期时间格式将访问存储在请求正文中:
-
$ http post : 8080 /visits <<< ‘ {
-
“date” : “2020/01/01 00:00” ,
-
“description” : “lorem ipsum” ,
-
“pet” : {
-
“id” : 7
-
},
-
“vet” : {
-
“id” : 2
-
} }’ HTTP/ 1.1 201 Created Content-Length: 0 Location: http: //localhost:8080/visits/1042
OpenAPI / Swagger支持
SmallRye OpenAPI扩展负责提供API文档,并且在开发模式下启用了SwaggerUI。
默认端点是:
- OpenAPI文档–
/openapi
- SwaggerUI –
/swaggerui
另请参阅: https : //quarkus.io/guides/openapi-swaggerui
整合测试
Quarkus使用JUnit 5和RESTAssured进行集成测试。 可以使用@QuarkusTest
批注创建test
,并且默认情况下会在激活test
配置文件的情况下执行test
。
-
@QuarkusTest public class PetResourceTest {
-
@Test
-
public void pagedList() {
-
given()
-
.when().get( “/pets?pageNum=0&pageSize=2” )
-
.then()
-
.statusCode( 200 )
-
.body(
-
“$.size()” , is( 2 ),
-
“name” , containsInAnyOrder( “Leo” , “Basil” )
-
);
-
} }
Quarkus测试要求应用程序正在运行。 通过使用CDI @Alternate
bean定义,可以替换测试中的选定bean。 备用bean必须放置在src/test/java
。
注意:由于有了配置文件支持,您可以使用单独的数据库容器轻松配置test
配置文件的数据源。 请参阅测试数据源属性 。
另请参阅: https : //quarkus.io/guides/getting-started-testing
打包并运行应用程序
该应用程序可以打包为./mvnw package
。
它在/target
目录中生成可执行文件quarkus-petclinic-api-1.0.0-runner.jar
文件,并将依赖项复制到target/lib
目录中。
[INFO] [io.quarkus.deployment.pkg.steps.JarResultBuildStep] Building thin jar: /Users/rafal.borowiec/Projects/quarkus/quarkus-petclinic-api/target/quarkus-petclinic-api- 1.0 . 0 -runner.jar [INFO] [io.quarkus.deployment.QuarkusAugmentor] Quarkus augmentation completed in 1888ms [INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESS [INFO] ------------------------------------------------------------------------ [INFO] Total time: 15.868 s [INFO] Finished at: 2020 - 02 -23T19: 18 : 25 + 01 : 00 [INFO] ------------------------------------------------------------------------
现在可以使用java -jar target/quarkus-petclinic-api-1.0.0-runner.jar
运行该应用程序。
2020 - 02 - 23 19 : 19 : 10 , 169 INFO [io.quarkus] (main) quarkus-petclinic-api 1.0 . 0 (running on Quarkus 1.2 . 1 .Final) started in 2 .011s. Listening on: http: .011s. Listening on: http: //0.0.0.0:8080 .011s. Listening on: http: //0.0.0.0:8080 2020 - 02 - 23 19 : 19 : 10 , 171 INFO [io.quarkus] (main) Profile prod activated. 2020 - 02 - 23 19 : 19 : 10 , 171 INFO [io.quarkus] (main) Installed features: [agroal, cdi, flyway, hibernate-orm, hibernate-orm-panache, hibernate-validator, jdbc-postgresql, narayana-jta, rest-client, resteasy, resteasy-jackson, smallrye-openapi]
注意: uber-jar可以与./mvnw clean package -DskipTests=true -Dquarkus.package.uber-jar=true
一起打包。
创建一个以JVM模式运行应用程序的Docker容器
$ ./mvnw clean package $ docker build -f src/main/docker/Dockerfile.jvm -t quarkus/petclinic-api-jvm . Successfully built 1a5d963fedfa Successfully tagged quarkus/petclinic-api-jvm:latest
使用链接运行容器,执行Postgres数据库容器,并使用环境变量覆盖数据源url:
$ docker run -i --rm -p 8080 : 8080 --link petclinic-db -e QUARKUS_DATASOURCE_URL= 'jdbc:postgresql://petclinic-db/petclinic' quarkus/petclinic-api-jvm 2020 - 02 - 23 20 : 39 : 18 , 949 INFO [io.quarkus] (main) quarkus-petclinic-api 1.0 . 0 (running on Quarkus 1.2 . 1 .Final) started in 3 .475s. Listening on: http: .475s. Listening on: http: //0.0.0.0:8080 .475s. Listening on: http: //0.0.0.0:8080 2020 - 02 - 23 20 : 39 : 18 , 949 INFO [io.quarkus] (main) Profile prod activated. 2020 - 02 - 23 20 : 39 : 18 , 949 INFO [io.quarkus] (main) Installed features: [agroal, cdi, flyway, hibernate-orm, hibernate-orm-panache, hibernate-validator, jdbc-postgresql, narayana-jta, rest-client, resteasy, resteasy-jackson, smallrye-openapi
注意: petclinic-db
是在此处创建的Postgres容器的名称: Prod database 。 我们还需要传递数据源URL。 阅读有关在运行时覆盖配置属性的更多信息:在运行时覆盖属性
创建本机可执行文件
您可以使用以下命令创建本机可执行文件:
$ ./mvnw package -Pnative [INFO] [io.quarkus.deployment.pkg.steps.NativeImageBuildStep] Building image from /Users/rafal.borowiec/Projects/quarkus/quarkus-petclinic-api/target/quarkus-petclinic-api- 1.0 [INFO] [io.quarkus.deployment.pkg.steps.NativeImageBuildStep] Building native image from /Users/rafal.borowiec/Projects/quarkus/quarkus-petclinic-api/target/quarkus-petclinic-api- . 0 - native -image-source-jar/quarkus-petclinic-api- 1.0 . 0 -runner.jar ... [quarkus-petclinic-api- 1.0 . 0 -runner: 50503 ] (typeflow): 72 , 535.72 ms [quarkus-petclinic-api- 1.0 . 0 -runner: 50503 ] (objects): 49 , 325.68 ms [quarkus-petclinic-api- 1.0 . 0 -runner: 50503 ] (features): 3 , 115.04 ms [quarkus-petclinic-api- 1.0 . 0 -runner: 50503 ] analysis: 135 , 220.10 ms [quarkus-petclinic-api- 1.0 . 0 -runner: 50503 ] (clinit): 1 , 966.77 ms [quarkus-petclinic-api- 1.0 . 0 -runner: 50503 ] universe: 6 , 919.51 ms [quarkus-petclinic-api- 1.0 . 0 -runner: 50503 ] (parse): 13 , 679.33 ms [quarkus-petclinic-api- 1.0 . 0 -runner: 50503 ] (inline): 18 , 193.40 ms [quarkus-petclinic-api- 1.0 . 0 -runner: 50503 ] (compile): 70 , 849.75 ms [quarkus-petclinic-api- 1.0 . 0 -runner: 50503 ] compile: 111 , 062.75 ms [quarkus-petclinic-api- 1.0 . 0 -runner: 50503 ] image: 8 , 843.46 ms [quarkus-petclinic-api- 1.0 . 0 -runner: 50503 ] write: 1 , 789.58 ms [quarkus-petclinic-api- 1.0 . 0 -runner: 50503 ] [total]: 282 , 727.03 ms [INFO] [io.quarkus.deployment.QuarkusAugmentor] Quarkus augmentation completed in 287304ms [INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESS [INFO] ------------------------------------------------------------------------ [INFO] Total time: 04 : 58 min [INFO] Finished at: 2020 - 02 -23T19: 25 : 10 + 01 : 00 [INFO] ------------------------------------------------------------------------
创建本机可执行文件的过程需要花费一些时间,但是值得等待它完成以查看应用程序的启动时间:
$ ./target/quarkus-petclinic-api- 1.0 . 0 -runner 2020 - 02 - 23 19 : 26 : 03 , 959 INFO [io.quarkus] (main) quarkus-petclinic-api 1.0 . 0 (running on Quarkus 1.2 . 1 .Final) started in 0 .066s. Listening on: http: .066s. Listening on: http: //0.0.0.0:8080 .066s. Listening on: http: //0.0.0.0:8080 2020 - 02 - 23 19 : 26 : 03 , 959 INFO [io.quarkus] (main) Profile prod activated. 2020 - 02 - 23 19 : 26 : 03 , 959 INFO [io.quarkus] (main) Installed features: [agroal, cdi, flyway, hibernate-orm, hibernate-orm-panache, hibernate-validator, jdbc-postgresql, narayana-jta, rest-client, resteasy, resteasy-jackson, smallrye-openapi]
本机可执行文件启动为0.67秒,而JVM版本为2秒。
创建一个以纯模式运行应用程序的Docker容器
默认情况下,本机可执行文件以操作系统支持的格式创建。 由于容器使用的可执行文件格式可能与操作系统生成的格式不同,因此Maven构建可以从容器内部生成可执行文件:
$ ./mvnw package -Pnative -Dquarkus. native .container-build= true
要调整构建器映像的版本,您需要设置quarkus.native.builder-image
属性:
$ ./mvnw clean package -Pnative -DskipTests= true -Dquarkus. native .container-build= true -Dquarkus. native .builder-image=quay.io/quarkus/ubi-quarkus- native -image: 20.0 . 0 -java11
现在,构建并运行容器:
$ docker build -f src/main/docker/Dockerfile. native -t quarkus/petclinic-api . $ docker run -i --rm -p 8080 : 8080 quarkus/petclinic-api
注意:有关构建本机可执行文件的更多信息,请参见Quarkus文档: https ://quarkus.io/guides/building-native-image
源代码
可以在Github上找到本文的源代码: https : //github.com/kolorobot/quarkus-petclinic-api
翻译自: https://www.javacodegeeks.com/2020/02/getting-started-with-quarkus.html
quarkus