Conditional Extension Dependencies

Quarkus 扩展依赖项通常按项目在项目构建文件中与任何其他项目依赖项不同的方式进行配置，例如 Maven pom.xml 或 Gradle 构建脚本。但是，Maven 和 Gradle 还不支持开箱即用的依赖项类型。我们这里提到的“条件依赖项”就是一个例子。

Quarkus extension dependencies are usually configured in the same way as any other project dependencies in the project’s build file, e.g. the Maven pom.xml or the Gradle build scripts. However, there are dependency types that aren’t yet supported out-of-the-box by Maven and Gradle. What we refer here to as "conditional dependencies" is one example.

Conditional Dependencies

条件依赖性的思想是，只有在满足特定条件时才必须激活此类依赖项。如果条件不满足，则 must not 依赖项将被激活。在这方面，条件依赖项可以归类为可选项，即它们可能出现在项目依赖项的结果集中，也可能不出现。

The idea behind the notion of the conditional dependency is that such a dependency must be activated only if a certain condition is satisfied. If the condition is not satisfied then the dependency must not be activated. In that regard, conditional dependencies can be categorized as optional, i.e. they may or may not appear in the resulting set of project dependencies.

在哪些情况下条件依赖项可能有用？一个典型的例子是一个组件，当其所有必需依赖项都可用时，它应该 only 激活。如果组件的一个或多个必需依赖项不可用，组件不应失败，而应不激活。

In which cases could conditional dependencies be useful? A typical example would be a component that should be activated only in case all of its required dependencies are available. If one or more of the component’s required dependencies aren’t available, instead of failing, the component should simply not be activated.

Quarkus Conditional Extension Dependencies

Quarkus 支持条件扩展依赖项。即一个 Quarkus 扩展可以通过其他 Quarkus 扩展声明一个或多个条件依赖项。不支持不属于扩展程序工件的条件依赖项。

Quarkus supports conditional extension dependencies. I.e. one Quarkus extension may declare one or more conditional dependencies on other Quarkus extensions. Conditional dependencies on and from non-extension artifacts aren’t supported.

让我们以以下场景为例：quarkus-extension-a 对 quarkus-extension-b 有一个可选依赖项，它应该仅在其依赖项（直接或传递）中找到 quarkus-extension-c 时才包含在 Quarkus 应用程序中。换句话说，quarkus-extension-c 的存在是条件，如果满足，则在构建 Quarkus 应用程序期间会启用 quarkus-extension-b 。

Let’s take the following scenario as an example: quarkus-extension-a has an optional dependency on quarkus-extension-b which should be included in a Quarkus application only if quarkus-extension-c is found among its dependencies (direct or transitive). In other words, the presence of quarkus-extension-c is the condition which, if satisfied, enables quarkus-extension-b during the build of a Quarkus application.

触发扩展激活的条件是在扩展程序的描述符中配置的，该描述符作为 META-INF/quarkus-extension.properties 包含在扩展程序的运行时工件中。由于扩展符描述符是由 Quarkus 插件在扩展符构建时生成的，因此扩展符开发人员可以添加以下配置来表示扩展符激活所必需的条件：

The condition which triggers activation of an extension is configured in the extension’s descriptor, which is included into the runtime artifact of the extension as META-INF/quarkus-extension.properties. Given that extension descriptor is generated by the Quarkus plugin at extension build time, extension developers can add the following configuration to express the condition which would have to be satisfied for the extension to be activated:

<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">

  <!-- SKIPPED CONTENT -->

  <artifactId>quarkus-extension-b</artifactId> 1

  <!-- SKIPPED CONTENT -->

  <build>
    <plugins>
      <plugin>
        <groupId>io.quarkus</groupId>
        <artifactId>quarkus-extension-maven-plugin</artifactId>
        <version>${quarkus.version}</version>
        <executions>
          <execution>
            <phase>process-resources</phase>
            <goals>
              <goal>extension-descriptor</goal> 2
            </goals>
            <configuration>
              <dependencyCondition> 3
                <artifact>org.acme:quarkus-extension-c</artifact> 4
              </dependencyCondition>
            </configuration>
          </execution>
        </executions>
      </plugin>

  <!-- SKIPPED CONTENT -->

1	runtime Quarkus extension artifact ID, in our example `quarkus-extension-b`;
2	the goal that generates the extension descriptor which every Quarkus runtime extension project should be configured with;
3	configuration of the condition which will have to be satisfied for this extension to be included into a Quarkus application expressed as a list of artifacts that must be present among the application dependencies;
4	an artifact key (in the format of `groupId:artifactId[:<classifier>:<extension>]` but typically simply `<groupId>:<artifactId>`) of the artifact that must be present among the application dependencies for the condition to be satisfied.

在上面的示例中，条件配置中使用的 artifact 碰巧是一个运行时 Quarkus 扩展工件，但它也可以是任何其他工件。dependencyCondition 的正文中还可以有多个 artifact 元素。

In the example above the artifact used in the condition configuration happens to be a runtime Quarkus extension artifact but it could as well be any other artifact. There could also be more than one artifact element in the body of dependencyCondition.

现在，在 quarkus-extension-b 的描述符中有一个依赖项激活条件，其他扩展可以声明对它的条件依赖项。

