Quarkus 扩展的成熟度矩阵
什么是一个好的 Quarkus 扩展？Quarkus 扩展应该提供哪些功能？当然，这取决于您正在构建的扩展。但是，我们发现许多扩展都有一些共同的属性。本文档将解释这些属性。我们可以将这些特性安排到一个成熟度矩阵中。以下是一个（虚构的）扩展的已填写矩阵的示例
这并没有定义一个确切的顺序，即使在单行中也是如此。不同的扩展有不同的目标，不同的开发人员对哪些功能最重要有不同的看法。您可能希望（例如）优先考虑出色的编程模型，而不是增强扩展的 Dev UI 磁贴。这没问题！
此外，并非每个步骤都适用于每个扩展。例如，如果您的扩展不依赖于外部服务，则不需要 Dev Service。
发布不处理所有内容的扩展的第一个版本是完全可以的。事实上，如果您的扩展永远没有达到更高级的功能，也是可以的。这是一个建议的途径，而不是最低功能集。
另请注意，此列表仅包含扩展的技术特性。您可能还想考虑如何共享您的扩展，以及它如何向世界展示自己。Quarkiverse Hub 上的新扩展清单提供了一个有用的列表，列出了扩展可以参与生态系统的方式。花一些时间在 quarkus-extension.yaml 文件中的元数据上也是一个好主意，Quarkus 工具会使用这些元数据。
以下是一些关于如何实现这些功能的指导。
运行模式
Quarkus 应用程序可以作为普通的基于 jar 的 JVM 应用程序运行，也可以在开发模式下进行实时编码，或者编译为本机二进制文件。每种环境对框架扩展都有不同的要求。
在 JVM 模式下工作
对于大多数扩展来说，这是最低的期望。在包装现有库时，这通常很容易实现；如果扩展提供的是全新的功能，则可能需要更多的工作。Quarkus 提供了用于 单元测试和集成测试 扩展的工具。
在开发模式下工作
在某些情况下，可能需要额外的工作来确保任何包装的库都可以容忍开发模式，因为类加载不同，热重载可能会破坏一些假设。扩展也可能希望为 开发模式添加一些特殊处理。要添加验证开发模式的自动化测试，您可以 添加扩展 QuarkusDevModeTest 的测试。
作为本机应用程序工作
对于许多库来说，本机模式支持是创建扩展的主要动机。有关可能需要的一些调整的更多讨论，请参阅 本机可执行文件支持指南。
开发者愉悦度
开发者愉悦度是一个重要的 Quarkus 原则。以下是一些有助于愉悦开发的扩展功能。
配置支持
扩展应该通过 与 Quarkus 配置模型集成来支持 Quarkus 的统一配置。《编写扩展指南》提供了更多关于 Quarkus 配置理念的指导。
CDI Bean
Quarkus 扩展应该旨在 通过 CDI 公开组件，以便用户应用程序可以以无摩擦的方式使用它们。将所有内容作为 CDI Bean 注入也有助于测试，尤其是 模拟。
Dev Service
Dev Services 通常与“连接”到某些东西的扩展相关，例如用于数据源的数据库、用于安全的 keycloak 实例、用于消息传递的 Apache Kafka 实例等。
要提供 Dev Service，请使用 DevServicesResultBuildItem 构建项。有关更多信息，请参阅 Dev Services 操作方法。
基本 Dev UI
每个扩展都会在 Dev UI 中获得一个磁贴。默认磁贴从 扩展元数据中提取信息，这也是花一些时间正确设置元数据的另一个原因。
扩展还使用 Dev UI 挂钩向用户呈现额外的信息。例如，该磁贴可以包含指向外部控制台的链接，或一个呈现简单文本指标的内部页面。请参阅 扩展开发人员的 Dev UI 指南。
丰富的 Dev UI
一些扩展提供了非常复杂的 Dev UI。例如，它们可能允许用户与正在运行的应用程序（在开发模式下）交互，响应重新加载，可视化应用程序指标，或 流式传输特定于应用程序的日志。Dev UI 指南还解释了这些更高级的选项。
愉悦的编程模型
Quarkus 的构建时理念意味着扩展可以整理 API 样板代码，并使编程模型更加简洁和富有表现力。一个好的起点通常是使用 Jandex 扫描用户代码中的注解和其他标记。尽管提供新的、令人愉悦的方式来做事是好的，但不破坏用户可能熟悉的正常模式非常重要。
有关此方面的灵感，请查看 简化的日志记录、使用 Panache 简化的 Hibernate ORM、@RestQuery 注解，或者 Quarkus 允许测试容器在 无需任何配置的情况下使用的方式。
Codestart 应用程序模板
Codestarts 是可用于为用户生成应用程序的模板。扩展可以 提供他们自己的 codestart 模板。
超音速亚原子性能
扩展应该使用构建时应用程序知识来消除浪费的运行时代码路径。我们称之为超音速亚原子性能。因为 Quarkus 将工作转移到构建阶段，Quarkus 应用程序应该具有快速启动、高吞吐量和低内存需求。性能调优是一个很大的主题，但扩展应该使用构建时应用程序知识来消除运行时浪费的运行时代码路径。
用生成的字节码替换反射
许多 Java 库大量使用反射来延迟运行时决策。Quarkus 旨在通过将逻辑移动到构建时来提高性能，从而减少不必要的动态性。扩展应该旨在用构建时代码替换反射。这可以通过 Jandex（一个“离线反射”库）来实现。可能还需要对现有库进行一些字节码转换。
有关如何消除反射以及性能优势的案例研究，请参阅 无反射 Jackson 序列化
虚拟线程支持
并非每个库都适合开箱即用地与虚拟线程一起使用。“为什么不是到处都是虚拟线程？” 解释了原因。
要使您的库与虚拟线程正常工作，您应该确保该库没有固定载体线程。Quarkus 具有 测试助手以自动方式进行这些检查。对于分派工作，您应该使用 Quarkus 管理的虚拟执行器。WebSockets-next 扩展使用虚拟调度程序和智能调度，是一个很好的示例。
热路径性能优化
尽管 Quarkus 为扩展性能提供了一些独特的机会，但扩展开发人员不应忘记 性能优化的基础知识。
添加基于 Mutiny 的 API
为了获得最大的可扩展性，超越反应式核心并启用完全反应式编程，请使用 Mutiny。大多数支持反应式编程模型的项目都提供两个不同的扩展，一个 -reactive 和一个普通的。例如，请参阅 ElasticSearch 和 ElasticSearch Reactive 扩展。
运维
开发者愉悦度很重要，但可观察性、可维护性和其他运维方面的考虑也很重要。这些特性中的许多特性默认情况下都带有 Quarkus 框架或 以可观察性为重点的扩展。但扩展可以做更多的事情。
日志记录
Quarkus 使用 JBoss Logging 作为其日志引擎，并 支持多个日志记录 API。（这是普通的 Java 日志记录，而不是 OpenTelemetry 日志记录。）
避免为不会影响正常运行的条件使用错误和警告。这些输出可能会在用户监控系统中引起误报。
定义健康端点
扩展可能希望 为特定于该扩展的健康标准定义特定于库的端点。要添加新端点，扩展应生成 NonApplicationRootPathBuildItem。
跟踪上下文
您应该测试使用扩展的应用程序的 OpenTelemetry 输出是否具有正确定义的 span。您可能需要做额外的工作来确保使用正确的跟踪 ID 创建 span。例如，具有反应式内部结构的扩展应支持 重复的上下文 以实现正确的上下文传播。
