Quarkus Extension Metadata

Quarkus 扩展以 Maven JAR 工件的形式分发，应用程序和其他库可能依赖于这些 JAR 工件。在使用 Quarkus 开发工具构建、测试或编辑 Quarkus 应用程序项目时，Quarkus 开发工具将在应用程序类路径中识别 Quarkus 扩展 JAR 工件，方法是这些工件中存在 Quarkus 扩展元数据文件。本文档描述了每个 Quarkus 扩展元数据文件的目的和内容。

其中两个元数据文件具有相同的名称但不同的扩展名，quarkus-extension.yaml 和 quarkus-extension.properties。很容易将其混淆，请小心。您通常会编辑 YAML 文件并在您的 SCM 中跟踪它。虽然您 can 手动管理属性文件，但如果您不这样做，Quarkus 会在构建时生成它。

META-INF/quarkus-extension.yaml

每个 runtime 扩展工件 must 都包含此文件。Quarkus 开发工具在显示有关扩展的信息、创建新项目或向现有项目添加扩展等操作时使用此文件。此文件在应用程序构建或引导时并不使用。此文件中包含的基本且必需的元数据可以在构建扩展工件时由 Quarkus Maven 和 Gradle 插件生成。但是，通常，扩展作者希望向 Quarkus 开发工具和用户提供有关扩展的更多信息。可以在扩展运行时模块的资源目录中找到模板 META-INF/quarkus-extension.yaml 中提供其他信息，例如 src/main/resources/META-INF/quarkus-extension.yaml。以下是 quarkus-resteasy-reactive 扩展的此类模板示例：

name: "REST" 1
artifact: ${project.groupId}:${project.artifactId}:${project.version} 2
metadata:
  short-name: "rest" 3
  keywords: 4
  - "jaxrs"
  - "web"
  - "rest"
  categories: 5
  - "web"
  - "reactive"
  status: "stable" 6
  guide: "https://quarkus.io/guides/rest" 7
  icon-url: "https://quarkus.io/assets/images/about/icon-reactive.svg" 8
  codestart: 9
    name: "rest"
    languages:
      - "java"
      - "kotlin"
      - "scala"
    artifact: "io.quarkus:quarkus-project-core-extension-codestarts"
  config: 10
  - "quarkus.rest."
1 显示给用户的扩展名称
2 实际坐标将在构建期间替换的扩展运行时工件表达式，该字段可以省略
3 可以用来在 dev 工具向用户提供的扩展目录中快速找到扩展的简称
4 可以用来在 dev 工具向用户提供的扩展目录中搜索扩展的关键词
5 扩展应该在 code.quarkus.io 中显示的类别。此字段可以省略，扩展仍然会列于 code.quarkus.io 中，但不会被归类
6 成熟度状态可能为 stable，preview，experimental。评估成熟度状态并将其传达给用户取决于扩展维护人员
7 指向扩展指南或文档页面
8 指向外部托管图像的链接。Quarkus 开发工具中将其用作扩展图标。它应该是正方形，任意分辨率大于 220 像素。支持的格式为 png、jpeg、tiff、webp 和 svg。或者，如果您直接位于扩展源代码存储库中，工具将获取该图像。
9 Codestart information
10 Configuration prefix

以下是包含在运行时 JAR 中的文件的最终版本，它增加了 Quarkus Maven 插件收集的其他信息：

name: "Quarkus REST (formerly RESTEasy Reactive)"
artifact: "io.quarkus:quarkus-rest:999-SNAPSHOT"
metadata:
  short-name: "rest"
  keywords:
  - "jaxrs"
  - "web"
  - "rest"
  categories:
  - "web"
  - "reactive"
  status: "stable"
  guide: "https://quarkus.io/guides/rest"
  codestart:
    name: "rest"
    languages:
    - "java"
    - "kotlin"
    - "scala"
    artifact: "io.quarkus:quarkus-project-core-extension-codestarts::jar:999-SNAPSHOT"
  config:
  - "quarkus.rest."
  built-with-quarkus-core: "3.8.5" 1
  requires-quarkus-core: "[3.8,)" 2
  capabilities: 3
    provides:
    - "io.quarkus.rest"
    - "io.quarkus.resteasy.reactive"
  extension-dependencies: 4
  - "io.quarkus:quarkus-rest-common"
  - "io.quarkus:quarkus-mutiny"
  - "io.quarkus:quarkus-smallrye-context-propagation"
  - "io.quarkus:quarkus-vertx"
  - "io.quarkus:quarkus-arc"
  - "io.quarkus:quarkus-netty"
  - "io.quarkus:quarkus-vertx-http"
  - "io.quarkus:quarkus-core"
  - "io.quarkus:quarkus-jsonp"
