返回指南
编辑此页面

Quarkus 和 Gradle

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

创建新项目

要脚手架一个 Gradle 项目，您可以使用 Quarkus CLI 或 Quarkus Maven 插件

CLI
quarkus create app my-groupId:my-artifactId \
    --extensions=rest,rest-jackson \
    --gradle

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

Maven
mvn io.quarkus.platform:quarkus-maven-plugin:3.24.4:create \
    -DprojectGroupId=my-groupId \
    -DprojectArtifactId=my-artifactId \
    -Dextensions="rest,rest-jackson" \
    -DbuildTool=gradle
如果您只运行 mvn io.quarkus.platform:quarkus-maven-plugin:3.24.4:create，Maven 插件会要求用户输入。您可以通过向 Maven 命令传递 -B 来禁用此交互模式（并使用默认值）。
如果您更喜欢使用 Kotlin DSL，请使用 gradle-kotlin-dsl 而不是 gradle。

Quarkus 项目脚手架会自动在您的项目中安装 Gradle 包装器 (./gradlew)。

如果您更喜欢使用独立的 Gradle 安装，请使用 Gradle 8.14。

项目将在以提供的 artifactId 命名的目录中生成。

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

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

默认情况下，JVM 模式下的 Quarkus 测试使用 test 配置配置文件运行。如果您不熟悉 Quarkus 配置配置文件，您需要了解的一切都在 配置配置文件文档 中进行了说明。

然而，使用下面的 Gradle 构建配置，可以为您的测试使用自定义配置配置文件。如果您需要例如使用特定数据库（而不是默认测试数据库）运行某些测试，这将非常有用。

Groovy DSL
test {
    systemProperty "quarkus.test.profile", "foo" (1)
}
1 foo 配置配置文件将用于运行测试。
Kotlin DSL
tasks.test {
    systemProperty("quarkus.test.profile", "foo") (1)
}
1 foo 配置配置文件将用于运行测试。

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

处理扩展

在 Quarkus 项目中，您可以通过以下方式获取可用扩展的列表：

CLI
quarkus extension
Gradle
./gradlew listExtensions

您可以使用以下方式启用扩展：

CLI
quarkus extension add hibernate-validator
Gradle
./gradlew addExtension --extensions='hibernate-validator'

扩展通过逗号分隔的列表传递。

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

$ ./gradlew addExtension --extensions="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?
[...]

您可以安装匹配 glob 模式的所有扩展：

CLI
quarkus extension add smallrye-*
Gradle
./gradlew addExtension --extensions='smallrye-*'

开发模式

Quarkus 自带内置的开发模式。您可以使用以下命令启动它：

CLI
quarkus dev
Gradle
./gradlew --console=plain quarkusDev

请注意，如果以这种方式运行，连续测试体验将不如预期，因为 Gradle 作为守护进程运行，Quarkus 无法绘制“漂亮的”测试输出，因此会回退到仅记录输出。

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

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

按 CTRL+C 停止应用程序。

您可以更改开发环境运行的工作目录：

Groovy DSL
quarkusDev {
    workingDirectory = rootProject.layout.projectDirectory.asFile
}
Kotlin DSL
tasks.quarkusDev {
    workingDirectory = rootProject.layout.projectDirectory.asFile
}

默认情况下，quarkusDev 任务使用 compileJava 编译器选项。这些可以通过在任务中设置 compilerArgs 属性来覆盖。

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

CLI
quarkus dev -DdebugHost=0.0.0.0
Gradle
./gradlew --console=plain quarkusDev -DdebugHost=0.0.0.0

您还可以为开发环境添加环境变量：

Groovy DSL
quarkusDev {
    environmentVariables = [FOO_VALUE: 'abc', BAR_VALUE: 'def']
}
Kotlin DSL
tasks.quarkusDev {
    environmentVariables.set(mapOf("FOO_VALUE" to "abc", "BAR_VALUE" to "def"))
}

