Quarkus - 用 Maven 构建应用

创建项目
处理扩展
开发模式
- Remote Development Mode
- 配置开发模式
调试
导入到 IDE
Logging Quarkus application build classpath tree
Building a native executable
- Build a container friendly executable
Maven configuration
- Uber-Jar Creation
Configuring the Project Output
- Custom test configuration profile in JVM mode

创建项目

使用 Maven ，可以用它搭建项目：

mvn io.quarkus:quarkus-maven-plugin:1.3.1.Final:create \
    -DprojectGroupId=my-groupId \
    -DprojectArtifactId=my-artifactId \
    -DprojectVersion=my-version \
    -DclassName="org.my.group.MyResource"

如果只运行 mvn io.quarkus:quarkus-maven-plugin:1.3.1.Final:create ，Maven 插件会需要你输入一些信息。你可以给 Maven 命令传 -B 参数禁用交互模式（会使用默认值）。

下表中列出可以传给 create 命令的属性:

属性默认值说明

属性	默认值	说明
`projectGroupId`	`org.acme.sample`	The group id of the created project
`projectArtifactId`	mandatory	The artifact id of the created project. Not passing it triggers the interactive mode.
`projectVersion`	`1.0-SNAPSHOT`	The version of the created project
`platformGroupId`	`io.quarkus`	The group id of the target platform. Given that all the existing platforms are coming from `io.quarkus` this one won’t practically be used explicitly. But it’s still an option.
`platformArtifactId`	`quarkus-universe-bom`	The artifact id of the target platform BOM. It should be `quarkus-bom` in order to use the locally built Quarkus.
`platformVersion`	If it’s not specified, the latest one will be resolved.	The version of the platform you want the project to use. It can also accept a version range, in which case the latest from the specified range will be used.
`className`	Not created if omitted	The fully qualified name of the generated resource
`path`	`/hello`	The resource path, only relevant if `className` is set.
`extensions`	[]	The list of extensions to add to the project (comma-separated)

projectGroupId

org.acme.sample

The group id of the created project

projectArtifactId

mandatory

The artifact id of the created project. Not passing it triggers the interactive mode.

projectVersion

1.0-SNAPSHOT

The version of the created project

platformGroupId

io.quarkus

The group id of the target platform. Given that all the existing platforms are coming from io.quarkus this one won’t practically be used explicitly. But it’s still an option.

platformArtifactId

quarkus-universe-bom

The artifact id of the target platform BOM. It should be quarkus-bom in order to use the locally built Quarkus.

platformVersion

If it’s not specified, the latest one will be resolved.

The version of the platform you want the project to use. It can also accept a version range, in which case the latest from the specified range will be used.

className

Not created if omitted

The fully qualified name of the generated resource

path

/hello

The resource path, only relevant if className is set.

extensions

[]

The list of extensions to add to the project (comma-separated)

默认，此命令会找 quarkus-universe-bom 最新版本（触发指定了）。但是如果你离线运行，它会在你本机找可用的，如果本地无可用的 quarkus-universe-bom（满足当前版本到2.0之间）会使用 quarkus-bom 对应的版本（与插件版本对应）

如果你选择生成 REST 资源（使用了 className 属性）, 接口暴露在 : http://localhost:8080/$path. 如果使用默认 path 网址是: http://localhost:8080/hello.

项目在 artifactId 后指定目录生成。如果目录已经存在，生成失败。

有一组 Dockerfiles 生成在 src/main/docker, 包含原生模式及 jvm 模式。构建镜像及运行容器的介绍在这些 Dockerfiles 里。

处理扩展

在 Quarkus 项目中，通过以下方式获知所有可用扩展

./mvnw quarkus:list-extensions

通过启用扩展：

./mvnw quarkus:add-extension -Dextensions="hibernate-validator"

多个扩展用逗号分隔。