description: "A Jakarta REST implementation utilizing build time processing and Vert.x.\
  \ This extension is not compatible with the quarkus-resteasy extension, or any of\
  \ the extensions that depend on it." 5
scm-url: "https://github.com/quarkusio/quarkus" 6
sponsor: A Sponsoring Organisation 7
1 使用该扩展构建的 Quarkus 版本
2 该扩展所需的 Quarkus 版本范围。可选，且将通过使用 built-with-quarkus-core 作为最低范围自动设置。
3 Capabilities this extension provides
4 对其他扩展的直接依赖
5 可以向用户显示的描述。在此情况下，该描述是从扩展模块的 pom.xml 中复制的，但也可以在模板文件中提供。
6 该扩展的源代码存储库。可选，且通常会通过使用 pom 中的 <scm> 信息自动设置。在 GitHub Actions 构建中，系统会从 CI 环境中推断出它。对于其他 GitHub 存储库，可以通过设置 GITHUB_REPOSITORY 环境变量对其进行控制。
7 该扩展的赞助商。可选，有时会根据提交历史自动确定。

META-INF/quarkus-extension.properties

每个 runtime 扩展工件 must 都包括此文件。此文件由 Quarkus 引导机制读取，其目的是仅包含与 building or bootstrapping 应用程序相关的信息。此文件通常在构建扩展项目时由相应的 Quarkus Maven 或 Gradle 插件自动生成，不应手动编辑。此文件中可能出现以下属性：

Name Presence Description

deployment-artifact

Required

以 groupId:artifactId[:classifier:type]:version 格式指向相应的扩展部署工件

parent-first-artifacts

Optional

要以先后加载方式加载的工件密钥 (groupId:artifactId:classifier:type) 的逗号分隔列表。这可以用来解决给定类需要由系统 ClassLoader 加载的问题。

runner-parent-first-artifacts

Optional

当应用程序从生产二进制包启动时，除了使用 parent-first-artifacts 配置的那些工件密钥以外，还要以先后加载方式加载的工件密钥的逗号分隔列表。这可以用来解决给定类需要由系统 ClassLoader 加载的问题。

excluded-artifacts

Optional

永远不会由类加载器加载且不会打包到最终应用程序中的工件密钥的逗号分隔列表。

lesser-priority-artifacts

Optional

只有在不存在包含该类或资源的其他工件的情况下，才用来加载类或资源的工件密钥的逗号分隔列表。这是为了控制工件的顺序，当多个工件包含相同的类时。

removed-resources.*

Optional

应从依赖关系中移除/隐藏的资源。这允许从依赖关系中移除类和其他资源，因此它们无法被应用程序访问。这是工件键到要移除的资源的逗号分隔列表的映射。在开发和测试模式下运行时，这些资源对 ClassLoader 隐藏，在生产模式下运行时，这些文件从包含它们的 jar 文件中移除。请注意，如果您想移除类，则需要指定类文件名称。例如，要移除 com.acme.Foo，您需要指定 com/acme/Foo.class。

provides-capabilities

Optional

此扩展提供的 capabilities 列表

requires-capabilities

Optional

其他 Quarkus 扩展需要此扩展提供的 capabilities 列表

conditional-dependencies

Optional

此扩展声明的 conditional dependencies 列表

dependency-condition

Optional

激活对此扩展的条件依赖关系时必须满足的 Dependency condition

META-INF/quarkus-config-roots.list

此文件可能出现在运行时扩展工件以及部署工件中。此文件不得手动编辑，它作为扩展项目构建过程的一部分生成，并包含用 io.quarkus.runtime.annotations.ConfigRoot 注释的 Java 类名称列表，该扩展提供。

META-INF/quarkus-javadoc.properties

与 quarkus-config-roots.list 相同，此文件可能出现在运行时扩展工件以及部署工件中。它作为扩展项目构建过程的一部分从用 io.quarkus.runtime.annotations.ConfigRoot 注释的类中可用的配置选项的描述中生成，不支持手动编辑。

META-INF/quarkus-build-steps.list

此文件可能出现在部署扩展工件中。它包含实现 Quarkus 构建步骤的类的列表（用 io.quarkus.deployment.annotations.BuildStep 注释的方法）。此文件作为扩展项目构建过程的一部分生成，不得手动编辑。