Now, having a dependency activating condition in the descriptor of quarkus-extension-b, other extensions may declare a conditional dependency on it.

条件依赖项是在 Quarkus 扩展的运行时工件中配置的。在我们的示例中，quarkus-extension-a 对 quarkus-extension-b 有条件依赖项，可以用两种方式表示。

A conditional dependency is configured in the runtime artifact of a Quarkus extension. In our example, it’s the quarkus-extension-a that has a conditional dependency on quarkus-extension-b, which can be expressed in two ways.

Declaring a dependency as `optional`

如果一个扩展在它的描述符中配置了一个依赖条件，其他扩展可以通过简单地向依赖项配置中添加 <optional>true</optional> 来配置对它的条件依赖项。在我们的示例中，它将如下所示：

If an extension was configured with a dependency condition in its descriptor, other extensions may configure a conditional dependency on it by simply adding <optional>true</optional> to the dependency configuration. In our example it would look like this:

<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">

  <!-- SKIPPED CONTENT -->

  <artifactId>quarkus-extension-a</artifactId> 1

  <!-- SKIPPED CONTENT -->

  <dependencies>
    <dependency>
      <groupId>org.acme</groupId>
      <artifactId>quarkus-extension-b</artifactId> 2
      <optional>true</optional>
    </dependency>

  <!-- SKIPPED CONTENT -->

1	the runtime extension artifact `quarkus-extension-a`
2	declares an optional Maven dependency on the runtime extension artifact `quarkus-extension-b`

通常，对于针对另一个运行时扩展制品依赖的运行时扩展制品依赖，在另一个部署扩展制品上的部署扩展制品依赖必须是对应的。而如果运行时依赖被声明为可选，那么对应的部署依赖 must 也必须被配置为可选。

In general, for every runtime extension artifact dependency on another runtime extension artifact there must be a corresponding deployment extension artifact dependency on the other deployment extension artifact. And if the runtime dependency is declared as optional then the corresponding deployment dependency must also be configured as optional.

<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">

  <!-- SKIPPED CONTENT -->

  <artifactId>quarkus-extension-a-deployment</artifactId> 1

  <!-- SKIPPED CONTENT -->

  <dependencies>
    <dependency>
      <groupId>org.acme</groupId>
      <artifactId>quarkus-extension-b-deployment</artifactId> 2
      <optional>true</optional>
    </dependency>

  <!-- SKIPPED CONTENT -->

1	the deployment extension artifact `quarkus-extension-a-deployment`
2	declares an optional Maven dependency on the deployment extension artifact `quarkus-extension-b-deployment`

通常，可选的 Maven 扩展依赖在构建时会被 Quarkus 依赖解析器忽略。然而，在这种情况下，可选依赖 quarkus-extension-b 在扩展描述符中包含一个依赖条件，这将该可选 Maven 依赖转换为一个 Quarkus 条件扩展依赖。

Normally, optional Maven extension dependencies are ignored by the Quarkus dependency resolver at build time. In this case though, the optional dependency quarkus-extension-b includes a dependency condition in its extension descriptor, which turns this optional Maven dependency into a Quarkus conditional extension dependency.

如果 quarkus-extension-b 不是声明为`<optional>true</optional>`，那将会使`quarkus-extension-b`成为 quarkus-extension-a 的必需依赖，并且它的依赖条件将会被忽略。

If quarkus-extension-b wasn’t declared as <optional>true</optional> that would make quarkus-extension-b a required dependency of quarkus-extension-a and its dependency condition would be ignored.

Declaring a conditional dependency in the Quarkus extension descriptor

条件依赖也可以在 Quarkus 扩展描述符中配置。上面配置的条件依赖可以在`quarkus-extension-a`的扩展描述符中表达为：

Conditional dependencies can also be configured in the Quarkus extension descriptor. The conditional dependency configured above could be expressed in the extension descriptor of quarkus-extension-a as:

<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">

  <!-- SKIPPED CONTENT -->

  <artifactId>quarkus-extension-a</artifactId> 1

  <!-- SKIPPED CONTENT -->

  <build>
    <plugins>
      <plugin>
        <groupId>io.quarkus</groupId>
        <artifactId>quarkus-extension-maven-plugin</artifactId>
        <version>${quarkus.version}</version>
        <executions>
          <execution>
            <phase>process-resources</phase>
            <goals>
              <goal>extension-descriptor</goal> 2
            </goals>
            <configuration>
              <conditionalDependencies> 3
                <extension>org.acme:quarkus-extension-b:${b.version}</extension> 4
              </conditionalDependencies>
            </configuration>
          </execution>
        </executions>
      </plugin>

  <!-- SKIPPED CONTENT -->

1	runtime Quarkus extension artifact ID, in our example `quarkus-extension-a`
2	the goal that generates the extension descriptor which every Quarkus runtime extension project should be configured with
3	conditional dependency configuration element
4	artifact coordinates of conditional dependencies on other extensions.

在这种情况下，Maven 依赖在`pom.xml`中完全不需要。

In this case, the Maven dependency is not at all required in the pom.xml.

Conditional Extension Dependencies

Conditional Dependencies

Quarkus Conditional Extension Dependencies

Declaring a dependency as optional

Declaring a conditional dependency in the Quarkus extension descriptor

Declaring a dependency as `optional`