编辑此页面

Quarkus 和 Maven

使用 Maven 创建新项目、添加或删除扩展、启动开发模式、调试应用程序以及将应用程序构建为 jar、原生可执行文件或容器友好的可执行文件。使用 Maven 项目元数据将项目导入到您喜欢的 IDE 中。

创建新项目

您可以使用以下命令搭建新的 Maven 项目

CLI
quarkus create app my-groupId:my-artifactId

有关如何安装和使用 Quarkus CLI 的更多信息,请参阅 Quarkus CLI 指南。

Maven
mvn io.quarkus.platform:quarkus-maven-plugin:3.24.4:create \
    -DprojectGroupId=my-groupId \
    -DprojectArtifactId=my-artifactId

对于 Windows 用户

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

  • 如果使用 Powershell,请将 -D 参数用双引号括起来,例如 "-DprojectArtifactId=my-artifactId"

如果使用 CLI,可以使用以下命令获取可用选项列表

quarkus create app --help

如果使用 Maven 命令,下表列出了可以传递给 create 命令的属性

属性 默认值 描述

projectGroupId

org.acme.sample

创建项目的 group id

projectArtifactId

必填

创建项目的 artifact id。不传递它会触发交互模式。

projectVersion

1.0.0-SNAPSHOT

创建项目的版本

platformGroupId

io.quarkus.platform

目标平台的 group id。

platformArtifactId

quarkus-bom

目标平台 BOM 的 artifact id。

platformVersion

Quarkus 扩展注册表当前推荐的版本

您希望项目使用的平台版本。它也可以接受版本范围,在这种情况下,将使用指定范围内的最新版本。

javaVersion

17

您希望项目使用的 Java 版本。

className

如果省略则不创建

生成的资源的完全限定名称

path

/hello

资源路径,仅在设置了 className 时相关。

extensions

[]

要添加到项目的扩展列表(逗号分隔)

quarkusRegistryClient

true

Quarkus 是否应使用在线注册表来解析扩展目录。如果设置为 false,则扩展目录将缩小到定义的(或默认)平台 BOM。

默认情况下,该命令将以 io.quarkus.platform:quarkus-bom:3.24.4 平台版本为目标(除非已指定所需平台版本的坐标)。

项目在以传递的 artifactId 命名的目录中生成。如果目录已存在,则生成失败。

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

处理扩展

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

CLI
quarkus extension
Maven
./mvnw quarkus:list-extensions

您可以使用以下命令添加扩展

CLI
quarkus extension add hibernate-validator
Maven
./mvnw quarkus:add-extension -Dextensions='hibernate-validator'

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

扩展名是扩展的 GAV 名称:例如,io.quarkus:quarkus-agroal。但是,您可以传递部分名称,Quarkus 将尽力找到正确的扩展。例如,agroalAgroalagro 将扩展为 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?
[...]

您可以安装与 globbing 模式匹配的所有扩展

CLI
quarkus extension add smallrye-*
Maven
./mvnw quarkus:add-extension -Dextensions='smallrye-*'

配置 javac 选项

Quarkus Maven 插件使用 javac,默认情况下,它会从 maven-compiler-plugin 中选择编译器标志传递给 javac

如果您需要自定义插件使用的编译器标志,例如在 开发模式中,请向 plugin 块添加一个 configuration 部分,并设置 compilerArgs 属性,就像配置 maven-compiler-plugin 一样。您还可以设置 sourcetargetjvmArgs。例如,将 --enable-preview 传递给 JVM 和 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。

为此,您可以使用 MAVEN_OPTS

CLI
MAVEN_OPTS='--enable-preview' quarkus build
Maven
MAVEN_OPTS='--enable-preview' ./mvnw install

或者,您可以简单地在项目的根目录中创建文件 .mvn/jvm.config:并且您放入该文件中的任何选项都将被 Maven 拾取,而无需设置 MAVEN_OPTS

开发模式

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

CLI
quarkus dev
Maven
./mvnw quarkus:dev

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

开发模式启用带有后台编译的热部署,这意味着当您修改 Java 文件或资源文件并刷新浏览器时,这些更改将自动生效。这也适用于资源文件,例如配置文件。刷新浏览器的操作会触发工作区的扫描,如果检测到任何更改,则 Java 文件将被编译,应用程序将被重新部署,然后您的请求将由重新部署的应用程序提供服务。如果编译或部署存在任何问题,错误页面会通知您。

CTRL+C 停止应用程序。

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

CLI
quarkus dev -DdebugHost=0.0.0.0
Maven
./mvnw quarkus:dev -DdebugHost=0.0.0.0

远程开发模式

可以使用远程开发模式,以便您可以在容器环境中(例如 OpenShift)运行 Quarkus,并且可以立即看到对本地文件所做的更改。

这允许您在实际运行应用程序的同一环境中进行开发,并可以访问相同的服务。

请勿在生产中使用此功能。这应该仅在开发环境中使用。您不应该在开发模式下运行生产应用程序。

为此,您必须使用 mutable-jar 格式构建可变应用程序。在 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 这告诉 Quarkus 使用 mutable-jar 格式。可变应用程序还包括 Quarkus 的部署时部分,因此它们占用更多的磁盘空间。如果正常运行,它们的启动速度与不可变应用程序一样快,并且使用相同的内存,但是也可以在开发模式下启动它们。
2 用于保护远程端和本地端之间通信的密码。
3 您的应用程序将在开发模式下运行的 URL。这仅在本地端需要,因此您可能希望将其从属性文件中删除,并将其指定为命令行上的系统属性。

然后,以构建常规 Quarkus jar 的相同方式构建 mutable-jar,即通过发出

