Quarkus and Maven

使用 Maven 创建新项目、添加或移除扩展、启动开发模式、调试你的应用程序，并将你的应用程序构建到 jar、本机可执行文件或容器友好型可执行文件中。使用 Maven 项目元数据，将你的项目导入到你最喜欢的 IDE 中。

Use Maven to create a new project, add or remove extensions, launch development mode, debug your application, and build your application into a jar, native executable, or container-friendly executable. Import your project into your favorite IDE using Maven project metadata.

Creating a new project

你可以使用以下命令脚手架一个新的 Maven 项目：

You can scaffold a new Maven project with:

Unresolved directive in maven-tooling.adoc - include::{includes}/devtools/create-app.adoc[]

如果你正在使用 CLI，你可以使用以下命令获取可用选项列表：

If you are using the CLI, you can get the list of available options with:

quarkus create app --help

如果你正在使用 Maven 命令，下表列出了你可以传递给 create 命令的属性：

If you are using the Maven command, the following table lists the attributes you can pass to the create command:

Attribute Default Value Description

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.0-SNAPSHOT

The version of the created project

platformGroupId

{quarkus-platform-groupid}

The group id of the target platform.

platformArtifactId

quarkus-bom

The artifact id of the target platform BOM.

platformVersion

The version currently recommended by the Quarkus Extension Registry

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.

javaVersion

17

The version of Java you want the project to use.

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)

quarkusRegistryClient

true

Whether Quarkus should use the online registry to resolve extension catalogs. If this is set to false, the extension catalog will be narrowed to the defined (or default) platform BOM.

默认情况下，该命令将以 {quarkus-platform-groupid}:quarkus-bom:{quarkus-version} 平台版本为对象（除非指定所需平台版本的坐标）。

By default, the command will target the {quarkus-platform-groupid}:quarkus-bom:{quarkus-version} platform release (unless the coordinates of the desired platform release have been specified).

该项目在一个以所传递 artifactId 命名为目录中生成。如果该目录已经存在，则生成将失败。

The project is generated in a directory named after the passed artifactId. If the directory already exists, the generation fails.

还会在 src/main/docker 中生成一对适用于原生模式和 jvm 模式的 Dockerfile。在这些 Dockerfile 中编写有构建映像和运行容器的说明。

A pair of Dockerfiles for native and jvm mode are also generated in src/main/docker. Instructions to build the image and run the container are written in those Dockerfiles.

Dealing with extensions

在 Quarkus 项目内部，你可以使用以下命令获取可用扩展的列表：

From inside a Quarkus project, you can obtain a list of the available extensions with:

Unresolved directive in maven-tooling.adoc - include::{includes}/devtools/extension-list.adoc[]

你可以使用以下命令添加一个扩展：

You can add an extension using:

Unresolved directive in maven-tooling.adoc - include::{includes}/devtools/extension-add.adoc[]

扩展使用逗号分隔的列表传递。

Extensions are passed using a comma-separated list.

扩展名是扩展的 GAV 名称：例如，io.quarkus:quarkus-agroal。但是，你可以传递一个部分名称，Quarkus 将尽力寻找正确的扩展。例如，agroal、Agroal`或 `agro 将扩展为 io.quarkus:quarkus-agroal。如果没有找到扩展或有多个扩展匹配，你将会在命令结果中看到一个红色的对号标记 ❌。

The extension name is the GAV name of the extension: e.g., io.quarkus:quarkus-agroal. However, you can pass a partial name, and Quarkus will do its best to find the right extension. For example, agroal, Agroal, or agro will expand to io.quarkus:quarkus-agroal. If no extension is found or more than one extension matches, you will see a red check mark ❌ in the command result.

$ ./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?
[...]

你可以安装与全局模式匹配的所有扩展：

You can install all extensions which match a globbing pattern :

Unresolved directive in maven-tooling.adoc - include::{includes}/devtools/extension-add.adoc[]

Configuring javac options

Quarkus Maven 插件使用 javac，并且默认情况下它会选择编译器标志从 maven-compiler-plugin 传递到 javac。

The Quarkus Maven plugin makes use of javac, and by default it picks up compiler flags to pass to javac from maven-compiler-plugin.

如果您需要自定义插件使用的编译器标志（如 development mode）中），请将 configuration 部分添加到 plugin 块中，并设置 compilerArgs 属性，就像在配置 maven-compiler-plugin 时一样。您还可以设置 source、target 和 jvmArgs。例如，要将 --enable-preview 传递给 JVM 和 javac：

If you need to customize the compiler flags used by the plugin, like in dev-mode, add a configuration section to the plugin block and set the compilerArgs property just as you would when configuring maven-compiler-plugin. You can also set source, target, and jvmArgs. For example, to pass --enable-preview to both the JVM and javac:

