Quarkus Extension Metadata

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

Quarkus extensions are distributed as Maven JAR artifacts that application and other libraries may depend on. When a Quarkus application project is built, tested or edited using the Quarkus dev tools, Quarkus extension JAR artifacts will be identified on the application classpath by the presence of the Quarkus extension metadata files in them. This document describes the purpose of each Quarkus extension metadata file and its content.

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

Two of the metadata files have the same name but different extensions, quarkus-extension.yaml and quarkus-extension.properties. It is easy to mix them up, be careful. You will usually edit the YAML file and track it in your SCM. While you can manually manage the properties file, Quarkus will generated it at build if you don’t.

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 扩展的此类模板示例：

Every runtime extension artifact must include this file. This file is used by Quarkus dev tools when displaying information about an extension, creating a new project or adding extensions to an existing project, etc. This file isn’t used at application build or bootstrap times. The basic and required metadata included in this file can be generated by the Quarkus Maven and Gradle plugins when the extension artifact is built. However, typically, extension authors will want to provide more information about the extension to the Quarkus dev tools and users. The extra information could be provided in a template META-INF/quarkus-extension.yaml found in the extension runtime module’s resources directory, e.g. src/main/resources/META-INF/quarkus-extension.yaml. Here is an example of such a template for the quarkus-resteasy-reactive extension:

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	Extension name displayed to users
2	Extension runtime artifact expression that will be replaced with the actual coordinates during the build, this field could be omitted
3	Short name that could be used to quickly locate an extension in the catalog of extensions provided by the dev tools to the users
4	Keywords that can be used to search for extensions in the extension catalog provided by the dev tools to the users
5	Categories the extension should appear under on code.quarkus.io. This field can be omitted, the extension will still be listed on code.quarkus.io but won’t be categorized
6	Maturity status that could be `stable`, `preview`, `experimental`. It is up to extension maintainers to evaluate the maturity status and communicate it to the users
7	Link to the extension guide or documentation page
8	Link to an externally hosted image. This is used in the Quarkus dev tools as the extension icon. It should be square, and any resolution greater than 220 pixels. Supported formats are png, jpeg, tiff, webp, and svg. Alternatively, if you set the social media preview on the extension’s source code repository, the tools will pick up that image.
9	Codestart information
10	Configuration prefix

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

And here is the final version of the file included in the runtime JAR augmented with other information collected by the Quarkus Maven plugin:

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 version the extension was built with
2	The Quarkus version range this extension requires. Optional, and will be set automatically by using the `built-with-quarkus-core` as the minimum range.
3	Capabilities this extension provides
4	Direct dependencies on other extensions
5	Description that can be displayed to users. In this case, the description was copied from the `pom.xml` of the extension module but it could also be provided in the template file.
6	The source code repository of this extension. Optional, and will often be set automatically by using the `<scm>` information in the pom. In GitHub Actions builds, it will be inferred from the CI environment. For other GitHub repositories, it can be controlled by setting a `GITHUB_REPOSITORY` environment variable.
7	The sponsor(s) of this extension. Optional, and will sometimes be determined automatically from commit history.

META-INF/quarkus-extension.properties

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

Every runtime extension artifact must include this file. This file is read by the Quarkus bootstrap mechanism and is meant to contain only the information that is relevant for building or bootstrapping an applications. This file is typically generated by the corresponding Quarkus Maven or Gradle plugin when the extension project is built and shouldn’t be edited manually. The following properties may appear in this file:

Name Presence Description