CLI
quarkus build
Maven
./mvnw install

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

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

远程端不需要包含 Maven 或任何其他开发工具。使用新的 Quarkus 应用程序生成的常规 fast-jar Dockerfile 就是您所需要的。如果您使用裸机启动 Quarkus runner jar,请勿尝试运行常规开发模式。

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

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

现在,每次刷新浏览器时,您都应该在远程应用程序中立即看到您在本地所做的任何更改。这是通过基于 HTTP 的长轮询传输完成的,该传输将通过 HTTP 调用同步您的本地工作区和远程应用程序。

如果您不想使用 HTTP 功能,那么您可以简单地运行 remote-dev 命令而不指定 URL。在这种模式下,该命令将不断地重建本地应用程序,因此您可以使用 odo 或 rsync 等外部工具来同步到远程应用程序。

所有配置选项如下所示

构建时固定的配置属性 - 所有其他配置属性都可以在运行时覆盖

配置属性

类型

默认

是否应启用实时重新加载功能。

环境变量:QUARKUS_LIVE_RELOAD_ENABLED

显示更多

布尔值

true

Quarkus 是否应启用其能力,以便在对类的更改与 JVM Instrumentation 兼容时不进行完全重启。

如果将其设置为 true,Quarkus 将在可能的情况下执行类重定义。

环境变量:QUARKUS_LIVE_RELOAD_INSTRUMENTATION

显示更多

布尔值

false

要监视更改的其他资源文件的名称,在更改时触发重新加载。支持目录。

环境变量:QUARKUS_LIVE_RELOAD_WATCHED_RESOURCES

显示更多

字符串列表

用于连接到远程开发模式应用程序的密码

环境变量:QUARKUS_LIVE_RELOAD_PASSWORD

显示更多

字符串

用于连接到远程开发模式应用程序的 URL

环境变量:QUARKUS_LIVE_RELOAD_URL

显示更多

字符串

等待远程开发连接或重新连接的时间量

环境变量:QUARKUS_LIVE_RELOAD_CONNECT_TIMEOUT

显示更多

Duration 

30S

连接到远程开发的服务器端时,在尝试之间等待的时间量

环境变量:QUARKUS_LIVE_RELOAD_RETRY_INTERVAL

显示更多

Duration 

2S

连接到远程开发的服务器端时,最大尝试次数

环境变量:QUARKUS_LIVE_RELOAD_RETRY_MAX_ATTEMPTS

显示更多

整数

10

关于 Duration 格式

要编写 duration 值,请使用标准的 java.time.Duration 格式。有关更多信息,请参阅 Duration#parse() Java API 文档

您还可以使用简化的格式,以数字开头

  • 如果该值仅为一个数字,则表示以秒为单位的时间。

  • 如果该值是一个数字后跟 ms,则表示以毫秒为单位的时间。

在其他情况下,简化格式将被转换为 java.time.Duration 格式以进行解析

  • 如果该值是一个数字后跟 hms,则在其前面加上 PT

  • 如果该值是一个数字后跟 d,则在其前面加上 P

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

扩展提供的开发模式 Java 选项

某些扩展可能会提供预配置的 Java 选项,这些选项应添加到以开发模式启动应用程序的命令行中。

假设应用程序中有几个扩展 quarkus-bluequarkus-red 提供了开发模式的 Java 选项。日志可能如下所示

[DEBUG] [io.quarkus.deployment.dev.DevModeCommandLineBuilder] (main) Adding JVM options from org.acme:quarkus-red::jar
[DEBUG] [io.quarkus.deployment.dev.DevModeCommandLineBuilder] (main)   add-opens: [java.base/java.io=ALL-UNNAMED, java.base/java.nio=ALL-UNNAMED]
[DEBUG] [io.quarkus.deployment.dev.DevModeCommandLineBuilder] (main) Adding JVM options from org.acme:quarkus-blue::jar
[DEBUG] [io.quarkus.deployment.dev.DevModeCommandLineBuilder] (main)   enable-native-access: [ALL-UNNAMED]
[DEBUG] [io.quarkus.deployment.dev.DevModeCommandLineBuilder] (main)   add-modules: [jdk.incubator.vector]
[DEBUG] [io.quarkus.deployment.dev.DevModeCommandLineBuilder] (main)   enable-preview: []
[DEBUG] Launching JVM with command line: /home/<username>/jdk/bin/java -Dquarkus-internal.serialized-app-model.path=/home/<username>/app/target/quarkus/bootstrap/dev-app-model.dat -javaagent:/home/<username>/.m2/repository/io/quarkus/quarkus-class-change-agent/{quarkus-version}/quarkus-class-change-agent-{quarkus-version}.jar -XX:TieredStopAtLevel=1 -agentlib:jdwp=transport=dt_socket,address=localhost:5005,server=y,suspend=n --add-opens java.base/java.io=ALL-UNNAMED --add-opens java.base/java.nio=ALL-UNNAMED --enable-native-access=ALL-UNNAMED --add-modules=jdk.incubator.vector --enable-preview -Djava.util.logging.manager=org.jboss.logmanager.LogManager -jar /home/<username>/app/target/acme-app-dev.jar

用户可以选择通过配置 disableAll 参数来禁用扩展提供的所有 Java 选项,例如

            <plugin>
                <groupId>${quarkus.platform.group-id}</groupId>
                <artifactId>quarkus-maven-plugin</artifactId>
                <version>${quarkus.platform.version}</version>
                <configuration>
                    <extensionJvmOptions>
                        <disableAll>true</disableAll>
                    </extensionJvmOptions>
                </configuration>
            </plugin>