该插件还公开了一个 quarkusDev 配置。使用此配置声明依赖关系会将该依赖关系的用法限制在开发模式。quarkusDev 配置可以按如下方式使用：

Groovy DSL
dependencies {
    quarkusDev 'io.quarkus:quarkus-jdbc-h2'
}
Kotlin DSL
dependencies {
    quarkusDev("io.quarkus:quarkus-jdbc-h2")
}

远程开发模式

可以在远程使用开发模式，以便您可以在容器环境（如 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。这仅在本地端需要，因此您可能希望将其从属性文件中删除，并在命令行中将其指定为系统属性。

然后，mutable-jar 的构建方式与常规 Quarkus jar 相同，即通过发出以下命令：

CLI
quarkus build
Gradle
./gradlew build

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

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

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

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

./gradlew quarkusRemoteDev -Dquarkus.live-reload.url=http://my-remote-host:8080

现在，每次刷新浏览器时，您应该会立即看到在本地所做的任何更改在远程应用程序中可见。

所有配置选项如下所示：

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

配置属性

类型

默认

quarkus.live-reload.enabled

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

环境变量：QUARKUS_LIVE_RELOAD_ENABLED

显示更多

布尔值

true

quarkus.live-reload.instrumentation

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

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

环境变量：QUARKUS_LIVE_RELOAD_INSTRUMENTATION

显示更多

布尔值

false

quarkus.live-reload.watched-resources

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

环境变量：QUARKUS_LIVE_RELOAD_WATCHED_RESOURCES

显示更多

字符串列表

quarkus.live-reload.password

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

环境变量：QUARKUS_LIVE_RELOAD_PASSWORD

显示更多

字符串

quarkus.live-reload.url

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

环境变量：QUARKUS_LIVE_RELOAD_URL

显示更多

字符串

quarkus.live-reload.connect-timeout

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

环境变量：QUARKUS_LIVE_RELOAD_CONNECT_TIMEOUT

显示更多

Duration 

30S

quarkus.live-reload.retry-interval

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

环境变量：QUARKUS_LIVE_RELOAD_RETRY_INTERVAL

显示更多

Duration 

2S

quarkus.live-reload.retry-max-attempts

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

环境变量：QUARKUS_LIVE_RELOAD_RETRY_MAX_ATTEMPTS

显示更多

整数

10
关于 Duration 格式

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

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

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

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

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

  • 如果该值是一个数字后跟 h、m 或 s，则在其前面加上 PT。

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

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

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

假设应用程序中有几个扩展 quarkus-blue 和 quarkus-red，它们为开发模式提供了 Java 选项。日志可能看起来像这样：

[DEBUG] [io.quarkus.deployment.dev.DevModeCommandLineBuilder] Adding JVM options from org.acme:quarkus-blue::jar
[DEBUG] [io.quarkus.deployment.dev.DevModeCommandLineBuilder]   enable-native-access: [ALL-UNNAMED]
[DEBUG] [io.quarkus.deployment.dev.DevModeCommandLineBuilder]   add-modules: [jdk.incubator.vector]
[DEBUG] [io.quarkus.deployment.dev.DevModeCommandLineBuilder]   enable-preview: []
[DEBUG] [io.quarkus.deployment.dev.DevModeCommandLineBuilder] Adding JVM options from org.acme:quarkus-red::jar
[DEBUG] [io.quarkus.deployment.dev.DevModeCommandLineBuilder]   add-opens: [java.base/java.io=ALL-UNNAMED, java.base/java.nio=ALL-UNNAMED]
[INFO] [org.gradle.process.internal.DefaultExecHandle] Starting process 'command '/home/<username>/jdk/bin/java''. Working directory: /home/<username>/gradle-app/build/classes/java/main Command: /home/<username>/jdk/bin/java -Dquarkus.console.basic=true -Dio.quarkus.force-color-support=true -javaagent:/home/<username>/.m2/repository/io/quarkus/quarkus-class-change-agent/{quarkus-version}/quarkus-class-change-agent-{quarkus-version}.jar -Dquarkus-internal.serialized-app-model.path=/home/<username>/gradle-app/build/tmp/quarkusDev/quarkus-app-model.dat -Dquarkus-internal-test.serialized-app-model.path=/home/<username>/gradle-app/build/tmp/quarkusDev/quarkus-app-test-model.dat -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>/gradle-app/build/gradle-app-dev.jar

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