扩展名是扩展的 GAV 名: 如 io.quarkus:quarkus-agroal. 但是可以传递名称的一部分，Quarkus 会尽量找到正确的扩展。如, agroal, Agroal 或 agro 会展开成 io.quarkus:quarkus-agroal. 如果未找到扩展，或者匹配多个扩展名，则命令结果中将显示红色的 ❌ 标记

$ ./mvnw quarkus:add-extensions -Dextensions=jdbc,agroal,non-exist-ent
[...]
❌ Multiple extensions matching 'jdbc'
     * io.quarkus:quarkus-jdbc-h2
     * io.quarkus:quarkus-jdbc-mariadb
     * io.quarkus:quarkus-jdbc-postgresql
     Be more specific e.g using the exact name or the full gav.
✅ Adding extension io.quarkus:quarkus-agroal
❌ Cannot find a dependency matching 'non-exist-ent', maybe a typo?
[...]

您可以安装所有匹配通配名的扩展

./mvnw quarkus:add-extension -Dextensions="hibernate-*"

开发模式

Quarkus 内置开发模式。使用下列命令运行：

./mvnw compile quarkus:dev

然后修改源代码、资源及配置。这些修改会自动反映到运行中的应用。修改立即反映出来，对于跨UI和数据库进行开发非常有用。

quarkus:dev 通过后台编译启用热部署，这意味着当您修改Java文件或资源文件并刷新浏览器时，这些更改将自动生效。这对于资源文件（如配置属性文件）也适用。刷新浏览器的操作将触发对工作区的扫描，并且如果检测到任何更改，将编译Java文件，并重新部署应用程序，然后重新部署的应用程序将为您的请求提供服务。如果编译或部署有任何问题，则会显示错误页面。

按 CTRL+C 停止应用程序。

Remote Development Mode

It is possible to use development mode remotely, so that you can run Quarkus in a container environment (such as Openshift) and have changes made to your local files become immediately visible.

This allows you to develop in the same environment you will actually run your app in, and with access to the same services.

Do not use this in production. This should only be used in a development environment. You should not run production application in dev mode.

To do this you must have the quarkus-undertow-websockets extension installed:

./mvnw quarkus:add-extension -Dextensions="undertow-websockets"

You must also have the following config properties set:

quarkus.live-reload.password
quarkus.live-reload.url

These can be set via application.properties, or any other way (e.g. system properties, environment vars etc). The password must be set on both the local and remote processes, while the url only needs to be set on the local host.

Start Quarkus in dev mode on the remote host. Now you need to connect your local agent to the remote host:

./mvnw quarkus:remote-dev -Dquarkus.live-reload.url=http://my-remote-host:8080

Now every time you refresh the browser you should see any changes you have made locally immediately visible in the remote app.

配置开发模式

默认 Maven 插件会从 maven-compiler-plugin 选择编译参数传给 javac .

如果想定制开发模式中的编译参数，需要在 plugin 中添加 configuration 然后在 compilerArgs 里设置想要的参数，就像 maven-compiler-plugin 中配置一样。还可以设置 source, target 及 jvmArgs 。如：传 --enable-preview 给 JVM 及 javac :

<plugin>
  <groupId>io.quarkus</groupId>
  <artifactId>quarkus-maven-plugin</artifactId>
  <version>${quarkus.version}</version>

  <configuration>
    <source>${maven.compiler.source}</source>
    <target>${maven.compiler.target}</target>
    <compilerArgs>
      <arg>--enable-preview</arg>
    </compilerArgs>
    <jvmArgs>--enable-preview</jvmArgs>
  </configuration>

  ...
</plugin>

调试

开发模式 Quarkus 默认启用了调试，监听端口 5005 不挂起 JVM (listening to port 5005 without suspending the JVM.)

可以通过系统属性 debug 调整：

false - JVM将以禁用的调试模式启动。
true - JVM在调试模式下启动，并且将在端口上侦听 5005
client - JVM将以客户端模式启动并尝试连接到 localhost:5005
{port} - JVM在调试模式下启动，并且侦听端口 {port}