Name	Presence	Description
`deployment-artifact`	Required	Points to the corresponding extension deployment artifact in the `groupId:artifactId[:classifier:type]:version` format
`parent-first-artifacts`	Optional	Comma-separated list of artifact keys (`groupId:artifactId:classifier:type`) that are to be loaded in a parent first manner. This can be used to work around issues where a given class needs to be loaded by the system ClassLoader.
`runner-parent-first-artifacts`	Optional	Comma-separated list of artifact keys that are to be loaded in a parent first manner in addition to those configured with `parent-first-artifacts` when an application is launched from a production binary package. This can be used to work around issues where a given class needs to be loaded by the system ClassLoader.
`excluded-artifacts`	Optional	Comma-separated list of artifact keys that will never be loaded by the class loader, and will not be packed into the final application.
`lesser-priority-artifacts`	Optional	Comma-separated list of artifact keys that will only be used to load a class or resource if no other artifact containing that class or resource exists. This is used in order to control the order of artifacts when multiple contain the same classes.
`removed-resources.*`	Optional	Resources that should be removed/hidden from dependencies. This allows for classes and other resources to be removed from dependencies, so they are not accessible to the application. This is a map of artifact key to a comma-separated list of resources to be removed. When running in dev and test mode these resources are hidden from the ClassLoader, when running in production mode these files are removed from the jars that contain them. Note that if you want to remove a class you need to specify the class file name. e.g. to remove com.acme.Foo you would specify com/acme/Foo.class.
`provides-capabilities`	Optional	List of capabilities this extension provides
`requires-capabilities`	Optional	List of capabilities this extension requires to be provided by other Quarkus extensions
`conditional-dependencies`	Optional	List of conditional dependencies this extension declares
`dependency-condition`	Optional	Dependency condition that has to be satisfied for a conditional dependency on this extension to be activated

deployment-artifact

Required

Points to the corresponding extension deployment artifact in the groupId:artifactId[:classifier:type]:version format

parent-first-artifacts

Optional

Comma-separated list of artifact keys (groupId:artifactId:classifier:type) that are to be loaded in a parent first manner. This can be used to work around issues where a given class needs to be loaded by the system ClassLoader.

runner-parent-first-artifacts

Optional

Comma-separated list of artifact keys that are to be loaded in a parent first manner in addition to those configured with parent-first-artifacts when an application is launched from a production binary package. This can be used to work around issues where a given class needs to be loaded by the system ClassLoader.

excluded-artifacts

Optional

Comma-separated list of artifact keys that will never be loaded by the class loader, and will not be packed into the final application.

lesser-priority-artifacts

Optional

Comma-separated list of artifact keys that will only be used to load a class or resource if no other artifact containing that class or resource exists. This is used in order to control the order of artifacts when multiple contain the same classes.

removed-resources.*

Optional

Resources that should be removed/hidden from dependencies. This allows for classes and other resources to be removed from dependencies, so they are not accessible to the application. This is a map of artifact key to a comma-separated list of resources to be removed. When running in dev and test mode these resources are hidden from the ClassLoader, when running in production mode these files are removed from the jars that contain them. Note that if you want to remove a class you need to specify the class file name. e.g. to remove com.acme.Foo you would specify com/acme/Foo.class.

provides-capabilities

Optional

List of capabilities this extension provides

requires-capabilities

Optional

List of capabilities this extension requires to be provided by other Quarkus extensions

conditional-dependencies

Optional

List of conditional dependencies this extension declares

dependency-condition

Optional

Dependency condition that has to be satisfied for a conditional dependency on this extension to be activated

META-INF/quarkus-config-roots.list

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

This file may appear in a runtime extension artifact as well as in a deployment one. This file must not be edited manually, it is generated as part of the extension project build process and contains a list of Java class names that are annotated with io.quarkus.runtime.annotations.ConfigRoot an extension provides.

META-INF/quarkus-javadoc.properties

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

Same as quarkus-config-roots.list, this file may appear in a runtime extension artifact as well in a deployment one. It is generated as part of the extension project build process from the descriptions of configuration options available in the classes annotated with io.quarkus.runtime.annotations.ConfigRoot and is not supported to be edited manually.

META-INF/quarkus-build-steps.list

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

This file may appear in a deployment extension artifact. It contains a list of classes that implement Quarkus build steps (methods annotated with io.quarkus.deployment.annotations.BuildStep). This file is generated as part of the extension project build process and must not be edited manually.