<plugin>
  <groupId>${quarkus.platform.group-id}</groupId>
  <artifactId>quarkus-maven-plugin</artifactId>
  <version>${quarkus.platform.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 Maven 插件本身在 Maven 启动的 JVM 中运行，并且因为一些（罕见）Quarkus 扩展需要在构建过程中加载应用程序类，所以可能需要将相同的标志传递给运行 Maven 的 JVM。

Because the Quarkus Maven plugin itself runs in the JVM started by Maven, and because some (rare) Quarkus extensions need to load application classes during the build, it may be necessary to pass the same flags to the JVM running Maven.

为此，您可以使用 MAVEN_OPTS：

To that end, you can use MAVEN_OPTS: Unresolved directive in maven-tooling.adoc - include::{includes}/devtools/maven-opts.adoc[]

Alternatively，你可以简单地在项目根目录中创建文件 .mvn/jvm.config：Maven 将选择在该文件中放入的任何选项，而无需设置 MAVEN_OPTS。

Alternatively, you can simply create the file .mvn/jvm.config at the root of your project: and any options you put in that file will be picked up by Maven, without having to set MAVEN_OPTS.

Development mode

Quarkus 具有内置开发模式。使用以下命令运行应用程序：

Quarkus comes with a built-in development mode. Run your application with:

Unresolved directive in maven-tooling.adoc - include::{includes}/devtools/dev.adoc[]

然后，你可以更新应用程序源、资源和配置。这些更改将自动反映在正在运行的应用程序中。这非常适合进行跨 UI 和数据库的开发，因为你可以立即看到反映的更改。

You can then update the application sources, resources and configurations. The changes are automatically reflected in your running application. This is great to do development spanning UI and database as you see changes reflected immediately.

开发模式通过后台编译启用了热部署，这意味着当修改 Java 文件或资源文件并刷新浏览器时，这些更改将自动生效。这也适用于资源文件，如配置属性文件。刷新浏览器的行为将触发对工作区的扫描，如果检测到任何更改，将编译 Java 文件并重新部署应用程序，然后重新部署的应用程序会处理你的请求。如果编译或部署有任何问题，错误页面将通知你。

Dev mode enables hot deployment with background compilation, which means that when you modify your Java files or your resource files and refresh your browser these changes will automatically take effect. This works too for resource files like the configuration property file. The act of refreshing the browser triggers a scan of the workspace, and if any changes are detected the Java files are compiled, and the application is redeployed, then your request is serviced by the redeployed application. If there are any issues with compilation or deployment an error page will let you know.

按 CTRL+C 停止应用程序。

Hit CTRL+C to stop the application.

默认情况下，quarkus:dev 将调试主机设置为 localhost（出于安全原因）。如果你需要更改此设置，例如启用所有主机的调试，则可以使用 -DdebugHost 选项，如下所示：

By default, quarkus:dev sets the debug host to localhost (for security reasons). If you need to change this, for example to enable debugging on all hosts, you can use the -DdebugHost option like so:

include::{includes}/devtools/dev-parameters.adoc[]:!dev-additional-parameters:

Unresolved directive in maven-tooling.adoc - include::{includes}/devtools/dev-parameters.adoc[] :!dev-additional-parameters:

Remote Development Mode

可以使用远程开发模式，以便在容器环境（如 OpenShift）中运行 Quarkus，并使对本地文件进行的更改立即可见。

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.

为此，你必须使用 mutable-jar 格式构建一个可变应用程序。在 application.properties 中设置以下属性：

To do this you must build a mutable application, using the mutable-jar format. Set the following properties in application.properties:

quarkus.package.jar.type=mutable-jar 1
quarkus.live-reload.password=changeit 2
quarkus.live-reload.url=http://my.cluster.host.com:8080 3
1 This tells Quarkus to use the mutable-jar format. Mutable applications also include the deployment time parts of Quarkus, so they take up a bit more disk space. If run normally they start just as fast and use the same memory as an immutable application, however they can also be started in dev mode.
2 The password that is used to secure communication between the remote side and the local side.
3 The URL that your app is going to be running in dev mode at. This is only needed on the local side, so you may want to leave it out of the properties file and specify it as a system property on the command line.

然后，以构建正常 Quarkus jar 的相同方式构建 mutable-jar，即通过发布：

The mutable-jar is then built in the same way that a regular Quarkus jar is built, i.e. by issuing:

Unresolved directive in maven-tooling.adoc - include::{includes}/devtools/build.adoc[]

在你启动远程主机上的 Quarkus 之前，设置环境变量 QUARKUS_LAUNCH_DEVMODE=true。如果你在裸机上，你可以通过 export QUARKUS_LAUNCH_DEVMODE=true 命令进行设置，然后使用正确的 java -jar …​ 命令运行应用程序来运行应用程序。

Before you start Quarkus on the remote host set the environment variable QUARKUS_LAUNCH_DEVMODE=true. If you are on bare metal you can set it via the export QUARKUS_LAUNCH_DEVMODE=true command and then run the application with the proper java -jar …​ command to run the application.

如果你计划通过 Docker 运行应用程序，那么你需要向 docker run 命令中添加 -e QUARKUS_LAUNCH_DEVMODE=true。当应用程序启动时，你现在应该在日志中看到以下行：Profile dev activated. Live Coding activated。你还需要通过在 Dockerfile 中向 COPY 命令后面添加 RUN chmod o+rw -R /deployments 来向应用程序授予更新部署资源的权限。出于安全原因，不应将此选项添加到生产 Dockerfile 中。

If you plan on running the application via Docker, then you’ll need to add -e QUARKUS_LAUNCH_DEVMODE=true to the docker run command. When the application starts you should now see the following line in the logs: Profile dev activated. Live Coding activated. You will also need to give the application the rights to update the deployment resources by adding RUN chmod o+rw -R /deployments after the COPY commands into your Dockerfile. For security reasons, this option should not be added to the production Dockerfile.

远程端无需包含 Maven 或任何其他开发工具。使用新 Quarkus 应用程序生成的法规 fast-jar Dockerfile 是你唯一需要的。如果你正在使用裸机启动 Quarkus runner jar，请不要尝试运行正常开发模式。

The remote side does not need to include Maven or any other development tools. The normal fast-jar Dockerfile that is generated with a new Quarkus application is all you need. If you are using bare metal launch the Quarkus runner jar, do not attempt to run normal dev mode.

现在你需要使用 remote-dev 命令将本地代理连接到远程主机：

Now you need to connect your local agent to the remote host, using the remote-dev command:

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

现在，每次刷新浏览器时，你都应该看到你在本地进行的任何更改都会立即在远程应用程序中显示。这是通过基于 HTTP 的长时间轮询传输完成的，它将通过 HTTP 调用同步本地工作空间和远程应用程序。

Now every time you refresh the browser you should see any changes you have made locally immediately visible in the remote app. This is done via an HTTP based long polling transport, that will synchronize your local workspace and the remote application via HTTP calls.

如果你不想使用 HTTP 功能，那么你可以简单运行 remote-dev 命令而不指定 URL。在此模式下，命令将持续重建本地应用程序，因此你可以使用外部工具（例如 odo 或 rsync）同步到远程应用程序。

If you do not want to use the HTTP feature then you can simply run the remote-dev command without specifying the URL. In this mode the command will continuously rebuild the local application, so you can use an external tool such as odo or rsync to sync to the remote application.

所有配置选项如下所示：

All the config options are shown below:

Unresolved directive in maven-tooling.adoc - include::{generated-dir}/config/quarkus-core_quarkus.live-reload.adoc[]

建议你在使用远程开发模式时使用 SSL，但即使你使用未加密连接，你的密码也不会直接通过网络发送。对于初始连接请求，密码会使用初始状态数据进行哈希处理，并且后续请求会使用服务器生成的随机会话 ID 和 POST 请求的任何正文内容、DELETE 请求的路径以及递增的计数器对它进行哈希处理，以防止重放攻击。

It is recommended you use SSL when using remote dev mode, however even if you are using an unencrypted connection your password is never sent directly over the wire. For the initial connection request the password is hashed with the initial state data, and subsequent requests hash it with a random session id generated by the server and any body contents for POST requests, and the path for DELETE requests, as well as an incrementing counter to prevent replay attacks.

Debugging

在开发模式下，Quarkus 默认以启用调试模式启动，侦听端口 5005，且不会挂起 JVM。

In development mode, Quarkus starts by default with debug mode enabled, listening to port 5005 without suspending the JVM.

可以通过向 debug 系统属性赋予以下值之一来改变此行为：

This behavior can be changed by giving the debug system property one of the following values:

  • false - the JVM will start with debug mode disabled

  • true - The JVM is started in debug mode and will be listening on port 5005

  • client - the JVM will start in client mode and attempt to connect to localhost:5005

  • {port} - The JVM is started in debug mode and will be listening on {port}

一个附加的系统属性 suspend 可用来在调试模式下启动时挂起 JVM。suspend 支持以下值：

An additional system property suspend can be used to suspend the JVM, when launched in debug mode. suspend supports the following values:

  • y or true - The debug mode JVM launch is suspended

  • n or false - The debug mode JVM is started without suspending

你还可以使用以下命令用一个挂起的 JVM 在调试模式下运行 Quarkus 应用程序：

You can also run a Quarkus application in debug mode with a suspended JVM using:

include::{includes}/devtools/dev-parameters.adoc[]:!dev-additional-parameters:

Unresolved directive in maven-tooling.adoc - include::{includes}/devtools/dev-parameters.adoc[] :!dev-additional-parameters:

然后，将你的调试器附加到 localhost:5005。

Then, attach your debugger to localhost:5005.

Import in your IDE

一旦您拥有一个 project generated，您便可以将其导入到您喜爱的 IDE 中。唯一的要求是可以导入 Maven 项目。

Once you have a project-creation, 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。在下一个屏幕中，选择项目的根位置。下一个屏幕列出了找到的模块；选择生成的项目并单击 Finish。完成！

In Eclipse, click on: File → Import. In the wizard, select: Maven → Existing Maven Project. On the next screen, select the root location of the project. The next screen list the found modules; select the generated project and click on Finish. Done!

在单独的终端中，运行：

In a separated terminal, run:

Unresolved directive in maven-tooling.adoc - include::{includes}/devtools/dev.adoc[]

并尽享高产出环境。

and enjoy a highly productive environment.

IntelliJ IDEA

在 IntelliJ IDEA 中：

In IntelliJ IDEA:

  1. From inside IntelliJ IDEA select File → New → Project From Existing Sources…​ or, if you are on the welcome dialog, select Import project.

  2. Select the project root

  3. Select Import project from external model and Maven

  4. Next a few times (review the different options if needed)

  5. On the last screen click on Finish

在单独的终端中或在嵌入式终端中，运行：

In a separated terminal or in the embedded terminal, run:

Unresolved directive in maven-tooling.adoc - include::{includes}/devtools/dev.adoc[]

享受！

Enjoy!

Apache NetBeans

在 NetBeans 中：

In NetBeans:

  1. Select File → Open Project

  2. Select the project root

  3. Click on Open Project

在单独的终端或嵌入式终端中，转到项目根目录并运行：

In a separated terminal or the embedded terminal, go to the project root and run:

Unresolved directive in maven-tooling.adoc - include::{includes}/devtools/dev.adoc[]

享受！

Enjoy!

Visual Studio Code

在 VS 代码中打开项目目录。如果您已安装 Java 扩展包（将一组 Java 扩展组合在一起），则此项目将加载为 Maven 项目。

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

通常，可以使用 mvn dependency:tree 命令显示应用程序（是 Maven 项目）的依赖项。但是，对于 Quarkus 应用程序，此命令将仅列出应用程序的运行时依赖项。由于 Quarkus 构建过程会将应用程序中使用扩展的部署依赖项添加到原始应用程序类路径中，因此了解哪些依赖项以及哪些版本最终出现在构建类路径上会很有用。幸运的是，quarkus Maven 插件包含 dependency-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 Maven plugin includes the dependency-tree goal which displays the build dependency tree for the application.

对您的项目执行 `./mvnw quarkus:dependency-tree`应生成类似以下内容的输出：

Executing ./mvnw quarkus:dependency-tree on your project should result in an output similar to:

[INFO] --- quarkus-maven-plugin:{quarkus-version}:dependency-tree (default-cli) @ getting-started ---
[INFO] org.acme:getting-started:jar:1.0.0-SNAPSHOT
[INFO] └─ io.quarkus:quarkus-resteasy-deployment:jar:{quarkus-version} (compile)
[INFO]    ├─ io.quarkus:quarkus-resteasy-server-common-deployment:jar:{quarkus-version} (compile)
[INFO]    │  ├─ io.quarkus:quarkus-core-deployment:jar:{quarkus-version} (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)
...

该目标接受以下可选参数：

The goal accepts the following optional parameters:

  • mode - the default value is prod, i.e. the production build dependency tree. Alternatively, it accepts values test to display the test dependency tree and dev to display the dev mode dependency tree;

  • outputFile - specifies the file to persist the dependency tree to;

  • appendOutput - the default value is false, indicates whether the output to the command should be appended to the file specified with the outputFile parameter or it should be overridden.

Downloading Maven artifact dependencies for offline development and testing

Quarkus 扩展依赖项分为最终出现在应用程序运行时类路径中的运行时扩展依赖项和部署（或构建时）扩展依赖项，而 Quarkus 仅在应用程序构建时解析后者以创建构建类路径。应用程序开发人员预计只会对 Quarkus 扩展的运行时制品表达依赖项。因此，部署扩展依赖项对于不了解 Quarkus 扩展依赖模型的 Maven 插件（例如 maven-dependency-plugin、`go-offline-maven-plugin`等）是不可见的。这意味着这些插件不能用于预下载所有应用程序依赖项，以便稍后在脱机模式下构建和测试应用程序。

Quarkus extension dependencies are divided into the runtime extension dependencies that end up on the application runtime classpath and the deployment (or build time) extension dependencies that are resolved by Quarkus only at application build time to create the build classpath. Application developers are expected to express dependencies only on the runtime artifacts of Quarkus extensions. As a consequence, the deployment extension dependencies aren’t visible to Maven plugins that aren’t aware of the Quarkus extension dependency model, such as the maven-dependency-plugin, go-offline-maven-plugin, etc. That means those plugins can not be used to pre-download all the application dependencies to be able to build and test the application later in offline mode.

为了启用在脱机状态下构建和测试 Quarkus 应用程序的用例，`quarkus-maven-plugin`包含 `go-offline`目标，可以如此从命令行调用：

To enable the use-case of building and testing a Quarkus application offline, the quarkus-maven-plugin includes the go-offline goal that could be called from the command line like this:

./mvnw quarkus:go-offline

此目标将解析应用程序的所有运行时、构建时、测试和开发模式依赖项，并将它们下载到配置的本地 Maven 仓库。

This goal will resolve all the runtime, build time, test and dev mode dependencies of the application downloading them to the configured local Maven repository.

Building a native executable

本机可执行文件使 Quarkus 应用程序非常适合容器和无服务器工作负载。

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

确保已配置 `GRAALVM_HOME`并将其指向 GraalVM {graalvm-version} 的最新版本。验证您的 `pom.xml`具有适当的 `native`配置，如 Maven configuration 中所示。

Make sure to have GRAALVM_HOME configured and pointing to the latest release of GraalVM {graalvm-version}. Verify that your pom.xml has the proper native profile as shown in Maven configuration.

使用以下命令创建本机可执行文件：

Create a native executable using:

Unresolved directive in maven-tooling.adoc - include::{includes}/devtools/build-native.adoc[]

本机可执行文件将显示在 target/ 中。

A native executable will be present in target/.

要在本机可执行文件上运行集成测试，请确保具有适当的 Maven plugin configured并启动 verify 目标。

To run Integration Tests on the native executable, make sure to have the proper build-tool-maven and launch the verify goal.

$ ./mvnw verify -Dnative
...
[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, rest]
[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:

include::{includes}/devtools/build-native.adoc[]:!build-additional-parameters:

Unresolved directive in maven-tooling.adoc - include::{includes}/devtools/build-native.adoc[] :!build-additional-parameters:

生成的执行文件将是 64 位的 Linux 执行文件，因此，根据您的操作系统，它可能不再具有可运行性。然而，这不是问题，因为我们准备将它复制到 Docker 容器。请注意，在这种情况下构建本身也在 Docker 容器中运行，因此您无需在本地安装 GraalVM。

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.

默认情况下，将使用 quay.io/quarkus/ubi-quarkus-mandrel-builder-image:{mandrel-flavor} Docker 映像生成原生可执行文件。

By default, the native executable will be generated using the quay.io/quarkus/ubi-quarkus-mandrel-builder-image:{mandrel-flavor} Docker image.

如果您要使用不同的 Docker 映像（例如使用不同的 GraalVM 版本）构建原生可执行文件，请使用 -Dquarkus.native.builder-image=<image name> 构建参数。

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.

可在此处找到可用 Docker 镜像列表： quay.io。请注意，给定的 Quarkus 版本可能与所有可用的镜像不兼容。

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.

您还可以关注 Build a native executable guide 和 Deploying Application to Kubernetes and OpenShift 了解详细信息。

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

Maven configuration

如果您尚未使用 project scaffolding，请在您的 pom.xml 中添加以下元素

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

<properties>
    <skipITs>true</skipITs> 1
</properties>

<dependencyManagement>
    <dependencies>
        <dependency> 2
            <groupId>${quarkus.platform.group-id}</groupId>
            <artifactId>quarkus-bom</artifactId>
            <version>${quarkus.platform.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<build>
    <plugins>
        <plugin> 3
            <groupId>${quarkus.platform.group-id}</groupId>
            <artifactId>quarkus-maven-plugin</artifactId>
            <version>${quarkus.platform.version}</version>
            <extensions>true</extensions> 4
            <executions>
                <execution>
                    <goals>
                        <goal>build</goal>
                        <goal>generate-code</goal>
                        <goal>generate-code-tests</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
        <plugin> 5
            <groupId>org.apache.maven.plugins</groupId>
            <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>
        <plugin> 6
            <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>
    </plugins>
</build>

<profiles>
    <profile> 7
        <id>native</id>
        <properties> 8
            <quarkus.native.enabled>true</quarkus.native.enabled>
            <skipITs>false</skipITs> 9
        </properties>
    </profile>
</profiles>
1 Disable running of integration tests (test names *IT and annotated with @QuarkusIntegrationTest) on all builds. To run these tests all the time, either remove this property, set its value to false, or set -DskipITs=false on the command line when you run the build. As mentioned below, this is overridden in the native profile.
2 Optionally use a BOM file to omit the version of the different Quarkus dependencies.
3 Use the Quarkus Maven plugin that will hook into the build process.
4 Enabling Maven plugin extensions will register a Quarkus MavenLifecycleParticipant which will make sure the Quarkus classloaders used during the build are properly closed. During the generate-code and generate-code-tests goals the Quarkus application bootstrap is initialized and re-used in the build goal (which actually builds and packages a production application). The Quarkus classloaders will be properly closed in the build goal of the quarkus-maven-plugin. However, if the build fails in between the generate-code or generate-code-tests and build then the Quarkus augmentation classloader won’t be properly closed, which may lead to locking of JAR files that happened to be on the classpath on Windows OS.
5 Add system properties to maven-surefire-plugin. maven.home is only required if you have custom configuration in ${maven.home}/conf/settings.xml.
6 If you want to test the artifact produced by your build with Integration Tests, add the following plugin configuration. Test names *IT and annotated with @QuarkusIntegrationTest will be run against the artifact produced by the build (JAR file, container image, etc). See the Integration Testing guide for more info. maven.home is only required if you have custom configuration in ${maven.home}/conf/settings.xml.
7 Use a specific native profile for native executable building.
8 Enable the native package type. The build will therefore produce a native executable.
9 Always run integration tests when building a native image (test names *IT and annotated with @QuarkusIntegrationTest). If you do not wish to run integration tests when building a native image, simply remove this property altogether or set its value to true.

Using fast-jar

fast-jar 是默认的 quarkus 包类型。

fast-jar is the default quarkus package type.

构建的结果是 target 下名为 quarkus-app 的目录。

The result of the build is a directory under target named quarkus-app.

你可以使用以下方式运行应用程序：java -jar target/quarkus-app/quarkus-run.jar

You can run the application using: java -jar target/quarkus-app/quarkus-run.jar.

若要成功运行生成的 jar，你需要 quarkus-app 目录的全部内容。如果缺少任何文件，应用程序将无法启动或可能无法正确运行。

In order to successfully run the produced jar, you need to have the entire contents of the quarkus-app directory. If any of the files are missing, the application will not start or might not function correctly.

fast-jar 打包通过创建工件以比旧 Quarkus jar 更快地启动并消耗更少的内存，因为它已对哪个依赖项 jar 包含类和资源编制索引。在加载类或资源时，它因此可以避免像传统 jar 在类路径中搜索每个 jar。

The fast-jar packaging results in creating an artifact that starts a little faster and consumes slightly less memory than a legacy Quarkus jar because it has indexed information about which dependency jar contains classes and resources. It can thus avoid the lookup into potentially every jar on the classpath that the legacy jar necessitates, when loading a class or resource.

Uber-Jar Creation

Quarkus Maven 插件支持通过在 application.properties（或在 pom.xml 中的 <quarkus.package.jar.type>uber-jar</quarkus.package.jar.type>）中指定 quarkus.package.jar.type=uber-jar 配置选项来生成 Uber-Jars。

Quarkus Maven plugin supports the generation of Uber-Jars by specifying a quarkus.package.jar.type=uber-jar configuration option in your application.properties (or <quarkus.package.jar.type>uber-jar</quarkus.package.jar.type> in your pom.xml).

原始 jar 仍然存在于 target 目录中，但它将被重命名以包含 .original 后缀。

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

在构建 Uber-Jar 时，你可以通过使用 quarkus.package.ignored-entries 配置选项指定要从生成的 jar 中排除的条目，这将获取要忽略的一系列条目。

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 separated list of entries to ignore.

Uber-Jar 默认会排除应用程序依赖项中可能存在的 signature files。

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

Uber-Jar 的最终名称可以通过 Maven 构建设置 finalName 选项进行配置。

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

Uber-Jar file name suffix

默认情况下，所生成的 uber JAR 文件名将具有 -runner 后缀，除非通过使用 quarkus.package.runner-suffix 配置选项配置自定义名称来覆盖它。如果不需要后缀，可以通过将 quarkus.package.jar.add-runner-suffix 配置选项设置为 false 来禁用它，在这种情况下，uber JAR 将替换 maven-jar-plugin 为应用程序模块生成的原始 JAR 文件。

By default the generated uber JAR file name will have the -runner suffix, unless it was overriden by configuring a custom one with quarkus.package.runner-suffix configuration option. If the runner suffix is not desired, it can be disabled by setting quarkus.package.jar.add-runner-suffix configuration option to false, in which case the uber JAR will replace the original JAR file generated by maven-jar-plugin for the application module.

Attaching Uber-Jar file as the main project artifact

只要 Uber-Jar 文件名是通过将后缀（如 runner）追加到原始项目 JAR 文件名来创建的，Uber-Jar 文件名后缀也将用作 Uber-Jar 工件的 Maven 工件分类器。有两种方法可以将 Uber-Jar 作为主要项目工件附加（不带分类器）：

As long as an Uber-Jar file name is created by appending a suffix, such as runner, to the original project JAR file name, the Uber-Jar file name suffix will also be used as the Maven artifact classifier for the Uber-Jar artifact. There are two ways to attach an Uber-Jar as the main project artifact (without the classifier):

  1. set quarkus.package.jar.add-runner-suffix=false, which will disable the addition of the file name suffix and, by doing that, will replace the original project JAR on the file system;

  2. set attachRunnerAsMainArtifact parameter of the quarkus:build goal to true.

Working with multi-module projects

默认情况下，Quarkus 不会在另一个模块内部发现 CDI Bean。

By default, Quarkus will not discover CDI beans inside another module.

为多模块项目中的模块启用 CDI Bean 发现的最佳方法是包括 jandex-maven-plugin，除非它是已使用 quarkus-maven-plugin 配置的主应用程序模块，在这种情况下，它将自动编入索引。

The best way to enable CDI bean discovery for a module in a multi-module project would be to include the jandex-maven-plugin, unless it is the main application module already configured with the quarkus-maven-plugin, in which case it will be indexed automatically.

<build>
  <plugins>
    <plugin>
      <groupId>io.smallrye</groupId>
      <artifactId>jandex-maven-plugin</artifactId>
      <version>{jandex-version}</version>
      <executions>
        <execution>
          <id>make-index</id>
          <goals>
            <goal>jandex</goal>
          </goals>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>

有关此主题的更多信息，请参见 CDI 指南的 Bean Discovery 部分。

More information on this topic can be found on the Bean Discovery section of the CDI guide.

Maven test plugin configuration

上面显示的 maven-surefire-plugin 和 maven-failsafe-plugin 配置在大多数情况下都会起作用。但是，可能需要额外的配置。

maven-surefire-plugin and maven-failsafe-plugin configurations showed above will work in most cases. However, there could be cases when extra configuration will be required.

原因是，Quarkus 可能需要在测试阶段重新解析应用程序依赖项，以便为测试设置测试类路径。在测试过程中将无法使用以前构建阶段中使用的原始 Maven 解析器，因此，Quarkus 需要初始化一个新解析器。为了确保正确初始化新解析器，需要将相关配置选项传递给测试过程。

The reason is that, Quarkus may need to re-resolve application dependencies during the test phase to set up the test classpath for the tests. The original Maven resolver used in previous build phases will not be available in the test process and, as a conseqence, Quarkus will need to initialize a new one. To make sure the new resolver is initialized correctly, the relevant configuration options will need to be passed to the test process.

Maven user settings

可能需要将 Maven 用户设置文件的路径传递给测试过程，例如，在没有使用 Maven 发行版中包含的默认 mvn 脚本启动 Maven 构建过程的情况下。可以通过以下方式完成：

A path to the Maven user settings file may need to be passed to test processes, for example, in case the Maven build process was not launched using the default mvn scripts included in the Maven distribution. It could be done in the following way:

        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-surefire-plugin</artifactId>
            <version>${surefire-plugin.version}</version>
            <configuration>
                <systemPropertyVariables>
                    <!-- skip -->
                    <maven.settings>${session.request.userSettingsFile.absolutePath}</maven.settings>
                </systemPropertyVariables>
            </configuration>
        </plugin>

Remote repository access through authenticated HTTPS

如果远程 Maven 存储库需要 authenticated HTTPS access configuration，则需要将以下所有或部分属性传递给测试插件：

In case a remote Maven repository requires authenticated HTTPS access configuration, some or all of the following properties will need to be passed to the test plugins:

        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-surefire-plugin</artifactId>
            <version>${surefire-plugin.version}</version>
            <configuration>
                <systemPropertyVariables>
                    <!-- skip -->
                    <javax.net.ssl.keyStoreType>${javax.net.ssl.keyStoreType}</javax.net.ssl.keyStoreType>
                    <javax.net.ssl.keyStore>${javax.net.ssl.keyStore}</javax.net.ssl.keyStore>
                    <javax.net.ssl.keyStorePassword>${javax.net.ssl.keyStorePassword}</javax.net.ssl.keyStorePassword>
                    <javax.net.ssl.trustStore>${javax.net.ssl.trustStore}</javax.net.ssl.trustStore>
                    <javax.net.ssl.trustStorePassword>${javax.net.ssl.trustStorePassword}</javax.net.ssl.trustStorePassword>
                </systemPropertyVariables>
            </configuration>
        </plugin>

Building with a specific configuration profile

Quarkus 支持 configuration profiles 以便根据目标环境提供特定配置。

Quarkus supports configuration profiles in order to provide a specific configuration according to the target environment.

该配置文件可直接采用类型为 mvn:build-helper-plugin 的命令提供给 Maven 构建命令，借助系统属性 quarkus.profile：

The profile can be provided directly in the Maven build’s command thanks to the system property quarkus.profile with a command of type:

include::{includes}/devtools/build.adoc[]:!build-additional-parameters:

Unresolved directive in maven-tooling.adoc - include::{includes}/devtools/build.adoc[] :!build-additional-parameters:

不过，也可使用项目属性、Quarkus Maven 插件配置属性或在 Quarkus Maven 插件配置中设置的系统属性，在项目的 POM 文件中直接指定配置文件。

However, it is also possible to specify the profile directly in the POM file of the project using project properties, the Quarkus Maven plugin configuration properties or system properties set in the Quarkus Maven plugin configuration.

优先顺序如下（优先级越高则最先）：

In order of precedence (greater precedence first):

1. System properties set in the Quarkus Maven plugin configuration
<project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd" xmlns="http://maven.apache.org/POM/4.0.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  ...
  <build>
    <plugins>
      ...
      <plugin>
        <groupId>${quarkus.platform.group-id}</groupId>
        <artifactId>quarkus-maven-plugin</artifactId>
        <version>${quarkus.platform.version}</version>
        <extensions>true</extensions>
        <configuration>
          <systemProperties>
            <quarkus.profile>prod-aws</quarkus.profile> 1
          </systemProperties>
        </configuration>
     </plugin>
     ...
    </plugins>
  </build>
...
</project>
1 The default configuration profile of this project is prod-aws.
2. Quarkus Maven plugin configuration properties
<project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd" xmlns="http://maven.apache.org/POM/4.0.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  ...
  <build>
    <plugins>
      ...
      <plugin>
        <groupId>${quarkus.platform.group-id}</groupId>
        <artifactId>quarkus-maven-plugin</artifactId>
        <version>${quarkus.platform.version}</version>
        <extensions>true</extensions>
        <configuration>
          <properties>
            <quarkus.profile>prod-aws</quarkus.profile> 1
          </properties>
        </configuration>
     </plugin>
     ...
    </plugins>
  </build>
...
</project>
1 The default configuration profile of this project is prod-aws.
3. Project properties
<project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd" xmlns="http://maven.apache.org/POM/4.0.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  ...
  <properties>
    <quarkus.profile>prod-aws</quarkus.profile> 1
    ...
  </properties>
...
</project>
1 The default configuration profile of this project is prod-aws.

无论选择哪种方法，都可以使用 quarkus.profile 系统属性或 QUARKUS_PROFILE 环境变量重写配置文件。

Whatever the approach is chosen, the profile can still be overridden with the quarkus.profile system property or the QUARKUS_PROFILE environment variable.

Building several artifacts from a single module

在一些特定使用案例中，从同一模块构建应用程序的多个工件会非常有用。一个典型的示例是，当你想使用不同的配置配置文件构建应用程序时。

In some particular use cases, it can be interesting to build several artifacts of your application from the same module. A typical example is when you want to build your application with different configuration profiles.

在这种情况下，可以在 Quarkus Maven 插件配置中按需添加任意多个执行。

In that case, it is possible to add as many executions as needed to the Quarkus Maven plugin configuration.

下面是一个 Quarkus Maven 插件配置示例，它会生成同一应用程序的两个构建：一个使用 prod-oracle 配置文件，另一个使用 prod-postgresql 配置文件。

Below is an example of a Quarkus Maven plugin configuration that will produce two builds of the same application: one using the prod-oracle profile and the other one using the prod-postgresql profile.

<project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd" xmlns="http://maven.apache.org/POM/4.0.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  ...
  <build>
    <plugins>
      ...
      <plugin>
        <groupId>${quarkus.platform.group-id}</groupId>
        <artifactId>quarkus-maven-plugin</artifactId>
        <version>${quarkus.platform.version}</version>
        <extensions>true</extensions>
        <executions>
          <execution>
            <id>oracle</id>
            <goals>
              <goal>build</goal>
            </goals>
            <configuration>
              <properties>
                <quarkus.profile>prod-oracle</quarkus.profile> 1
                <quarkus.package.output-directory>oracle-quarkus-app</quarkus.package.output-directory> 2
              </properties>
            </configuration>
          </execution>
          <execution>
            <id>postgresql</id>
            <goals>
              <goal>build</goal>
            </goals>
            <configuration>
              <properties>
                <quarkus.profile>prod-postgresql</quarkus.profile> 3
                <quarkus.package.output-directory>postgresql-quarkus-app</quarkus.package.output-directory> 4
              </properties>
            </configuration>
          </execution>
        </executions>
     </plugin>
     ...
    </plugins>
  </build>
...
</project>
1 The default configuration profile of the first execution of the plugin is prod-oracle.
2 The output directory of the first execution of the plugin is set to oracle-quarkus-app instead of quarkus-app to have a dedicated directory.
3 The default configuration profile of the second execution of the plugin is prod-postgresql.
4 The output directory of the second execution of the plugin is set to postgresql-quarkus-app instead of quarkus-app to have a dedicated directory.

使用上述配置，两个配置文件构建将使用相同的依赖关系，因此，如果我们向应用程序中添加了 Oracle 和 PostgreSQL 驱动程序的依赖关系，则这两个驱动程序都将出现在两个构建中。

With the configuration above, both profile builds will be using the same dependencies, so if we added dependencies on the Oracle and PostgreSQL drivers to the application, both of the drivers will appear in both builds.

为了从其他配置文件中隔离特定配置文件的依赖关系，JDBC 驱动程序可以作为可选依赖关系添加到应用程序中，但配置为包含在需要它们的每个配置文件中，例如：

To isolate profile-specific dependencies from other profiles, the JDBC drivers could be added as optional dependencies to the application but configured to be included in each profile that requires them, e.g.:

<project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd" xmlns="http://maven.apache.org/POM/4.0.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  ...
  <dependencies>
    ...
    <dependency>
      <groupId>org.postgresql</groupId>
      <artifactId>postgresql</artifactId>
      <version>${postgresql.driver.version}</version>
      <optional>true</optional> 1
    </dependency>
  </dependencies>
  <build>
    <plugins>
      ...
      <plugin>
        <groupId>${quarkus.platform.group-id}</groupId>
        <artifactId>quarkus-maven-plugin</artifactId>
        <version>${quarkus.platform.version}</version>
        <extensions>true</extensions>
        <executions>
          ...
          <execution>
            <id>postgresql</id>
            <goals>
              <goal>build</goal>
            </goals>
            <configuration>
              <properties>
                <quarkus.profile>prod-postgresql</quarkus.profile>
                <quarkus.package.output-directory>postgresql-quarkus-app</quarkus.package.output-directory>
                <quarkus.package.jar.filter-optional-dependencies>true</quarkus.package.jar.filter-optional-dependencies> 2
                <quarkus.package.jar.included-optional-dependencies>org.postgresql:postgresql::jar</quarkus.package.jar.included-optional-dependencies> 3
              </properties>
            </configuration>
          </execution>
        </executions>
     </plugin>
     ...
    </plugins>
  </build>
...
</project>
1 The JDBC driver of PostgreSQL is defined as an optional dependency
2 For backward compatibility reasons, it is necessary to explicitly indicate that the optional dependencies need to be filtered.
3 Only the optional dependency corresponding to the JDBC driver of PostgreSQL is expected in the final artifact.

如果要在 quarkus.package.jar.included-optional-dependencies 标记中声明多个可选依赖项，请确保用 , 将其分隔开（例如，org.postgresql:postgresql::jar,com.foo:bar::jar）。

If you have more than one optional dependency to declare in the quarkus.package.jar.included-optional-dependencies tag, make sure they are separated with , (e.g. org.postgresql:postgresql::jar,com.foo:bar::jar).

Configuring the Project Output

有一些配置选项将定义项目构建的输出内容。这些选项与任何其他配置属性在 application.properties 中的提供方式相同。

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:

Unresolved directive in maven-tooling.adoc - include::{generated-dir}/config/quarkus-core_quarkus.package.adoc[]

Custom test configuration profile in JVM mode

默认情况下，使用 test 配置配置文件运行 JVM 模式下的 Quarkus 测试。如果你不熟悉 Quarkus 配置配置文件，所有你需要了解的内容都在 Configuration Profiles Documentation 中进行了说明。

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.

但你可以使用以下所示的 Maven Surefire 和 Maven Failsafe 配置为测试使用自定义配置配置文件。如果需要使用非默认测试数据库运行一些测试，这会很有用。

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.

现在还无法在原生模式下使用测试自定义配置文件。始终使用 prod 配置文件运行原生测试。

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.

Bootstrap Maven properties

Quarkus 启动程序包含一个 Maven 解析器实现，用于解析应用程序运行时和构建时依赖项。Quarkus Maven 解析器使用启动构建、测试或开发模式的相同 Maven 命令行进行初始化。通常，无需添加任何额外配置。但有时可能需要一个额外的配置选项才能在测试或开发模式或 IDE 中正确解析应用程序依赖项。

Quarkus bootstrap includes a Maven resolver implementation that is used to resolve application runtime and build time dependencies. The Quarkus Maven resolver is initialized from the same Maven command line that launched the build, test or dev mode. Typically, there is no need to add any extra configuration for it. However, there could be cases where an extra configuration option may be necessary to properly resolve application dependencies in test or dev modes, or IDEs.

例如，Maven 测试插件（例如 surefire 和 failsafe）不会默认将构建系统属性传播到正在运行的测试。这意味着 Maven CLI 设置的一些系统属性对于针对测试初始化的 Quarkus Maven 解析器不可用，这可能导致使用不同于主 Maven 构建的设置来解析测试依赖项。

Maven test plugins (such as surefire and failsafe), for example, are not propagating build system properties to the running tests by default. Which means some system properties set by the Maven CLI aren’t available for the Quarkus Maven resolver initialized for the tests, which may result in test dependencies being resolved using different settings than the main Maven build.

以下是 Quarkus 启动程序 Maven 解析器在初始化期间检查的系统属性列表。

Here is a list of system properties the Quarkus bootstrap Maven resolver checks during its initialization.

Property name Default Value Description

maven.home

MAVEN_HOME envvar

The Maven home dir is used to resolve the global settings file unless it was explicitly provided on the command line with the -gs argument

maven.settings

~/.m2/settings.xml

Unless the custom settings file has been provided with the -s argument, this property can be used to point the resolver to a custom Maven settings file

maven.repo.local

~/.m2/repository

This property could be used to configure a custom local Maven repository directory, if it is different from the default one and the one specified in the settings.xml

maven.top-level-basedir

none

This property may be useful to help the Maven resolver identify the top-level Maven project in the workspace. By default, the Maven resolver will be discovering a project’s workspace by navigating the parent-module POM relationship. However, there could be project layouts that are using an aggregator module which isn’t appearing as the parent for its modules. In this case, this property will help the Quarkus Maven resolver to properly discover the workspace.

quarkus.bootstrap.effective-model-builder

false

By default, the Quarkus Maven resolver is reading project’s POMs directly when discovering the project’s layout. While in most cases it works well enough and relatively fast, reading raw POMs has its limitation. E.g. if a POM includes modules in a profile, these modules will not be discovered. This system property enables project’s layout discovery based on the effective POM models, that are properly interpolated, instead of the raw ones. The reason this option is not enabled by default is it may appear to be significantly more time-consuming that could increase, e.g. CI testing times. Until there is a better approach found that could be used by default, projects that require it should enable this option.

以上这些系统属性可以添加到 surefire 和/或 failsafe 插件配置中，如

These system properties above could be added to, e.g., a surefire and/or failsafe plugin configuration as

<project>
  [...]
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-surefire-plugin</artifactId>
        <version>${surefire-plugin.version}</version>
        <configuration>
          <systemPropertyVariables>
            <maven.home>${maven.home}</maven.home> 1
            <maven.repo.local>${settings.localRepository}</maven.repo.local> 2
            <maven.settings>${session.request.userSettingsFile.path}</maven.settings> 3
            <maven.top-level-basedir>${session.topLevelProject.basedir.absolutePath}</maven.top-level-basedir> 4
            <quarkus.bootstrap.effective-model-builder>true</quarkus.bootstrap.effective-model-builder> 5
          </systemPropertyVariables>
        </configuration>
      </plugin>
    </plugins>
  </build>
  [...]
</project>
1 Propagate maven.home system property set by the Maven CLI to the tests
2 Set the Maven local repository directory for the tests
3 Set the Maven settings file the tests
4 Point to the top-level project directory for the tests
5 Enable effective POM-based project layout discovery

Top-level vs Multi-module project directory

在 Maven 中，似乎存在顶级项目概念（公开为项目属性 ${session.topLevelProject.basedir.absolutePath}）和多模块项目目录（可用作属性 ${maven.multiModuleProjectDirectory}）。这些目录不一定总是一致的！

In Maven there appears to be a notion of the top-level project (that is exposed as a project property ${session.topLevelProject.basedir.absolutePath}) and the multi-module project directory (that is available as property ${maven.multiModuleProjectDirectory}). These directories might not always match!

maven.multiModuleProjectDirectory 预计由 Maven 代码本身参考，而非依赖用户代码。因此，如果您觉得有帮助，请自行承担风险！

maven.multiModuleProjectDirectory is meant to be consulted by the Maven code itself and not something to be relied upon by user code. So, if you find it useful, use it at your own risk!

${maven.multiModuleProjectDirectory} 会解析为第一个包含 .mvn 目录的目录，该目录为其子目录，从当前目录（或通过 -f 参数指定的目录）启动 mvn 命令时，从工作空间文件系统树开始向上移动。但如果未找到 .mvn 目录，则 ${maven.multiModuleProjectDirectory} 会指向启动 mvn 命令的目录（或通过 -f 参数指定的目录）。

The ${maven.multiModuleProjectDirectory} will be resolved to the first directory that contains .mvn directory as its child going up the workspace file system tree starting from the current directory (or the one specified with the -f argument) from which the mvn command was launched. If the .mvn directory was not found, however, the ${maven.multiModuleProjectDirectory} will be pointing to the directory from which the mvn command was launched (or the one targeted with the -f argument).

${session.topLevelProject.basedir.absolutePath} 会指向启动 mvn 命令的目录或使用 -f 参数指定的目录（如果指定了该参数）。

The ${session.topLevelProject.basedir.absolutePath} will be pointing either to the directory from which the mvn command was launched or to the directory targeted with the -f argument, if it was specified.

Quarkus project info

Quarkus Maven 插件包括一个称为 info 的目标（目前标记为“实验”），它会记录项目中特定于 Quarkus 的信息，例如：导入的 Quarkus 平台 BOM 和项目依存关系中找到的 Quarkus 扩展。在多模块项目 quarkus:info 中会认为当前模块（在其中执行）是应用程序的主模块。

The Quarkus Maven plugin includes a goal called info (currently marked as 'experimental') that logs Quarkus-specific information about the project, such as: the imported Quarkus platform BOMs and the Quarkus extensions found among the project dependencies. In a multi-module project quarkus:info will assume that the current module, in which it is executed, is the main module of the application.

目前 quarkus:info 生成的报告不包括 Quarkus Maven 插件信息，但计划在未来版本中添加。

The report generated by quarkus:info is not currently including the Quarkus Maven plugin information, however it’s planned to be added in the future releases.

下面是一个简单项目的 info 输出示例：

Here is an example info output for a simple project:

[aloubyansky@localhost code-with-quarkus]$ mvn quarkus:info
[INFO] Scanning for projects...
[INFO]
[INFO] ---------------------< org.acme:code-with-quarkus >---------------------
[INFO] Building code-with-quarkus 1.0.0-SNAPSHOT
[INFO] --------------------------------[ jar ]---------------------------------
[INFO]
[INFO] --- quarkus-maven-plugin:{quarkus-version}:info (default-cli) @ code-with-quarkus ---
[WARNING] quarkus:info goal is experimental, its options and output may change in future versions
[INFO] Quarkus platform BOMs: 1
[INFO]   {quarkus-platform-groupid}:quarkus-bom:pom:{quarkus-version}
[INFO]   {quarkus-platform-groupid}:quarkus-camel-bom:pom:{quarkus-version}
[INFO]
[INFO] Extensions from {quarkus-platform-groupid}:quarkus-bom: 2
[INFO]   io.quarkus:quarkus-rest
[INFO]
[INFO] Extensions from {quarkus-platform-groupid}:quarkus-camel-bom: 3
[INFO]   org.apache.camel.quarkus:camel-quarkus-rabbitmq
[INFO]
[INFO] Extensions from registry.quarkus.io: 4
[INFO]   io.quarkiverse.prettytime:quarkus-prettytime:2.0.1
1 Quarkus platform BOMs imported in the project (BOMs imported by parent POMs will also be reported)
2 Direct Quarkus extension dependencies managed by the quarkus-bom
3 Direct Quarkus extension dependencies managed by the quarkus-camel-bom
4 Direct Quarkus extensions dependencies that aren’t managed by Quarkus BOMs but found in the Quarkus extension registry

quarkus:info 还会报告 Quarkus 扩展注册表中找不到的 Quarkus 扩展（如果这些扩展存在于项目依存关系中），表明这些扩展的“来源未知”。

quarkus:info will also report Quarkus extensions that aren’t found in the Quarkus extension registries if those are present among the project dependencies, indicating they have an 'unknown origin'.

Highlighting misaligned versions

在检测到基本 Quarkus 依赖关系版本不一致时，quarkus:info 也会突出显示它们。例如，如果我们通过从依存关系中删除 camel-quarkus-rabbitmq 扩展并在 quarkus-bom 管理的 quarkus-rest 依存关系中添加 2.6.3.Final <version> 元素来修改上面提到的项目，然后再次运行 quarkus:info，会看到类似以下内容：

quarkus:info will also highlight basic Quarkus dependency version misalignments, in case they are detected. For example, if we modify the project mentioned above by removing the camel-quarkus-rabbitmq extension from the dependencies and adding a 2.6.3.Final <version> element to the quarkus-rest dependency that is managed by the quarkus-bom and then run quarkus:info again, we’ll see something like:

[INFO] --- quarkus-maven-plugin:{quarkus-version}:info (default-cli) @ code-with-quarkus ---
[WARNING] quarkus:info goal is experimental, its options and output may change in future versions
[INFO] Quarkus platform BOMs:
[INFO]   {quarkus-platform-groupid}:quarkus-bom:pom:{quarkus-version}
[INFO]   {quarkus-platform-groupid}:quarkus-camel-bom:pom:{quarkus-version} | unnecessary 1
[INFO]
[INFO] Extensions from {quarkus-platform-groupid}:quarkus-bom:
[INFO]   io.quarkus:quarkus-resteasy-reactive:2.6.3.Final | misaligned 2
[INFO]
[INFO] Extensions from {quarkus-platform-groupid}:quarkus-camel-bom:
[INFO]   org.apache.camel.quarkus:camel-quarkus-rabbitmq
[INFO]
[INFO] Extensions from registry.quarkus.io:
[INFO]   io.quarkiverse.prettytime:quarkus-prettytime:2.0.1
[INFO]
[WARNING] Non-recommended Quarkus platform BOM and/or extension versions were found. For more details, please, execute 'mvn quarkus:update -Drectify'
1 The quarkus-camel-bom import is now reported as 'unnecessary' since none of the Quarkus extensions it includes are found among the project dependencies
2 The version 2.6.3.Final of the quarkus-resteasy-reactive is now reported as being misaligned with the version managed by the Quarkus platform BOM imported in the project, which is {quarkus-version}

Quarkus project update

Quarkus Maven 插件提供的 quarkus:update 目标（目前标记为“实验”）可用于检查项目是否存在可用的与 Quarkus 相关的更新，例如：相关 Quarkus 平台 BOM 的新版本和项目中存在的非平台 Quarkus 扩展。在多模块项目中，update 目标应从 Quarkus 主应用程序模块执行。

The quarkus:update goal (currently marked as 'experimental') provided by the Quarkus Maven plugin can be used to check whether there are Quarkus-related updates available for a project, such as: new releases of the relevant Quarkus platform BOMs and non-platform Quarkus extensions present in the project. In a multi-module project the update goal is meant to be executed from the main Quarkus application module.

在这一点上，`quarkus:update`目标实际上不会应用推荐的更新，但会告诉您更新内容以及如何手动应用。

At this point, the quarkus:update goal does not actually apply the recommended updates but simply reports what they are and how to apply them manually.

Quarkus Maven 插件的版本当前并未包含在更新报告中，但计划在未来的版本中添加。

The Quarkus Maven plugin version isn’t currently included in the update report, however it’s planned to be added in the future releases.

quarkus:update`的工作方式是，首先，收集项目的所有直接 Quarkus 扩展依赖项（由 Quarkus 平台 BOM 管理的和未由 Quarkus 平台 BOM 管理但在 Quarkus 扩展注册表中找到的）。然后，将查询已配置的 Quarkus 扩展注册表（通常是 `registry.quarkus.io）以获得最新推荐/支持的 Quarkus 平台版本和与之兼容的非平台 Quarkus 扩展。然后，该算法将选择项目中找到的所有扩展的最新兼容组合（假设这种组合确实存在）。否则，将不建议进行更新。

The way quarkus:update works, first, all the direct Quarkus extension dependencies of the project are collected (those that are managed by the Quarkus platform BOMs and those that aren’t but found in the Quarkus extension registries). Then the configured Quarkus extension registries (typically the registry.quarkus.io) will be queried for the latest recommended/supported Quarkus platform versions and non-platform Quarkus extensions compatible with them. The algorithm will then select the latest compatible combination of all the extensions found in the project, assuming such a combination actually exists. Otherwise, no updates will be suggested.

假设我们有一个项目包括基于 Quarkus `2.7.1.Final`的 Quarkus 平台中可用的 Kogito、Camel 和核心 Quarkus 扩展，则 `quarkus:update`的输出如下所示：

Assuming we have a project including Kogito, Camel and core Quarkus extensions available in the Quarkus platform based on Quarkus 2.7.1.Final, the output of the quarkus:update would look like:

[aloubyansky@localhost code-with-quarkus]$ mvn quarkus:update
[INFO] Scanning for projects...
[INFO]
[INFO] ---------------------< org.acme:code-with-quarkus >---------------------
[INFO] Building code-with-quarkus 1.0.0-SNAPSHOT
[INFO] --------------------------------[ jar ]---------------------------------
[INFO]
[INFO] --- quarkus-maven-plugin:{quarkus-version}:update (default-cli) @ code-with-quarkus ---
[WARNING] quarkus:update goal is experimental, its options and output might change in future versions
[INFO]
[INFO] Recommended Quarkus platform BOM updates: 1
[INFO] Update: {quarkus-platform-groupid}:quarkus-bom:pom:2.7.1.Final -> {quarkus-version}
[INFO] Update: {quarkus-platform-groupid}:quarkus-camel-bom:pom:2.7.1.Final -> {quarkus-version}
1 A list of currently recommended Quarkus platform BOM updates

通常，将使用单个项目属性管理所有 Quarkus 平台 BOM，但当前的实现还不够智能，无法指出这一点，并会单独报告每个 BOM 的更新。

Typically, a single project property will be used to manage all the Quarkus platform BOMs but the implementation isn’t currently smart enough to point that out and will report updates for each BOM individually.

如果我们修改项目以从项目中删除所有 Camel Quarkus 扩展，将 quarkus-resteasy-reactive`扩展的版本更改为 `2.6.3.Final，并将未包含在 Quarkus 平台 BOM 中的 quarkus-prettytime`降级为 `0.2.0，则 `quarkus:update`将报告如下内容：

If we modify the project to remove all the Camel Quarkus extensions from the project, change the version of the quarkus-resteasy-reactive extension to 2.6.3.Final and downgrade quarkus-prettytime which is not included in the Quarkus platform BOMs to 0.2.0, quarkus:update will report something like:

[INFO] Recommended Quarkus platform BOM updates: 1
[INFO] Update: {quarkus-platform-groupid}:quarkus-bom:pom:2.7.1.Final -> {quarkus-version}
[INFO] Remove: {quarkus-platform-groupid}:quarkus-camel-bom:pom:2.7.1.Final 2
[INFO]
[INFO] Extensions from {quarkus-platform-groupid}:quarkus-bom:
[INFO] Update: io.quarkus:quarkus-resteasy-reactive:2.6.3.Final -> remove version (managed) 3
[INFO]
[INFO] Extensions from registry.quarkus.io:
[INFO] Update: io.quarkiverse.prettytime:quarkus-prettytime:0.2.0 -> 0.2.1 4
1 A list of the currently recommended Quarkus platform BOM updates for the project
2 Given that the project does not include any Camel Quarkus extensions, the BOM import is recommended to be removed
3 An outdated version of the quarkus-resteasy-reactive is recommended to be removed in favor of the one managed by the quarkus-bom
4 The latest compatible version of the quarkus-prettytime extension

Quarkus project rectify

如上所述，`quarkus:info`除了报告 Quarkus 平台和扩展版本外，还执行快速版本对齐检查，以确保项目中使用的扩展版本与导入的 Quarkus 平台 BOM 兼容。如果检测到不对齐，将记录以下警告消息：

As was mentioned above, quarkus:info, besides reporting Quarkus platform and extension versions, performs a quick version alignment check, to make sure the extension versions used in the project are compatible with the imported Quarkus platform BOMs. If misalignments are detected, the following warning message will be logged:

[WARNING] Non-recommended Quarkus platform BOM and/or extension versions were found. For more details, please, execute 'mvn quarkus:update -Drectify'

启用 `rectify`选项后，`quarkus:update`将记录更新说明，简单地将项目中找到的扩展依赖版本与当前导入的 Quarkus 平台 BOM 对齐，而不是建议使用最新的推荐 Quarkus 版本更新。

When the rectify option is enabled, quarkus:update, instead of suggesting the latest recommended Quarkus version updates, will log update instructions to simply align the extension dependency versions found in the project with the currently imported Quarkus platform BOMs.