在调试模式下启动时，可以使用附加的系统属性 suspend 来挂起 JVM, suspend 支持以下值:

y or true - 调试模式JVM启动时挂起
n or false - 不挂起

可以用 ./mvnw compile quarkus:dev -Ddebug=true (简写成 ./mvnw compile quarkus:dev -Ddebug ) 将 Quarkus 应用以挂起状态的调试模式启动。

然后连接调试器到 localhost:5005.

导入到 IDE

Once you have a project generated, you can import it in your favorite IDE. The only requirement is the ability to import a Maven project.

Eclipse

Eclipse 中, 点:

File → Import.
向导中, 选择: Maven → Existing Maven Project.
下一屏, 选择项目根目录. 4。再下一屏列出找到的模块；选择生成的项目并点 Finish.

搞定！

In a separated terminal, run ./mvnw compile quarkus:dev, and enjoy a highly productive environment. 在另外终端，运行 n ./mvnw compile quarkus:dev ，Enjoy!。

IntelliJ

IntelliJ 中 :

选择 File → New → Project From Existing Sources… ，或者在欢迎页中选择 Import project.
选择项目根目录
选择 Import project from external model 和 Maven
下几步 (如果需要检查下选项)
最后点完成

打开终端窗口或嵌入式终端，运行 ./mvnw compile quarkus:dev ，Enjoy!。

Apache NetBeans

In NetBeans:

Select File → Open Project
Select the project root
Click on Open Project

In a separated terminal or the embedded terminal, go to the project root and run ./mvnw compile quarkus:dev. Enjoy!

Visual Studio Code

Open the project directory in VS Code. If you have installed the Java Extension Pack (grouping a set of Java extensions), the project is loaded as a Maven project.

Logging Quarkus application build classpath tree

Usually, dependencies of an application (which is a Maven project) could be displayed using mvn dependency:tree command. In case of a Quarkus application, however, this command will list only the runtime dependencies of the application. Given that the Quarkus build process adds deployment dependencies of the extensions used in the application to the original application classpath, it could be useful to know which dependencies and which versions end up on the build classpath. Luckily, the quarkus-bootstrap Maven plugin includes the build-tree goal which displays the build dependency tree for the application.

To be able to use it, the following plugin configuration has to be added to the pom.xml:

            <plugin>
                <groupId>io.quarkus</groupId>
                <artifactId>quarkus-bootstrap-maven-plugin</artifactId>
                <version>${quarkus.version}</version>
            </plugin>

Now you should be able to execute ./mvnw quarkus-bootstrap:build-tree on your project and see something like:

[INFO] --- quarkus-bootstrap-maven-plugin:1.3.1.Final:build-tree (default-cli) @ getting-started ---
[INFO] org.acme:getting-started:jar:1.0-SNAPSHOT
[INFO] └─ io.quarkus:quarkus-resteasy-deployment:jar:1.3.1.Final (compile)
[INFO]    ├─ io.quarkus:quarkus-resteasy-server-common-deployment:jar:1.3.1.Final (compile)
[INFO]    │  ├─ io.quarkus:quarkus-core-deployment:jar:1.3.1.Final (compile)
[INFO]    │  │  ├─ commons-beanutils:commons-beanutils:jar:1.9.3 (compile)
[INFO]    │  │  │  ├─ commons-logging:commons-logging:jar:1.2 (compile)
[INFO]    │  │  │  └─ commons-collections:commons-collections:jar:3.2.2 (compile)
...

Building a native executable

Native executables make Quarkus applications ideal for containers and serverless workloads.

Make sure to have GRAALVM_HOME configured and pointing to GraalVM version 19.3.1. Verify that your pom.xml has the proper native profile (see Maven configuration).

Create a native executable using: ./mvnw package -Pnative. A native executable will be present in target/.

To run Integration Tests on the native executable, make sure to have the proper Maven plugin configured (see Maven configuration) and launch the verify goal.

