Quarkus 扩展元数据
Quarkus 扩展以 Maven JAR 工件的形式分发，应用程序和其他库可以依赖于这些工件。当使用 Quarkus 开发工具构建、测试或编辑 Quarkus 应用程序项目时，Quarkus 扩展 JAR 工件将通过其中存在的 Quarkus 扩展元数据文件在应用程序类路径上被识别。本文档描述了每个 Quarkus 扩展元数据文件的用途及其内容。
其中两个元数据文件具有相同的名称但不同的扩展名，分别是 quarkus-extension.yaml 和 quarkus-extension.properties。很容易将它们混淆，请小心。您通常会编辑 YAML 文件并将其跟踪在您的 SCM 中。虽然您可以手动管理 properties 文件，但如果您不手动管理，Quarkus 将在构建时生成它。 |
META-INF/quarkus-extension.yaml
每个运行时扩展工件必须包含此文件。此文件由 Quarkus 开发工具使用，用于显示有关扩展的信息、创建新项目或向现有项目添加扩展等。此文件不在应用程序构建或引导时使用。包含在此文件中的基本和必需的元数据可以由 Quarkus Maven 和 Gradle 插件在构建扩展工件时生成。但是，通常，扩展作者希望向 Quarkus 开发工具和用户提供有关扩展的更多信息。额外信息可以在扩展运行时模块的 resources 目录中的模板 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.net.cn/guides/rest" (7)
icon-url: "https://quarkus.net.cn/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 | 可用于在开发工具提供给用户的扩展目录中快速找到扩展的短名称 |
| 4 | 可用于在开发工具提供给用户的扩展目录中搜索扩展的关键字 |
| 5 | 扩展应在 code.quarkus.io 上显示的类别。此字段可以省略，扩展仍将在 code.quarkus.io 上列出，但不会被分类 |
| 6 | 成熟度状态，可以是 stable、preview、experimental。由扩展维护者评估成熟度状态并将其传达给用户 |
| 7 | 指向扩展指南或文档页面的链接 |
| 8 | 指向外部托管图像的链接。这在 Quarkus 开发工具中用作扩展图标。它应该是正方形的，并且任何分辨率大于 220 像素。支持的格式为 png、jpeg、tiff、webp 和 svg。或者，如果您 设置了社交媒体预览 在扩展的源代码存储库上，工具将拾取该图像。 |
| 9 | Codestart 信息 |
| 10 | 配置前缀 |
这是包含在运行时 JAR 中的文件的最终版本，其中包含 Quarkus Maven 插件收集的其他信息
name: "Quarkus REST (formerly RESTEasy Reactive)"
artifact: "io.quarkus:quarkus-rest:999-SNAPSHOT"
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." (1)
metadata:
short-name: "rest"
keywords:
- "jaxrs"
- "web"
- "rest"
categories:
- "web"
- "reactive"
status: "stable"
guide: "https://quarkus.net.cn/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" (2)
requires-quarkus-core: "[3.8,)" (3)
minimum-java-version: "17" (4)
capabilities: (5)
provides:
- "io.quarkus.rest"
- "io.quarkus.resteasy.reactive"
extension-dependencies: (6)
- "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"
scm-url: "https://github.com/quarkusio/quarkus" (7)
sponsor: A Sponsoring Organisation (8)| 1 | 可以向用户显示的描述。在本例中，描述是从扩展模块的 pom.xml 中复制的，但也可以在模板文件中提供。 |
| 2 | 构建扩展所用的 Quarkus 版本 |
| 3 | 此扩展需要的 Quarkus 版本范围。可选，并将通过使用 built-with-quarkus-core 作为最小范围自动设置。 |
| 4 | 运行此扩展所需的最低 Java 版本。将基于构建中使用的 maven.compiler.release 生成。 |
| 5 | 此扩展提供的 功能 |
| 6 | 对其他扩展的直接依赖 |
| 7 | 此扩展的源代码存储库。可选，并且通常会通过使用 pom 中的 <scm> 信息自动设置。在 GitHub Actions 构建中，将从 CI 环境中推断出来。对于其他 GitHub 存储库，可以通过设置 GITHUB_REPOSITORY 环境变量来控制。 |
| 8 | 此扩展的赞助商。可选，有时会根据提交历史记录自动确定。 |
META-INF/quarkus-extension.properties
每个运行时扩展工件必须包含此文件。此文件由 Quarkus 引导机制读取，旨在仅包含与构建或引导应用程序相关的信息。此文件通常由相应的 Quarkus Maven 或 Gradle 插件在构建扩展项目时生成，不应手动编辑。以下属性可能会出现在此文件中
| 名称 | 存在 | 描述 |
|---|---|---|
|
必需 |
指向 |
|
可选 |
以逗号分隔的工件键列表（ |
|
可选 |
以逗号分隔的工件键列表，除了使用 |
|
可选 |
以逗号分隔的工件键列表，这些工件永远不会被类加载器加载，也不会被打包到最终应用程序中。 |
|
可选 |
以逗号分隔的工件键列表，只有在不存在包含该类或资源的其他工件时，才会使用这些工件来加载类或资源。这用于在多个工件包含相同类时控制工件的顺序。 |
|
可选 |
应从依赖项中删除/隐藏的资源。这允许从依赖项中删除类和其他资源，因此应用程序无法访问它们。这是工件键到要删除的以逗号分隔的资源列表的映射。在开发和测试模式下运行时，这些资源从 ClassLoader 中隐藏，在生产模式下运行时，这些文件将从包含它们的 jar 中删除。请注意，如果要删除一个类，则需要指定类文件名。例如，要删除 com.acme.Foo，您需要指定 com/acme/Foo.class。 |
|
可选 |
此扩展提供的 功能 列表 |
|
可选 |
此扩展需要由其他 Quarkus 扩展提供的 功能 列表 |
|
可选 |
此扩展声明的 条件依赖 列表 |
|
可选 |
必须满足的 依赖条件，才能激活对此扩展的条件依赖 |
|
可选 |
应添加到在开发模式下启动应用程序的命令行中的标准 Java 命令行选项 |
|
可选 |
|
|
可选 |
以逗号分隔的标准 Java 命令行选项列表，这些选项不应被 Quarkus Maven 和 Gradle 插件默认预配置的值覆盖 |
|
可选 |
以逗号分隔的 |
META-INF/quarkus-config-roots.list
此文件可能会出现在运行时扩展工件以及部署工件中。此文件不得手动编辑，它是作为扩展项目构建过程的一部分生成的，并包含一个 Java 类名称列表，这些类使用扩展提供的 io.quarkus.runtime.annotations.ConfigRoot 进行注释。
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 注释的方法）。此文件是作为扩展项目构建过程的一部分生成的，不得手动编辑。
Quarkus 扩展 Maven 插件
quarkus-extension-maven-plugin 在 Quarkus 扩展 Maven 项目的运行时模块中配置，并服务于以下目的
-
验证扩展元数据配置；
-
生成扩展元数据；
-
检查扩展依赖是否符合 Quarkus 扩展依赖模型。
开发模式 JVM 选项
扩展可以预配置某些 Java 命令行选项，这些选项应添加到在开发模式下启动应用程序的命令行中。以下是如何在 quarkus-extension-maven-plugin 配置中配置此类选项
<plugin>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-extension-maven-plugin</artifactId>
<version>${quarkus.version}</version>
<executions>
<execution>
<phase>compile</phase>
<goals>
<goal>extension-descriptor</goal>
</goals>
<configuration>
<devMode>
<jvmOptions>
<add-modules>jdk.incubator.vector</add-modules>
<enable-preview/>
<enable-native-access>ALL-UNNAMED</enable-native-access>
</jvmOptions>
<xxJvmOptions>
<UseThreadPriorities>false</UseThreadPriorities>
</xxJvmOptions>
<lockJvmOptions>agentlib:jdwp</lockJvmOptions>
<lockXxJvmOptions>TieredStopAtLevel</lockXxJvmOptions>
</devMode>
</configuration>
</execution>
</executions>
</plugin>extension-descriptor 目标将生成具有相应属性的 META-INF/quarkus-extension.properties。一旦在开发模式下启动了依赖于此扩展的应用程序，日志将如下所示
[DEBUG] [io.quarkus.deployment.dev.DevModeCommandLineBuilder] (main) Adding JVM options from org.acme:quarkus-blue::jar
[DEBUG] [io.quarkus.deployment.dev.DevModeCommandLineBuilder] (main) enable-native-access: [ALL-UNNAMED]
[DEBUG] [io.quarkus.deployment.dev.DevModeCommandLineBuilder] (main) add-modules: [jdk.incubator.vector]
[DEBUG] [io.quarkus.deployment.dev.DevModeCommandLineBuilder] (main) enable-preview: []
[DEBUG] [io.quarkus.deployment.dev.DevModeCommandLineBuilder] (main) UseThreadPriorities: [false]
[DEBUG] [io.quarkus.deployment.dev.DevModeCommandLineBuilder] (main) org.acme:quarkus-blue::jar locks JVM options [TieredStopAtLevel, agentlib:jdwp]
[INFO] [io.quarkus.deployment.dev.DevModeCommandLineBuilder] Extension org.acme:quarkus-blue enables the C2 compiler which is disabled by default in Dev mode for optimal performance.
[INFO] [io.quarkus.deployment.dev.DevModeCommandLineBuilder] Extension org.acme:quarkus-blue disables the Debug mode for optimal performance. Debugging can still be enabled in the Quarkus plugin configuration or with -Ddebug on the command line.
[DEBUG] [io.quarkus.deployment.dev.DevModeCommandLineBuilder] (main) Executable jar: /home/<username>/app/target/acme-app-dev.jar
[DEBUG] Launching JVM with command line: /home/<username>/jdk/bin/java -Dquarkus-internal.serialized-app-model.path=/home/<username>/app/target/quarkus/bootstrap/dev-app-model.dat -javaagent:/home/<username>/.m2/repository/io/quarkus/quarkus-class-change-agent/{quarkus-verion}/quarkus-class-change-agent-{quarkus-version}.jar --enable-native-access=ALL-UNNAMED --add-modules=jdk.incubator.vector --enable-preview -XX:-UseThreadPriorities -Djava.util.logging.manager=org.jboss.logmanager.LogManager -jar /home/<username>/app/target/acme-app-dev.jar请注意，有几条 INFO 消息通知用户，Quarkus 默认在开发模式下使用的某些选项的值已被扩展首选项覆盖。具体来说，C2 编译器已重新启用，调试模式已禁用。如果用户有必要，仍然可以选择启用调试代理并禁用 C2 编译器，方法是显式设置相应的 Quarkus Maven 或 Gradle 插件参数值。