Groovy DSL
quarkusDev {
    extensionJvmOptions{
        disableAll = true
    }
}
Kotlin DSL
tasks.quarkusDev {
    extensionJvmOptions{
        setDisableAll(true)
    }
}

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

Groovy DSL
quarkusDev {
    extensionJvmOptions{
        disableFor = ["org.acme:quarkus-red"]
    }
}
Kotlin DSL
tasks.quarkusDev {
    extensionJvmOptions{
        setDisableFor(mutableListOf("org.acme:quarkus-red"))
    }
}

使用此配置，日志将显示如下：

[DEBUG] [io.quarkus.deployment.dev.DevModeCommandLineBuilder] Adding JVM options from org.acme:quarkus-blue::jar
[DEBUG] [io.quarkus.deployment.dev.DevModeCommandLineBuilder]   enable-native-access: [ALL-UNNAMED]
[DEBUG] [io.quarkus.deployment.dev.DevModeCommandLineBuilder]   add-modules: [jdk.incubator.vector]
[DEBUG] [io.quarkus.deployment.dev.DevModeCommandLineBuilder]   enable-preview: []
[DEBUG] [io.quarkus.deployment.dev.DevModeCommandLineBuilder] Skipped JVM options from org.acme:quarkus-red::jar
[INFO] [org.gradle.process.internal.DefaultExecHandle] Starting process 'command '/home/<username>/jdk/bin/java''. Working directory: /home/<username>/gradle-app/build/classes/java/main Command: /home/<username>/jdk/bin/java -Dquarkus.console.basic=true -Dio.quarkus.force-color-support=true -javaagent:/home/<username>/.m2/repository/io/quarkus/quarkus-class-change-agent/{quarkus-version}/quarkus-class-change-agent-{quarkus-version}.jar -Dquarkus-internal.serialized-app-model.path=/home/<username>/gradle-app/build/tmp/quarkusDev/quarkus-app-model.dat -Dquarkus-internal-test.serialized-app-model.path=/home/<username>/gradle-app/build/tmp/quarkusDev/quarkus-app-test-model.dat -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>/gradle-app/build/gradle-app-kotlin-dev.jar

调试

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

可以通过将 debug 系统属性设置为以下值之一来更改此行为：

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

  • true - JVM 以调试模式启动，并将监听端口 5005

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

  • {port} - JVM 以调试模式启动，并将监听 {port}

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

  • y 或 true - 调试模式 JVM 启动被挂起

  • n 或 false - 调试模式 JVM 在不挂起的情况下启动

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

CLI
quarkus dev -Dsuspend -Ddebug
Gradle
./gradlew --console=plain quarkusDev -Dsuspend -Ddebug

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

导入到您的 IDE

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

Eclipse

在 Eclipse 中，点击：File → Import。在向导中，选择：Gradle → Existing Gradle Project。在下一个屏幕上，选择项目的根目录。下一个屏幕列出找到的模块；选择生成的项目，然后点击 Finish。完成！

在一个单独的终端中，运行：

CLI
quarkus dev
Gradle
./gradlew --console=plain quarkusDev

享受高效的开发环境。

IntelliJ IDEA

在 IntelliJ IDEA 中：

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

  2. 选择项目根目录

  3. 选择 Import project from external model 和 Gradle

  4. 接下来点击几次（如果需要，可以查看不同的选项）

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

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

CLI
quarkus dev
Gradle
./gradlew --console=plain quarkusDev

享受！

Apache NetBeans