./mvnw verify -Pnative
...
[quarkus-quickstart-runner:50955]     universe:     391.96 ms
[quarkus-quickstart-runner:50955]      (parse):     904.37 ms
[quarkus-quickstart-runner:50955]     (inline):   1,143.32 ms
[quarkus-quickstart-runner:50955]    (compile):   6,228.44 ms
[quarkus-quickstart-runner:50955]      compile:   9,130.58 ms
[quarkus-quickstart-runner:50955]        image:   2,101.42 ms
[quarkus-quickstart-runner:50955]        write:     803.18 ms
[quarkus-quickstart-runner:50955]      [total]:  33,520.15 ms
[INFO]
[INFO] --- maven-failsafe-plugin:2.22.0:integration-test (default) @ quarkus-quickstart-native ---
[INFO]
[INFO] -------------------------------------------------------
[INFO]  T E S T S
[INFO] -------------------------------------------------------
[INFO] Running org.acme.quickstart.GreetingResourceIT
Executing [/Users/starksm/Dev/JBoss/Quarkus/starksm64-quarkus-quickstarts/getting-started-native/target/quarkus-quickstart-runner, -Dquarkus.http.port=8081, -Dtest.url=http://localhost:8081, -Dquarkus.log.file.path=target/quarkus.log]
2019-02-28 16:52:42,020 INFO  [io.quarkus] (main) Quarkus started in 0.007s. Listening on: http://localhost:8080
2019-02-28 16:52:42,021 INFO  [io.quarkus] (main) Installed features: [cdi, resteasy]
[INFO] Tests run: 2, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 1.081 s - in org.acme.quickstart.GreetingResourceIT
[INFO]
[INFO] Results:
[INFO]
[INFO] Tests run: 2, Failures: 0, Errors: 0, Skipped: 0

...

Build a container friendly executable

The native executable will be specific to your operating system. To create an executable that will run in a container, use the following:

./mvnw package -Dnative -Dquarkus.native.container-build=true

The produced executable will be a 64 bit Linux executable, so depending on your operating system it may no longer be runnable. However, it’s not an issue as we are going to copy it to a Docker container. Note that in this case the build itself runs in a Docker container too, so you don’t need to have GraalVM installed locally.

By default, the native executable will be generated using the quay.io/quarkus/ubi-quarkus-native-image:19.3.1-java11 Docker image.

If you want to build a native executable with a different Docker image (for instance to use a different GraalVM version), use the -Dquarkus.native.builder-image=<image name> build argument.

The list of the available Docker images can be found on quay.io. Be aware that a given Quarkus version might not be compatible with all the images available.

You can follow the Build a native executable guide as well as Deploying Application to Kubernetes and OpenShift for more information.

Maven configuration

If you have not used project scaffolding, add the following elements in your pom.xml

<dependencyManagement>
    <dependencies>
        <dependency> (1)
            <groupId>io.quarkus</groupId>
            <artifactId>quarkus-bom</artifactId>
            <version>${quarkus.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<build>
    <plugins>
        <plugin> (2)
            <groupId>io.quarkus</groupId>
            <artifactId>quarkus-maven-plugin</artifactId>
            <version>${quarkus.version}</version>
            <executions>
                <execution>
                    <goals>
                        <goal>build</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

<profiles>
    <profile> (3)
        <id>native</id>
        <properties> (4)
            <quarkus.package.type>native</quarkus.package.type>
        </properties>
        <build>
            <plugins>
                <plugin> (5)
                    <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>
                                <systemProperties>
                                    <native.image.path>${project.build.directory}/${project.build.finalName}-runner</native.image.path>
                                </systemProperties>
                            </configuration>
                        </execution>
                    </executions>
                </plugin>
            </plugins>
        </build>
    </profile>
</profiles>

1	Optionally use a BOM file to omit the version of the different Quarkus dependencies.
2	Use the Quarkus Maven plugin that will hook into the build process.
3	Use a specific `native` profile for native executable building.
4	Enable the `native` package type. The build will therefore produce a native executable.
5	If you want to test your native executable with Integration Tests, add the following plugin configuration. Test names `*IT` and annotated `@NativeImageTest` will be run against the native executable. See the Native executable guide for more info.

Uber-Jar Creation

Quarkus Maven plugin supports the generation of Uber-Jars by specifying a quarkus.package.uber-jar=true configuration option in your application.properties.

The original jar will still be present in the target directory but it will be renamed to contain the .original suffix.

When building an Uber-Jar you can specify entries that you want to exclude from the generated jar by using the quarkus.package.ignored-entries configuration option, this takes a comma seperated list of entries to ignore.

Uber-Jar creation by default excludes signature files that might be present in the dependencies of the application.

Uber-Jar’s final name is configurable via a Maven’s build settings finalName option.

Configuring the Project Output

There are a several configuration options that will define what the output of your project build will be. These are provided in application.properties the same as any other config property.

The properties are shown below:

Configuration property fixed at build time - All other configuration properties are overridable at runtime

Configuration property	Type	Default
`quarkus.package.type` The requested output type. The default built in types are jar and native	string	`jar`
`quarkus.package.uber-jar` If the java runner should be packed as an uberjar	boolean	`false`
`quarkus.package.manifest.add-implementation-entries` If the Implementation information should be included in the runner jar’s MANIFEST.MF.	boolean	`true`
`quarkus.package.main-class` The entry point of the application. In most cases this should not be modified.	string	`io.quarkus.runner.GeneratedMain`
`quarkus.package.user-configured-ignored-entries` Files that should not be copied to the output artifact	list of string
`quarkus.package.runner-suffix` The suffix that is applied to the runner jar and native images	string	`-runner`
`quarkus.package.output-directory` The output folder in which to place the output, this is resolved relative to the build systems target directory.	string
`quarkus.package.output-name` The name of the final artifact	string

Configuration property

Type

Default

quarkus.package.type

The requested output type. The default built in types are jar and native

string

jar

quarkus.package.uber-jar

If the java runner should be packed as an uberjar

boolean

false

quarkus.package.manifest.add-implementation-entries

If the Implementation information should be included in the runner jar’s MANIFEST.MF.

boolean

true

quarkus.package.main-class

The entry point of the application. In most cases this should not be modified.

string

io.quarkus.runner.GeneratedMain

quarkus.package.user-configured-ignored-entries

Files that should not be copied to the output artifact

list of string

quarkus.package.runner-suffix

The suffix that is applied to the runner jar and native images

string

-runner

quarkus.package.output-directory

The output folder in which to place the output, this is resolved relative to the build systems target directory.

string

quarkus.package.output-name

The name of the final artifact

string

Custom test configuration profile in JVM mode

By default, Quarkus tests in JVM mode are run using the test configuration profile. If you are not familiar with Quarkus configuration profiles, everything you need to know is explained in the Configuration Profiles Documentation.

It is however possible to use a custom configuration profile for your tests with the Maven Surefire and Maven Failsafe configurations shown below. This can be useful if you need for example to run some tests using a specific database which is not your default testing database.

<project>
  [...]
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-surefire-plugin</artifactId>
        <version>${surefire-plugin.version}</version>
        <configuration>
          <systemPropertyVariables>
            <quarkus.test.profile>foo</quarkus.test.profile> (1)
            <buildDirectory>${project.build.directory}</buildDirectory>
            [...]
          </systemPropertyVariables>
        </configuration>
      </plugin>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-failsafe-plugin</artifactId>
        <version>${failsafe-plugin.version}</version>
        <configuration>
          <systemPropertyVariables>
            <quarkus.test.profile>foo</quarkus.test.profile> (1)
            <buildDirectory>${project.build.directory}</buildDirectory>
            [...]
          </systemPropertyVariables>
        </configuration>
      </plugin>
    </plugins>
  </build>
  [...]
</project>

1	The `foo` configuration profile will be used to run the tests.

It is not possible to use a custom test configuration profile in native mode for now. Native tests are always run using the prod profile.