或者通过配置 Maven 坐标模式来禁用特定扩展提供的 Java 选项,例如

            <plugin>
                <groupId>${quarkus.platform.group-id}</groupId>
                <artifactId>quarkus-maven-plugin</artifactId>
                <version>${quarkus.platform.version}</version>
                <configuration>
                    <extensionJvmOptions>
                        <disableFor>
                            <extension>org.acme:quarkus-red</extension>
                        </disableFor>
                    </extensionJvmOptions>
                </configuration>
            </plugin>

使用此配置,日志将如下所示

[DEBUG] [io.quarkus.deployment.dev.DevModeCommandLineBuilder] (main) Adding JVM options from org.acme:quarkus-blue::jar
[DEBUG] [io.quarkus.deployment.dev.DevModeCommandLineBuilder] (main)   enable-native-access: [ALL-UNNAMED]
[DEBUG] [io.quarkus.deployment.dev.DevModeCommandLineBuilder] (main)   add-modules: [jdk.incubator.vector]
[DEBUG] [io.quarkus.deployment.dev.DevModeCommandLineBuilder] (main)   enable-preview: []
[DEBUG] Launching JVM with command line: /home/<username>/jdk/bin/java -Dquarkus-internal.serialized-app-model.path=/home/<username>/app/target/quarkus/bootstrap/dev-app-model.dat -javaagent:/home/<username>/.m2/repository/io/quarkus/quarkus-class-change-agent/{quarkus-version}/quarkus-class-change-agent-{quarkus-version}.jar -XX:TieredStopAtLevel=1 -agentlib:jdwp=transport=dt_socket,address=localhost:5005,server=y,suspend=n --enable-native-access=ALL-UNNAMED --add-modules=jdk.incubator.vector --enable-preview -Djava.util.logging.manager=org.jboss.logmanager.LogManager -jar /home/<username>/app/target/acme-app-dev.jar

调试

在开发模式下,Quarkus 默认启动时启用调试模式,监听端口 5005 而不挂起 JVM。

可以通过为 debug 系统属性提供以下值之一来更改此行为

  • false - JVM 将以禁用调试模式启动

  • true - JVM 在调试模式下启动,并将监听端口 5005

  • client - JVM 将以客户端模式启动,并尝试连接到 localhost:5005

  • {port} - JVM 在调试模式下启动,并将监听 {port}

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

  • ytrue - 调试模式 JVM 启动被挂起

  • nfalse - 调试模式 JVM 启动时不挂起

您还可以使用以下命令在调试模式下运行带有挂起 JVM 的 Quarkus 应用程序

CLI
quarkus dev -Dsuspend -Ddebug
Maven
./mvnw quarkus:dev -Dsuspend -Ddebug

然后,将您的调试器附加到 localhost:5005

导入到您的 IDE 中

一旦您有了 生成的项目,您就可以将其导入到您喜欢的 IDE 中。唯一的要求是能够导入 Maven 项目。

Eclipse

在 Eclipse 中,单击:File → Import。在向导中,选择:Maven → Existing Maven Project。在下一个屏幕上,选择项目的根位置。下一个屏幕列出找到的模块;选择生成的项目并单击 Finish。完成!

在一个单独的终端中,运行

CLI
quarkus dev
Maven
./mvnw quarkus:dev

并享受高效的环境。

IntelliJ IDEA

在 IntelliJ IDEA 中

  1. 从 IntelliJ IDEA 内部选择 File → New → Project From Existing Sources…​,或者如果您在欢迎对话框中,选择 Import project

  2. 选择项目根目录

  3. 选择 Import project from external modelMaven

  4. 多次单击 Next(如果需要,请查看不同的选项)

  5. 在最后一个屏幕上单击 Finish

在一个单独的终端或嵌入式终端中,运行

CLI
quarkus dev
Maven
./mvnw quarkus:dev

享受!

Apache NetBeans

在 NetBeans 中

  1. 选择 File → Open Project

  2. 选择项目根目录

  3. 单击 Open Project

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

CLI
quarkus dev
Maven
./mvnw quarkus:dev

享受!

Visual Studio Code

在 VS Code 中打开项目目录。如果您安装了 Java Extension Pack(将一组 Java 扩展分组在一起),则该项目将作为 Maven 项目加载。

记录 Quarkus 应用程序构建类路径树

通常,可以使用 mvn dependency:tree 命令显示应用程序(这是一个 Maven 项目)的依赖项。但是,对于 Quarkus 应用程序,此命令将仅列出应用程序的运行时依赖项。鉴于 Quarkus 构建过程将应用程序中使用的扩展的部署依赖项添加到原始应用程序类路径中,因此了解哪些依赖项和哪些版本最终会出现在构建类路径中可能很有用。幸运的是,quarkus Maven 插件包含 dependency-tree 目标,该目标显示应用程序的构建依赖项树。

在您的项目上执行 ./mvnw quarkus:dependency-tree 应该会导致类似于以下内容的输出

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

该目标接受以下可选参数

  • mode - 默认值为 prod,即生产构建依赖项树。或者,它接受值 test 以显示测试依赖项树,并接受 dev 以显示开发模式依赖项树;

  • outputFile - 指定将依赖项树持久保存到的文件;

  • appendOutput - 默认值为 false,指示是否应将命令的输出追加到使用 outputFile 参数指定的文件中,或者是否应覆盖它。

下载 Maven 构件依赖项以进行脱机开发和测试