在 NetBeans 中：

  1. 选择 File → Open Project

  2. 选择项目根目录

  3. 点击 Open Project

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

CLI
quarkus dev
Gradle
./gradlew --console=plain quarkusDev

享受！

Visual Studio Code

在 VS Code 中打开项目目录。如果您安装了 Java Extension Pack（一组 Java 扩展），项目将被加载为 Gradle 项目。

为离线开发和测试下载依赖项

Quarkus 扩展依赖项分为运行时扩展依赖项（最终会出现在应用程序运行时类路径上）和部署（或构建时）扩展依赖项（仅在应用程序构建时由 Quarkus 解析以创建构建类路径）。应用程序开发人员应仅依赖于 Quarkus 扩展的运行时工件。

为了支持离线构建和测试 Quarkus 应用程序的用例，该插件包含 quarkusGoOffline 任务，可以从命令行像这样调用：

./gradlew quarkusGoOffline

此任务将把应用程序的所有运行时、构建时、测试和开发模式依赖项解析到 Gradle 缓存中。执行后，您将能够安全地使用 --offline 标志运行 quarkus 任务。

构建本机可执行文件

原生可执行文件使 Quarkus 应用程序成为容器和无服务器工作负载的理想选择。

确保已配置 GRAALVM_HOME 并指向 GraalVM for JDK 21 的最新版本。

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

CLI
quarkus build --native
Gradle
./gradlew build -Dquarkus.native.enabled=true

原生可执行文件将位于 build/ 目录中。

与原生相关的属性可以添加到 application.properties 文件中、作为命令行参数，或在 quarkusBuild 任务中配置。可以通过以下方式配置 quarkusBuild 任务：

Groovy DSL
quarkusBuild {
    nativeArgs {
        containerBuild = true (1)
        builderImage = "quay.io/quarkus/ubi9-quarkus-mandrel-builder-image:jdk-21" (2)
    }
}
1 将 quarkus.native.container-build 属性设置为 true
2 将 quarkus.native.builder-image 属性设置为 quay.io/quarkus/ubi9-quarkus-mandrel-builder-image:jdk-21
Kotlin DSL
tasks.quarkusBuild {
    nativeArgs {
        "container-build" to true (1)
        "builder-image" to "quay.io/quarkus/ubi9-quarkus-mandrel-builder-image:jdk-21" (2)
    }
}
1 将 quarkus.native.container-build 属性设置为 true
2 将 quarkus.native.builder-image 属性设置为 quay.io/quarkus/ubi9-quarkus-mandrel-builder-image:jdk-21

在使用 Gradle Groovy DSL 时，属性键必须遵循小驼峰命名法。例如，container-build 是无效的，应替换为 containerBuild。此限制不适用于 Gradle Kotlin DSL。

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

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

CLI
quarkus build --native --no-tests -Dquarkus.native.container-build=true
# The --no-tests flag is required only on Windows and macOS.
Gradle
./gradlew build -Dquarkus.native.enabled=true -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> 构建参数。

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

另请注意，从 Quarkus 3.19 开始，默认的*构建器*镜像基于 UBI 9。要使用以前的 UBI 8 基于的镜像，您可以从 quay.io 仓库 中选择一个镜像。

运行原生测试

使用以下命令运行原生测试：

./gradlew testNative

此任务依赖于 quarkusBuild，因此它将在运行原生测试之前生成原生镜像。

默认情况下，native-test 源集基于 main 和 test 源集。可以添加额外的源集。例如，如果您的集成测试位于 integrationTest 源集中，您可以将其指定为：

Groovy DSL
quarkus {
    sourceSets {
        extraNativeTest = sourceSets.integrationTest
    }
}
Kotlin DSL
quarkus {
    sourceSets {
        setExtraNativeTest(sourceSets["integrationTest"])
    }
}

运行集成测试

Quarkus 集成测试（用 @QuarkusIntegrationTest 标注）将在 Quarkus 生成的工件上运行。这些测试可以放在 src/integrationTest/java 目录中，并使用以下命令执行：

