Re-augment a Quarkus Application

What is augmentation?

Quarkus 应用程序配置可能包含两种类型的配置选项：

Quarkus application configuration may include two types of configuration options:

  • Build time options, handled during the application build time;

  • Runtime options, that may be adjusted after the application has been built but before it has been launched.

增强是应用程序构建过程的一个阶段，在此阶段，根据应用程序构建时间配置对应用程序的字节码进行优化。以前在 Jakarta EE 服务器上部署 EAR 文件时发生的初始化步骤（如解析静态配置、创建代理实例等）现在在增强时发生。增强后添加的 CDI bean 将无法正常工作（因为缺少代理类），并且在增强后更改的构建时间属性（例如 quarkus.datasource.db-kind）将会被忽略。构建时间属性在 list of all configuration options 中用锁图标 () 标记。无论您使用配置文件还是任何其他方式来覆盖属性都无关紧要。

The augmentation is a phase of an application build process during which the byte code of the application is optimized according to the application build time configuration. Initialization steps that used to happen when an EAR file was deployed on a Jakarta EE server such as parsing static configuration, creating proxy instances, etc. now happen at augmentation time. CDI beans added after augmentation won’t work (because of the missing proxy classes) as well as build time properties (e.g. quarkus.datasource.db-kind) changed after augmentation will be ignored. Build time properties are marked with a lock icon () in the list of all configuration options. It doesn’t matter if you use profiles or any other way to override the properties.

重新增强是为不同的构建时间配置重新创建增强输出的过程

Re-augmentation is the process of recreating the augmentation output for a different build time configuration

When is re-augmentation useful?

重新增强对于您的应用程序用户希望能够更改其一些构建时间属性的情况很有用。例如更改数据库驱动程序或开启或关闭特性（例如 OpenTelemetry 或 Config Consul）。如果只有两个或三个构建时间属性依赖于用户环境，您可以考虑提供应用程序的备用版本。但是，如果有更多这样的属性，您可能更愿意提供一个可变 jar，并让您的用户为他们的环境重新增强应用程序。请注意，您无法对包类型 mutable-jar 使用本机映像。考虑后果以及您还有哪些其他选择！

Re-augmentation is useful in case the users of your application want to be able to change some of its build time properties. For instance changing the database driver or switching features on or off (e.g. OpenTelemetry or Config Consul). If there are only two or three build time properties that depend on the user environment, you may consider providing alternative builds of the application. However, in case there are more such properties you may prefer shipping a mutable jar instead and let your users re-augment the application for their environment. Please notice that you won’t be able to use native images with the package type mutable-jar. Think of the consequences and what other options you have!

除非您怀念启动服务器需要几分钟的时间，并且您可以在服务器准备好之前享受一杯咖啡，否则在运行时进行重新增强并不是一个好主意。

It is not a good idea to do re-augmentation at runtime unless you miss the good old times when starting up a server took several minutes, and you could enjoy a cup of coffee until it was ready.

How to re-augment a Quarkus application

为了运行增强步骤，您需要所用 Quarkus 扩展的部署 JAR。这些 JAR 仅存在于 mutable-jar 发行版中。这意味着您需要使用 quarkus.package.jar.type=mutable-jar 构建您的应用程序。mutable-jar 发行版与 fast-jar 发行版相同，不同之处在于附加的文件夹 quarkus-app/lib/deployment，其中包含部署 JAR 及其依赖项（以及一些类加载器配置）。

In order to run the augmentation steps you need the deployment JARs of the used Quarkus extensions. These JARs are only present in the mutable-jar distribution. This means that you need to build your application with quarkus.package.jar.type=mutable-jar. The mutable-jar distribution is the same as the fast-jar distribution, except for the additional folder quarkus-app/lib/deployment which contains the deployment JARs and their dependencies (and some class-loader configuration).

默认情况下，如果构建时属性在运行时已更改，您会收到一个警告。您可以设置 quarkus.configuration.build-time-mismatch-at-runtime=fail 属性以确保应用程序在不匹配的情况下不会启动。然而，截至本文撰写之时，在运行时更改 quarkus.datasource.db-kind 既不会失败，也不会产生警告，而是会被静默忽略。

By default, you’ll get a warning if a build time property has been changed at runtime. You may set the quarkus.configuration.build-time-mismatch-at-runtime=fail property to make sure your application does not start up if there is a mismatch. However, as of this writing changing quarkus.datasource.db-kind at runtime did neither fail nor produce a warning but was silently ignored.

构建工具提供的构建时配置（Maven 中的 properties``pom.xml 或 Gradle 中的 gradle.properties）quarkus 命名空间中的将成为 mutable-jar 分发的一部分，包括来自 quarkus 的配置，它们引用机密或密码。请不要在构建工具配置文件中包含敏感信息。

Build time configuration provided by build tools (properties in Maven pom.xml or gradle.properties in Gradle) in the quarkus namespace will be part of the mutable-jar distribution, including configuration from quarkus that reference secrets or passwords. Please, do not include sensitive information in the build tool configuration files.

1. Build your application as mutable-jar

mvn clean install -Dquarkus.package.jar.type=mutable-jar

2. Re-augment your application with a different build time configuration

为了用不同的构建时属性重新扩充您的 Quarkus 应用程序，请使用所需的配置启动应用程序，再加上设置为 true 的 quarkus.launch.rebuild 系统属性。

In order to re-augment your Quarkus application with different build time properties, start the application with the desired configuration plus the quarkus.launch.rebuild system property set to true.

以下示例将 quarkus.datasource.db-kind 更改为 mysql。为了实现这一点，mysql-extension 必须已包含在构建中。扩充只能使用编译时已存在的扩展。

The following example changes the quarkus.datasource.db-kind to mysql. For this to work the mysql-extension must have been included in the build. Augmentation can only use extensions that were present during compile time.

java -jar -Dquarkus.launch.rebuild=true -Dquarkus.datasource.db-kind=mysql target/quarkus-app/quarkus-run.jar

使用系统属性、环境变量、配置还是外部配置文件并不重要。当前配置将用于扩充（quarkus-app/quarkus 的内容将用新的扩充输出替换）。上述命令行不会启动该应用程序。Quarkus 将在应用程序重新扩充后立即退出。

It does not matter if you use system properties, environment variables, profiles, or an external config file. The current configuration will be used for augmentation (the content of quarkus-app/quarkus will be replaced with the new augmentation output). The command line above will not launch the application. Quarkus will exit immediately after the application has been re-augmented.

3. Optional: Delete the deployments folder

您可以删除目录 quarkus-app/lib/deployment 以节省 ZIP 分发或 Docker 映像中的一些空间（记住使用多级 Docker 构建以避免不必要的层）。删除 deployment 目录后，显然不再有可能重新扩充该应用程序。

You may delete the directory quarkus-app/lib/deployment to save some space in your ZIP distribution or Docker image (remember to use a multistage Docker build to avoid unnecessary layers). After deleting the deployment directory, it is obviously not possible anymore to re-augment the application.