Quarkus 扩展依赖项分为最终出现在应用程序运行时类路径上的运行时扩展依赖项和 Quarkus 仅在应用程序构建时解析的部署(或构建时)扩展依赖项,以创建构建类路径。应用程序开发人员应该仅表达对 Quarkus 扩展的运行时构件的依赖。因此,部署扩展依赖项对于不了解 Quarkus 扩展依赖项模型的 Maven 插件(例如 maven-dependency-plugingo-offline-maven-plugin 等)不可见。这意味着无法使用这些插件来预先下载所有应用程序依赖项,以便以后在脱机模式下构建和测试应用程序。

为了启用脱机构建和测试 Quarkus 应用程序的用例,quarkus-maven-plugin 包含 go-offline 目标,可以从命令行调用该目标,如下所示

./mvnw quarkus:go-offline

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

构建本机可执行文件

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

确保已配置 GRAALVM_HOME 并指向 JDK 21 的 GraalVM 的最新版本。验证您的 pom.xml 是否具有正确的 native 配置文件,如 Maven 配置所示。

使用以下命令创建原生可执行文件

CLI
quarkus build --native
Maven
./mvnw install -Dnative

原生可执行文件将出现在 target/ 中。

要在原生可执行文件上运行集成测试,请确保已配置正确的 Maven 插件,并启动 verify 目标。

$ ./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=https://: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: https://: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

...

构建容器友好的可执行文件

原生可执行文件将特定于您的操作系统。要创建将在容器中运行的可执行文件,请使用以下命令

CLI
quarkus build --native -Dquarkus.native.container-build=true
Maven
./mvnw install -Dnative -Dquarkus.native.container-build=true

生成的可执行文件将是一个 64 位 Linux 可执行文件,因此根据您的操作系统,它可能不再可运行。但是,这不是问题,因为我们将把它复制到 Docker 容器中。请注意,在这种情况下,构建本身也在 Docker 容器中运行,因此您不需要在本地安装 GraalVM。

默认情况下,原生可执行文件将使用 quay.io/quarkus/ubi9-quarkus-mandrel-builder-image:jdk-21 Docker 镜像生成。

如果您想使用不同的 Docker 镜像构建原生可执行文件(例如,使用不同的 GraalVM 版本),请使用 -Dquarkus.native.builder-image=<image name> 构建参数。

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