./gradlew quarkusIntTest

此任务依赖于 quarkusBuild，因此它将在运行集成测试之前生成工件。

使用 fast-jar

fast-jar 现在是默认的 quarkus 打包类型。./gradlew build 命令的结果是 build 下的一个名为 quarkus-app 的新目录。

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

为了成功运行生成的 jar，您需要 quarkus-app 目录的全部内容。如果缺少任何文件，应用程序将无法启动或可能无法正常运行。
fast-jar 打包会创建一个比传统 Quarkus jar 启动稍快且内存消耗稍少的工件，因为它具有关于哪个依赖 jar 包含类和资源的索引信息。因此，当加载类或资源时，它可以避免在传统 jar 所必需的类路径上的所有 jar 中进行查找。

构建 Uber-Jars

Quarkus Gradle 插件通过指定 quarkus.package.jar.type 参数来支持 Uber-Jars 的生成，如下所示：

CLI
quarkus build quarkus deploy openshift
Gradle
./gradlew build -Dquarkus.package.jar.type=uber-jar

构建 Uber-Jar 时，您可以使用 --ignored-entry 参数指定要从生成的 jar 中排除的条目：

./gradlew quarkusBuild -Dquarkus.package.jar.type=uber-jar --ignored-entry=META-INF/file1.txt

条目相对于生成的 Uber-Jar 的根目录。您可以通过添加额外的 --ignored-entry 参数来指定多个条目。

处理多模块项目

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

要在多模块项目中为模块启用 CDI bean 发现的最佳方法是包含一个 META-INF/beans.xml 文件，除非它是已使用 io.quarkus Gradle 插件配置的主应用程序模块，在这种情况下，它将被自动索引。

或者，有一些非官方的 Gradle Jandex 插件 可以代替 META-INF/beans.xml 文件使用。

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

发布您的应用程序

为了确保 Gradle 使用正确的依赖版本，BOM 被声明为构建文件中的 enforcedPlatform。默认情况下，maven-publish 插件会由于此 enforcedPlatform 而阻止您发布应用程序。可以通过在构建文件中添加以下配置来跳过此验证：

Groovy DSL
tasks.withType(GenerateModuleMetadata).configureEach {
    suppressedValidationErrors.add('enforced-platform')
}
Kotlin DSL
tasks.withType<GenerateModuleMetadata>().configureEach {
    suppressedValidationErrors.add("enforced-platform")
}

配置 Quarkus 构建

有多种配置源会影响 Quarkus 构建，按优先级顺序列出。Quarkus 构建使用 prod 配置配置文件：

  1. 系统属性（例如 ./gradlew -Dquarkus.package.jar.type=fast-jar …​）

  2. 系统环境变量（例如 QUARKUS_PACKAGE_JAR_TYPE=fast-jar ./gradlew …​）

  3. 通过 quarkus 扩展的 quarkusBuildProperties 进行配置。例如：

    quarkus {
    quarkusBuildProperties {
        set("package.jar.type", "uber-jar")
    }
}

  4. 通过 Gradle 项目属性进行配置（例如 ./gradlew -Pquarkus.package.jar.type=fast-jar）

  5. 从项目的 application.properties、application.yaml 和 application.yml 文件以及项目的 application-prod.properties、application-prod.yaml 和 application-prod.yml 文件进行配置。

Quarkus 3.0 起，Quarkus 插件中的以上优先级已发生变化。Quarkus Gradle 插件的旧版本优先考虑 application.properties 而非 Gradle 构建中的设置。
Quarkus Gradle 插件使用“标准”Quarkus 机制加载和解析配置。除了 application.properties 之外，Quarkus 3.0 还支持 application.(yaml|yml)。3.0 中新增加的是，SmallRye Config 可用的所有机制，现在也隐式地可用于 Quarkus Gradle 插件。
使用 quarkusShowEffectiveConfig 任务显示 Quarkus 构建所使用的有效配置选项。如果指定 --save-config-properties 命令行选项，配置属性还将存储在文件 build/<final-name>.quarkus-build.properties 中。

Gradle 缓存/任务输入

默认情况下，以 quarkus. 开头的系统属性和环境变量（包括来自 ~/.env 的以 QUARKUS_ 开头的环境变量）被视为 Gradle 任务的输入。这意味着只有这些系统属性或环境变量发生更改才会导致 Gradle 的 up-to-date 触发重新构建。其他系统属性或环境变量的更改不会改变 Quarkus 的 Gradle 任务输入，也不会触发不必要的重新构建。

通过 quarkus.quarkusBuildProperties 或 Quarkus application.* 配置文件指定的配置属性都被视为 Gradle 任务输入，换句话说：这些文件的任何更改都会导致重新构建。

如果您的 Quarkus 构建引用了不以 quarkus. 开头的系统属性（或不以 QUARKUS_ 开头的环境变量），则必须通过 Quarkus 构建扩展显式引用它们。例如，如果您的 application.properties 文件像这样引用了一个环境变量：

greeting.message=${FOO_MESSAGE:Hello!}

它必须被显式声明为“与缓存相关的”：

quarkus {
   cachingRelevantProperties.add("FOO_MESSAGE")
   // Note: `cachingRelevantProperties` accepts regular expressions
}

构建工作进程

Quarkus 应用程序构建在隔离的进程中使用 Gradle 的工作进程 API 进行运行。这包括 Quarkus 应用程序构建和 Quarkus 代码生成。这是为了正确地将配置从 quarkus 扩展和 Gradle 项目属性传递给 Quarkus 的代码生成器/应用程序构建器。

执行代码生成和/或 Quarkus 构建的进程的 JVM 设置可以按如下方式配置。有关详细信息，请参阅 JavaForkOptions。

Groovy DSL
plugins {
    id 'java'
    id 'io.quarkus'
}

quarkus {
    buildForkOptions {
        maxHeapSize = '2g'
    }
    codeGenForkOptions {
        maxHeapSize = '128m'
    }
}
Kotlin DSL
plugins {
    java
    id("io.quarkus")
}

quarkus {
    buildForkOptions {
        maxHeapSize = '2g'
    }
    codeGenForkOptions {
        maxHeapSize = '128m'
    }
}

缓存的构建工件

Gradle 的构建缓存 是一个非常高效的机制，可以通过重用先前生成的输出来提高整体构建运行时（有关技术细节，请参阅 增量构建）。

Quarkus 插件利用 Gradle 的 up-to-date 检查和构建缓存机制。构建缓存可以是本地的，也可以是本地加远程缓存服务器，或者如果在 CI 环境中配置，则为远程的，通过检索和存储整个缓存作为工件，例如使用 Gradle 的 GitHub Action 或直接/手动 GitHub 的 GitHub 的缓存 Action。

Quarkus Gradle 插件负责*什么*被缓存*在何种环境中*（CI 或本地开发）。Uber-Jars 和原生二进制文件等大型工件在 CI 中不被缓存，但在本地开发环境中被缓存。

如果存在 CI 环境变量，Quarkus Gradle 插件将检测到*CI 环境*。

以下表格描述了各种 Quarkus 打包类型在非 CI 和 CI 环境中如何被缓存。请注意，即使任务的输出没有被*缓存*，*up-to-date* 检查仍然适用。

Quarkus 应用程序构建分为三个任务。quarkusBuild 任务负责*提供*已构建的 Quarkus 应用程序。quarkusDependenciesBuild 和 quarkusAppPartsBuild 任务被视为内部任务（可能会随时更改，恕不另行通知）。详情请参阅下文。

Quarkus 打包类型

备注

缓存（非 CI）

CI 中的缓存

fast-jar, jar

依赖 jar 被存储为 quarkus-app/lib/ 目录中的单独文件，未被修改。quarkus-app/ 目录中的所有其他文件都是生成的。