从 Quarkus 3.19 开始,builder 镜像基于 UBI 9,因此,如果您想在容器中运行原生可执行文件,则需要 UBI 9 基础镜像。您可以通过将 quarkus.native.builder-image 属性设置为 quay.io 存储库中的可用镜像之一来切换回 UBI 8。例如,`quay.io/quarkus/ubi-quarkus-mandrel-builder-image:jdk-21 使用 UBI 8,因此生成的原生可执行文件将与 UBI 8 基础镜像兼容。

Maven 配置

如果您尚未使用 项目脚手架,请将以下元素添加到您的 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 禁用在所有构建上运行集成测试(测试名称 *IT 并使用 @QuarkusIntegrationTest 注释)。要始终运行这些测试,请删除此属性,将其值设置为 false,或在运行构建时在命令行上设置 -DskipITs=false
如下所述,这在 native 配置文件中被覆盖。
2 可以选择使用 BOM 文件来省略不同 Quarkus 依赖项的版本。
3 使用 Quarkus Maven 插件,该插件将挂接到构建过程中。
4 启用 Maven 插件扩展将注册一个 Quarkus MavenLifecycleParticipant,这将确保在构建期间使用的 Quarkus 类加载器已正确关闭。在 generate-codegenerate-code-tests 目标期间,Quarkus 应用程序引导程序被初始化并在 build 目标中重新使用(实际上构建和打包了生产应用程序)。Quarkus 类加载器将在 quarkus-maven-pluginbuild 目标中正确关闭。但是,如果在 generate-codegenerate-code-testsbuild 之间的构建失败,则 Quarkus 增强类加载器将不会正确关闭,这可能会导致在 Windows OS 上锁定恰好位于类路径上的 JAR 文件。
5 将系统属性添加到 maven-surefire-plugin
只有当您在 ${maven.home}/conf/settings.xml 中有自定义配置时,才需要 maven.home
6 如果您想使用集成测试来测试由您的构建生成的构件,请添加以下插件配置。测试名称 *IT 并使用 @QuarkusIntegrationTest 注释的测试将针对由构建生成的构件(JAR 文件、容器镜像等)运行。有关更多信息,请参阅 集成测试指南
只有当您在 ${maven.home}/conf/settings.xml 中有自定义配置时,才需要 maven.home
7 为原生可执行文件构建使用特定的 native 配置文件。
8 启用 native 包类型。因此,构建将生成一个原生可执行文件。
9 在构建原生镜像时始终运行集成测试(测试名称 *IT 并使用 @QuarkusIntegrationTest 注释)。
如果您不希望在构建原生镜像时运行集成测试,只需完全删除此属性或将其值设置为 true

使用 fast-jar

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

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

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

为了成功运行生成的 jar,您需要拥有 quarkus-app 目录的全部内容。如果任何文件丢失,应用程序将无法启动或可能无法正常运行。
fast-jar 打包导致创建一个启动速度稍快且消耗内存略少的构件,而不是传统的 Quarkus jar,因为它具有有关哪个依赖 jar 包含类和资源的索引信息。因此,在加载类或资源时,它可以避免对类路径上可能存在的每个 jar 进行查找,而传统的 jar 需要这样做。

Uber-Jar 创建

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

原始 jar 仍将出现在 target 目录中,但它将被重命名以包含 .original 后缀。

在构建 Uber-Jar 时,您可以使用 quarkus.package.ignored-entries 配置选项指定要从生成的 jar 中排除的条目,这会采用要忽略的条目的逗号分隔列表。

Uber-Jar 创建默认排除可能存在于应用程序依赖项中的 签名文件

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

Uber-Jar 文件名后缀

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

将 Uber-Jar 文件作为主要项目构件附加

只要通过将后缀(例如 runner)附加到原始项目 JAR 文件名来创建 Uber-Jar 文件名,Uber-Jar 文件名后缀也将用作 Uber-Jar 构件的 Maven 构件分类器。有两种方法可以将 Uber-Jar 作为主要项目构件附加(没有分类器)

  1. 设置 quarkus.package.jar.add-runner-suffix=false,这将禁用文件后缀的添加,并通过这样做,将替换文件系统上的原始项目 JAR;

  2. quarkus:build 目标的 attachRunnerAsMainArtifact 参数设置为 true

使用多模块项目

默认情况下,Quarkus 不会发现另一个模块内的 CDI bean。

在多模块项目中为模块启用 CDI bean 发现的最佳方法是包含 jandex-maven-plugin,除非它是已经配置了 quarkus-maven-plugin 的主应用程序模块,在这种情况下,它将自动被索引。

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

有关此主题的更多信息,请参阅 CDI 指南的 Bean 发现部分。

Maven 测试插件配置

上面显示的 maven-surefire-pluginmaven-failsafe-plugin 配置在大多数情况下都可以正常工作。但是,在某些情况下可能需要额外的配置。

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

Maven 用户设置

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

        <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>

通过经过身份验证的 HTTPS 访问远程存储库

如果远程 Maven 存储库需要 经过身份验证的 HTTPS 访问配置,则需要将某些或所有以下属性传递给测试插件

        <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>

使用特定的配置配置文件构建

Quarkus 支持 配置配置文件,以便根据目标环境提供特定的配置。

可以使用以下类型的命令,通过系统属性 quarkus.profile 直接在 Maven 构建的命令中提供配置文件

CLI
quarkus build quarkus deploy openshift
Maven
./mvnw install -Dquarkus.profile=profile-name-here

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

按优先级顺序(优先级最高的在前)

1. 在 Quarkus Maven 插件配置中设置的系统属性
<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 此项目的默认配置配置文件为 prod-aws
2. Quarkus Maven 插件配置属性
<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 此项目的默认配置配置文件为 prod-aws
3. 项目属性
<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 此项目的默认配置配置文件为 prod-aws
无论选择哪种方法,配置文件仍然可以使用 quarkus.profile 系统属性或 QUARKUS_PROFILE 环境变量覆盖。

从单个模块构建多个构件

在某些特定的用例中,从同一模块构建应用程序的多个构件可能很有趣。一个典型的例子是当您想使用不同的配置配置文件构建您的应用程序时。

在这种情况下,可以根据需要在 Quarkus Maven 插件配置中添加尽可能多的执行。

下面是一个 Quarkus Maven 插件配置的示例,它将生成同一应用程序的两个构建版本:一个使用 prod-oracle profile,另一个使用 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 插件第一次执行的默认配置 profile 是 prod-oracle
2 插件第一次执行的输出目录设置为 oracle-quarkus-app 而不是 quarkus-app,以便拥有一个专用目录。
3 插件第二次执行的默认配置 profile 是 prod-postgresql
4 插件第二次执行的输出目录设置为 postgresql-quarkus-app 而不是 quarkus-app,以便拥有一个专用目录。
使用上面的配置,两个 profile 构建都将使用相同的依赖项,因此如果我们在应用程序中添加了对 Oracle 和 PostgreSQL 驱动程序的依赖项,则这两个驱动程序都将出现在两个构建中。

为了将 profile 特定的依赖项与其他 profile 隔离开来,可以将 JDBC 驱动程序作为可选依赖项添加到应用程序中,但配置为包含在每个需要它们的 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">
  ...
  <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 PostgreSQL 的 JDBC 驱动程序被定义为可选依赖项
2 出于向后兼容性的原因,有必要显式指出需要过滤可选依赖项。
3 最终构件中预计只有与 PostgreSQL 的 JDBC 驱动程序相对应的可选依赖项。
如果在 quarkus.package.jar.included-optional-dependencies 标签中声明多个可选依赖项,请确保它们用 , 分隔(例如 org.postgresql:postgresql::jar,com.foo:bar::jar)。

配置项目输出

有几个配置选项可以定义项目构建的输出。 它们在 application.properties 中提供,与其他任何配置属性一样。

这些属性如下所示

构建时固定的配置属性 - 所有其他配置属性都可以在运行时覆盖

配置属性

类型

默认

如果设置为 false,则不会生成 JAR。

环境变量: QUARKUS_PACKAGE_JAR_ENABLED

显示更多

布尔值

true

要使用的 JAR 输出类型。

环境变量: QUARKUS_PACKAGE_JAR_TYPE

显示更多

fast-jar“快速 JAR”打包类型。, uber-jar“Uber-JAR”打包类型。, mutable-jar“可变 JAR”打包类型(用于远程开发模式)。, legacy-jar“传统 JAR”打包类型。 这对应于 Quarkus 1.12 版本之前使用的打包类型。

fast-jar“快速 JAR”打包类型。

是否压缩创建的 jar。 构建 Native Image 时不使用此设置

环境变量: QUARKUS_PACKAGE_JAR_COMPRESS

显示更多

布尔值

true

指定是否应将 Implementation 信息包含在 runner jar 的 MANIFEST.MF 中。

环境变量: QUARKUS_PACKAGE_JAR_MANIFEST_ADD_IMPLEMENTATION_ENTRIES

显示更多

布尔值

true

要添加到 MANIFEST.MF 文件的主要部分的自定义 manifest 属性。 用户定义属性的示例:quarkus.package.jar.manifest.attributes."Entry-key1"=Value1 quarkus.package.jar.manifest.attributes."Entry-key2"=Value2

环境变量: QUARKUS_PACKAGE_JAR_MANIFEST_ATTRIBUTES__ATTRIBUTE_NAME_

显示更多

Map<String,String>

要添加到 MANIFEST.MF 文件的自定义 manifest 部分。 用户定义属性的示例:quarkus.package.jar.manifest.sections."Section-Name"."Entry-Key1"=Value1 quarkus.package.jar.manifest.sections."Section-Name"."Entry-Key2"=Value2

环境变量: QUARKUS_PACKAGE_JAR_MANIFEST_SECTIONS__SECTION_NAME_

显示更多

Map<String,Map<String,String>>

不应复制到输出构件的文件。

环境变量: QUARKUS_PACKAGE_JAR_USER_CONFIGURED_IGNORED_ENTRIES

显示更多

字符串列表

已定义为可选的所有依赖项的列表,以包含到应用程序的最终包中。 每个可选依赖项都需要以以下格式表示

groupId:artifactId[:[classifier][:[type]]]

分类器和类型是可选的(请注意,括号 ([]) 表示可选性,而不是语法规范的一部分)。 组 ID 和构件 ID 必须存在且非空。

如果缺少类型,则假定构件的类型为 jar

此参数是可选的;如果不存在,则不会将可选依赖项包含到应用程序的最终包中。

出于向后兼容性的原因,默认情况下会忽略此参数,可以通过将参数 quarkus.package.jar.filter-optional-dependencies 设置为 true 来启用它。

此参数旨在用于已配置多构建以避免获得带有未使用依赖项的最终包的模块中。

环境变量: QUARKUS_PACKAGE_JAR_INCLUDED_OPTIONAL_DEPENDENCIES

显示更多

GACT 列表

指示是否应过滤掉可选依赖项的标志。

此参数旨在用于已配置多构建以避免获得带有未使用依赖项的最终包的模块中。

环境变量: QUARKUS_PACKAGE_JAR_FILTER_OPTIONAL_DEPENDENCIES

显示更多

布尔值

false

指示生成的 JAR 文件是否应附加 runner 后缀。 仅适用于 JarType#UBER_JAR uber-JAR 输出类型。 如果禁用,则由原始构建系统(Maven、Gradle 等)构建的 JAR 将被 Quarkus 构建的 uber-JAR 替换。

环境变量: QUARKUS_PACKAGE_JAR_ADD_RUNNER_SUFFIX

显示更多

布尔值

true

是否自动化 AppCDS 的创建。 在构建和运行应用程序时必须注意使用完全相同的 JVM 版本。

环境变量: QUARKUS_PACKAGE_JAR_APPCDS_ENABLED

显示更多

布尔值

false

启用 AppCDS 生成时,如果设置了此属性,则用于生成 AppCDS 文件的 JVM 将是容器映像中存在的 JVM。 构建器映像应在其 PATH 上具有 'java' 二进制文件。 当运行时要使用的 JVM 与用于构建 jar 的 JVM 版本不完全相同时,此标志非常有用。 请注意,仅当 quarkus.package.jar.appcds.enabled=true 时才会查询此属性,并且它需要在构建期间可以使用 Docker。

环境变量: QUARKUS_PACKAGE_JAR_APPCDS_BUILDER_IMAGE

显示更多

字符串

如果可用,是否应在容器中运行 AppCDS 档案的创建。

通常,如果可以自动确定用于创建 AppCDS 档案的合适容器映像,或者如果使用 quarkus.<package-type>.appcds.builder-image 设置显式设置了一个容器映像,则通过运行映像中包含的 JDK 作为容器来生成 AppCDS 档案。

如果将此选项设置为 false,则不会使用容器来生成 AppCDS 档案。 相反,用于构建应用程序的 JDK 也用于创建档案。 请注意,在这种情况下,必须使用完全相同的 JDK 版本来运行应用程序。

如果将 quarkus.package.jar.appcds.enabled 设置为 false,则忽略。

环境变量: QUARKUS_PACKAGE_JAR_APPCDS_USE_CONTAINER

显示更多

布尔值

true

是否使用 JDK 24 中引入的 Ahead-of-Time Class Loading & Linking

环境变量: QUARKUS_PACKAGE_JAR_APPCDS_USE_AOT

显示更多

布尔值

false

这是一个高级选项,仅在开发模式下生效。

如果指定了此选项,则将在 jar 发行版中创建一个具有此名称的目录。 用户可以将 jar 文件放在此目录中,并且在执行重新增强时,将处理这些 jar 文件并将其添加到类路径中。

请注意,在执行重新增强之前,将忽略这些 jar 文件,并且如果更新了这些 jar 文件,则应再次重新增强应用程序。

环境变量: QUARKUS_PACKAGE_JAR_USER_PROVIDERS_DIRECTORY

显示更多

字符串

如果此选项为 true,则组成此映像的所有构件的坐标列表将包含在 quarkus-app 目录中。 漏洞扫描程序可以使用此列表来确定您的应用程序是否具有任何易受攻击的依赖项。 仅支持 JarType#FAST_JAR fast JARJarType#MUTABLE_JAR mutable JAR 输出类型。

环境变量: QUARKUS_PACKAGE_JAR_INCLUDE_DEPENDENCY_LIST

显示更多

布尔值

true

启用将生成的和转换的字节码反编译到文件系统中。

环境变量: QUARKUS_PACKAGE_JAR_DECOMPILER_ENABLED

显示更多

布尔值

false

用于保存反编译输出的目录。

相对路径被理解为相对于构建目录。

环境变量: QUARKUS_PACKAGE_JAR_DECOMPILER_OUTPUT_DIRECTORY

显示更多

字符串

decompiler

如果本地不存在,则将反编译工具保存到的目录。

环境变量: QUARKUS_PACKAGE_JAR_DECOMPILER_JAR_DIRECTORY

显示更多

字符串

${user.home}/.quarkus

应用程序的入口点。 这可以是带有 main 方法的标准 Java 类的完全限定名称,也可以是 io.quarkus.runtime.QuarkusApplication

如果您的应用程序具有使用 io.quarkus.runtime.annotations.QuarkusMain 注释的 main 类,则也可以引用注释中给出的名称,以避免需要在配置中指定完全限定名称。

环境变量: QUARKUS_PACKAGE_MAIN_CLASS

显示更多

字符串

应在其中写入输出包的目录。 相对于构建系统的目标目录解析相对路径。

环境变量: QUARKUS_PACKAGE_OUTPUT_DIRECTORY

显示更多

path

最终构件的名称,不包括后缀和文件扩展名。

环境变量: QUARKUS_PACKAGE_OUTPUT_NAME

显示更多

字符串

将此开关设置为 true 将导致 Quarkus 将转换后的应用程序字节码写入构建工具的输出目录。 这对于需要扫描应用程序字节码的构建后工具(例如,脱机代码覆盖率工具)非常有用。

例如,如果使用 Maven,启用此功能将导致 target/classes 中的类被 Quarkus 转换后的类替换。

但是,应非常谨慎地执行此操作,并且仅当在干净的环境中完成后续构建时(即,构建工具的输出目录已完全清除)。

环境变量: QUARKUS_PACKAGE_WRITE_TRANSFORMED_BYTECODE_TO_BUILD_OUTPUT

显示更多

布尔值

false

应用于 runner 构件基本文件名的后缀。

环境变量: QUARKUS_PACKAGE_RUNNER_SUFFIX

显示更多

字符串

-runner

JVM 模式下的自定义测试配置 profile

默认情况下,Quarkus 在 JVM 模式下运行测试时使用 test 配置 profile。 如果您不熟悉 Quarkus 配置 profile,您需要了解的所有内容都在 配置 Profile 文档中进行了解释。

但是,可以使用下面显示的 Maven Surefire 和 Maven Failsafe 配置为您的测试使用自定义配置 profile。 如果您需要使用特定的数据库(而不是您的默认测试数据库)运行某些测试,这可能很有用。

<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 foo 配置 profile 将用于运行测试。

目前无法在 Native 模式下使用自定义测试配置 profile。 Native 测试始终使用 prod profile 运行。

Bootstrap Maven 属性

Quarkus bootstrap 包含一个 Maven 解析器实现,该实现用于解析应用程序运行时和构建时依赖项。 Quarkus Maven 解析器从启动构建、测试或开发模式的同一 Maven 命令行初始化。 通常,无需为其添加任何额外的配置。 但是,在某些情况下,可能需要一个额外的配置选项才能正确解析测试或开发模式或 IDE 中的应用程序依赖项。

例如,Maven 测试插件(例如 surefirefailsafe)默认情况下不会将构建系统属性传播到正在运行的测试。 这意味着 Maven CLI 设置的某些系统属性对于为测试初始化的 Quarkus Maven 解析器不可用,这可能会导致使用与主 Maven 构建不同的设置来解析测试依赖项。

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

属性名称 默认值 描述

maven.home

MAVEN_HOME 环境变量

Maven home 目录用于解析全局设置文件,除非已使用 -gs 参数在命令行中显式提供该文件

maven.settings

~/.m2/settings.xml

除非已使用 -s 参数提供自定义设置文件,否则可以使用此属性将解析器指向自定义 Maven 设置文件

maven.repo.local

~/.m2/repository

如果此属性与默认目录和 settings.xml 中指定的目录不同,则可以使用此属性配置自定义本地 Maven 存储库目录

maven.top-level-basedir

none

此属性可能有助于 Maven 解析器识别工作区中的顶级 Maven 项目。 默认情况下,Maven 解析器将通过导航父模块 POM 关系来发现项目的workspace。 但是,可能存在使用聚合器模块的项目布局,该模块不会显示为其模块的父模块。 在这种情况下,此属性将帮助 Quarkus Maven 解析器正确发现工作区。

quarkus.bootstrap.effective-model-builder

false

默认情况下,Quarkus Maven 解析器在发现项目布局时直接读取项目的 POM。 虽然在大多数情况下它可以很好地工作并且相对较快,但读取原始 POM 有其局限性。 例如,如果 POM 在 profile 中包含模块,则不会发现这些模块。 此系统属性支持基于有效 POM 模型(而不是原始 POM 模型)的项目布局发现,这些模型已正确插值。 默认情况下未启用此选项的原因是它可能看起来非常耗时,这可能会增加 CI 测试时间。 在找到可以默认使用的更好方法之前,需要它的项目应启用此选项。

quarkus.bootstrap.legacy-model-resolver

false

系统POM 属性可用于启用旧版 ApplicationModel 解析器实现。 该属性是在 Quarkus 3.19.0 中引入的,一旦已知对旧版实现没有需求,就会将其删除。

上述这些系统属性可以添加到,例如,surefire 和/或 failsafe 插件配置中,如下所示

<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 将 Maven CLI 设置的 maven.home 系统属性传播到测试
2 为测试设置 Maven 本地存储库目录
3 为测试设置 Maven 设置文件
4 指向测试的顶级项目目录
5 启用基于有效 POM 的项目布局发现

顶级项目目录与多模块项目目录

在 Maven 中,似乎存在顶级项目的概念(作为项目属性 ${session.topLevelProject.basedir.absolutePath} 公开)和多模块项目目录(作为属性 ${maven.multiModuleProjectDirectory} 提供)。 这些目录可能并不总是匹配!

maven.multiModuleProjectDirectory 旨在由 Maven 代码本身咨询,而不是用户代码依赖的东西。 因此,如果您发现它有用,请自行承担使用它的风险!

${maven.multiModuleProjectDirectory} 将解析为第一个包含 .mvn 目录作为其子目录的目录,从启动 mvn 命令的当前目录(或使用 -f 参数指定的目录)开始,在工作区文件系统树中向上查找。 但是,如果未找到 .mvn 目录,则 ${maven.multiModuleProjectDirectory} 将指向启动 mvn 命令的目录(或使用 -f 参数定位的目录)。

${session.topLevelProject.basedir.absolutePath} 将指向启动 mvn 命令的目录,或者如果指定了 -f 参数,则指向使用 -f 参数定位的目录。

Quarkus 项目信息

Quarkus Maven 插件包含一个名为 info(当前标记为“实验性”)的目标,该目标记录有关项目的 Quarkus 特定信息,例如:导入的 Quarkus 平台 BOM 和在项目依赖项中找到的 Quarkus 扩展。 在多模块项目中,quarkus:info 将假定执行它的当前模块是应用程序的主模块。

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

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

[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:3.24.4: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]   io.quarkus.platform:quarkus-bom:pom:3.24.4
[INFO]   io.quarkus.platform:quarkus-camel-bom:pom:3.24.4
[INFO]
[INFO] Extensions from io.quarkus.platform:quarkus-bom: (2)
[INFO]   io.quarkus:quarkus-rest
[INFO]
[INFO] Extensions from io.quarkus.platform: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 平台 BOM(还将报告父 POM 导入的 BOM)
2 quarkus-bom 管理的直接 Quarkus 扩展依赖项
3 quarkus-camel-bom 管理的直接 Quarkus 扩展依赖项
4 不在 Quarkus BOM 中管理但在 Quarkus 扩展注册表中找到的直接 Quarkus 扩展依赖项
如果项目中存在不在 Quarkus 扩展注册表中找到的 Quarkus 扩展,quarkus:info 也会报告这些扩展,表明它们具有“未知来源”。

突出显示未对齐的版本

如果检测到基本的 Quarkus 依赖项版本未对齐,quarkus:info 还会突出显示它们。 例如,如果我们通过从依赖项中删除 camel-quarkus-rabbitmq 扩展并将 2.6.3.Final <version> 元素添加到由 quarkus-bom 管理的 quarkus-rest 依赖项来修改上面提到的项目,然后再次运行 quarkus:info,我们将看到类似

[INFO] --- quarkus-maven-plugin:3.24.4: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]   io.quarkus.platform:quarkus-bom:pom:3.24.4
[INFO]   io.quarkus.platform:quarkus-camel-bom:pom:3.24.4 | unnecessary (1)
[INFO]
[INFO] Extensions from io.quarkus.platform:quarkus-bom:
[INFO]   io.quarkus:quarkus-resteasy-reactive:2.6.3.Final | misaligned (2)
[INFO]
[INFO] Extensions from io.quarkus.platform: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 由于在项目依赖项中未找到它包含的任何 Quarkus 扩展,因此现在报告 quarkus-camel-bom 导入为“不必要”
2 现在报告 quarkus-resteasy-reactive 的版本 2.6.3.Final 与项目中导入的 Quarkus 平台 BOM 管理的版本未对齐,即 3.24.4

Quarkus 项目更新

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

在这一点上,quarkus:update 目标实际上并没有应用建议的更新,而是简单地报告它们是什么以及如何手动应用它们。
Quarkus Maven 插件版本当前未包含在更新报告中,但是计划在未来的版本中添加该版本。

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

假设我们有一个项目,其中包括 Kogito、Camel 和基于 Quarkus 2.7.1.Final 的 Quarkus 平台中提供的核心 Quarkus 扩展,则 quarkus:update 的输出将如下所示

[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:3.24.4: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: io.quarkus.platform:quarkus-bom:pom:2.7.1.Final -> 3.24.4
[INFO] Update: io.quarkus.platform:quarkus-camel-bom:pom:2.7.1.Final -> 3.24.4
1 当前推荐的 Quarkus 平台 BOM 更新列表
通常,将使用单个项目属性来管理所有 Quarkus 平台 BOM,但是该实现当前不够智能以指出这一点,并且将单独报告每个 BOM 的更新。

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

[INFO] Recommended Quarkus platform BOM updates: (1)
[INFO] Update: io.quarkus.platform:quarkus-bom:pom:2.7.1.Final -> 3.24.4
[INFO] Remove: io.quarkus.platform:quarkus-camel-bom:pom:2.7.1.Final (2)
[INFO]
[INFO] Extensions from io.quarkus.platform: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 项目当前推荐的 Quarkus 平台 BOM 更新列表
2 鉴于该项目不包含任何 Camel Quarkus 扩展,因此建议删除 BOM 导入
3 建议删除过时的 quarkus-resteasy-reactive 版本,以支持由 quarkus-bom 管理的版本
4 quarkus-prettytime 扩展的最新兼容版本

Quarkus 项目纠正

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

[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 版本更新。

相关内容