quarkusAppPartsBuild 任务构建 fast-jar 打包类型应用程序，并允许缓存*生成的*部分，即 quarkus-app/lib/ 目录中的依赖项之外的所有内容。quarkusDependenciesBuild 任务用于通过 Gradle 机制收集依赖项。然后，quarkusBuild 任务将 quarkusAppPartsBuild 和 quarkusDependenciesBuild 任务的输出组装起来。

注意：如果未显式配置打包类型，则 fast-jar（或 -jar）是默认值。

✅

✅

mutable-jar, uber-jar, native, native-sources

quarkusBuild 任务负责构建 Quarkus 应用程序。

quarkusAppPartsBuild 和 quarkusDependenciesBuild 任务对于 `uber-jar` 不执行任何操作。

✅

❌

legacy-jar, legacy

legacy-jar 构建的工作方式类似于 fast-jar 构建，只是目录结构不同，并且 modified-*.jar 文件被视为生成的。

✅

✅
在本地开发环境中，存储（和检索）即使是更大的缓存工件的成本（时间）也低于重新构建 Quarkus 应用程序的成本。这意味着，Quarkus Gradle 插件允许在非 CI 环境中缓存包括 uber-jars 或原生二进制文件在内的潜在大型工件。在 CI 环境中，这些环境针对代码库的不同状态运行构建（例如，针对主分支上的每个提交运行 CI），将每个构建的（大型）工件添加到构建缓存中将导致构建缓存变得不必要大，这在 GitHub 等场景中会成为问题，因为缓存工件的总量限制为 10 GB。

背景信息：Gradle 中有两种相关的机制可用于提高构建性能：

  • Up-to-date 检查允许跳过任务的执行，如果任务的*输入*和*输出*没有改变。例如，考虑一个 Java 编译任务：如果库依赖项和源文件（*输入*）没有改变，并且编译后的类文件（*输出*）仍然可用，则可以跳过编译。

  • 构建缓存可以将（可缓存）任务的输出存储在本地构建缓存中。可以从缓存中恢复任务的*输出*。

up-to-date 检查和构建缓存交互的优势在于需要对*输入*和*输出*进行建模。输入不仅是文件或目录，还包括构建期间使用的 Java 版本、操作系统、工作目录、配置选项等。因此，任何影响任务操作输出的内容都必须声明为任务的输入。

Gradle 配置缓存

Quarkus Gradle 插件可以与启用了 Gradle 配置缓存 的构建一起工作，但配置缓存对某些 Quarkus 任务被禁用。这意味着 Quarkus 插件不会破坏这些 Gradle 构建。当前兼容性状态如下表所示：

Quarkus 任务

配置缓存兼容性

quarkusGenerateCode

✅

quarkusGenerateCodeDev

✅

quarkusGenerateCodeTests

✅

quarkusDependenciesBuild

✅

quarkusAppPartsBuild

✅

quarkusShowEffectiveConfig

✅

quarkusBuild

✅

imageBuild

✅

imagePush

✅

quarkusDev

❌

quarkusRun

❌

quarkusRemoteDev

❌

quarkusTest

❌

quarkusGoOffline

❌

quarkusInfo

❌

quarkusUpdate

❌

deploy

❌

listExtensions

❌

listCategories

❌

listPlatforms

❌

addExtension

❌

removeExtension

❌

相关内容

关于相同主题

Quarkus 是开源的。本项目的所有依赖项均可在 Apache Software License 2.0 或兼容许可证下获得。 CC by 3.0

本网站由 Jekyll 构建，托管在 GitHub Pages 上，并且完全开源。如果您想让它变得更好，请 fork 本网站 并展示您的成果。

导航
关注我们
获取帮助
语言
Quarkus 由社区项目组成
版权所有 © Quarkus。保留所有权利。有关我们的商标详情，请访问我们的 商标政策 和 商标列表。第三方商标归其各自所有者所有，此处提及不表示任何认可或关联。