1.4. 影响与早期版本兼容的更改

在红帽构建的 Quarkus 3.20 中，以下扩展将 Fabric8 Kubernetes 客户端从版本 6.13 升级到 7.1。

虽然 quarkus-openshift 和 quarkus-kubernetes 扩展使用 Fabric8，但它们的功能保持不变，因此您不需要为它们进行任何更新。

作为升级的一部分，io.quarkus:quarkus-test-openshift-client 模块已被删除。如果您的测试使用此模块，请迁移到 io.quarkus:quarkus-test-kubernetes-client，它提供等同的功能。如需更多信息，请参阅 Quarkus "Kubernetes Client" 指南中的 OpenShift 客户端 部分。

升级的 Fabric8 Kubernetes 客户端重新组织了一些模型类型和类，将部分模式移到不同的模块。要找到它们的新位置，请参阅官方 Fabric8 Kubernetes 客户端：从 6.x 迁移到 7.x 指南。

检查您的应用程序是否有任何受影响的依赖项、配置或 API 使用情况，并根据需要更新它们。然后，对应用程序进行全面的测试，以确保与 Fabric8 7.1 完全兼容。

这个更改需要手动干预。它不包括在 将应用程序迁移到红帽构建的 Quarkus 3.20 指南中的自动更新过程中。

在红帽构建的 Quarkus 3.15 中，许多扩展和配置属性被重命名为 RESTEasy Reactive 到 Quarkus REST 和 Reactive Messaging to Quarkus Messaging 的一部分。为了支持这个转换，引入了工件重新定位和配置回退。

在 Red Hat build of Quarkus 3.20 中，这些工件重新定位和配置回退已被删除。现在，您必须使用新的工件名称和配置属性。

如需了解更多背景信息，请参阅 "Release Notes for Red Hat build of Quarkus 3.15" 指南中的 RESTEasy Reactive 扩展重命名为 Quarkus REST 部分。

红帽构建的 Quarkus 3.20 更新区域设置处理，使其与 Mandrel 版本 24.2 及更新版本保持一致。

为确保所有应用程序的一致性区域设置行为，红帽构建的 Quarkus 应用了标准化的默认区域设置策略。使用下表来确定应用程序的行为根据您的区域设置变化。

en_US 区域总是嵌入到原生可执行文件中，无论 quarkus.locales 配置是什么。

检查应用程序在配置属性中的区域设置，如有必要，更新设置以避免行为的意外更改。

这个更改需要手动干预。它不包括在 将应用程序迁移到红帽构建的 Quarkus 3.20 指南中的自动更新过程中。

在红帽构建的 Quarkus 3.20 中，@Fallback.fallbackMethod （） 和 @BeforeRetry.methodName （） 的配置属性现在在构建时被解决，且无法在运行时更改。受影响的配置属性有：

此更改可确保正确反映配置和与原生镜像编译的兼容性。

在 Red Hat build of Quarkus 3.20 中，quarkus-smallrye-fault-tolerance 扩展包括 SmallRye Fault Tolerance 6.7.0，它没有破坏更改，但包括以下更新：

如需更多信息，请参阅 SmallRye Fault Tolerance 6.7.0 发行公告，其中包括到 programmatic API 迁移指南的链接，以及新配置属性的详情。Quarkus SmallRye Fault Tolerance 指南为这些配置属性提供了完整的参考。

从红帽构建的 Quarkus 3.20 开始，io.quarkus.scheduler.Scheduler 中的方法行为已更改。

当调度程序没有启动时，几乎所有方法现在都会抛出 UnsupportedOperationException。

要验证调度程序是否正在运行，您可以使用新方法 Scheduler#isStarted （）。

这个更改会影响来自 quarkus-scheduler 和 quarkus-quartz 扩展的调度程序实例。

从红帽构建的 Quarkus 3.20 开始，当您使用 development 和 test 模式时，管理界面默认侦听 localhost 接口，而不是 0.0.0.0。这个变化与主接口的行为一致。

在 Windows 上，适用于 Linux (WSL)的 Windows 子系统，管理和主接口将继续侦听 0.0.0.0。

如需更多信息，请参阅 Quarkus 管理界面参考指南。

在红帽构建的 Quarkus 3.20 中，配置已迁移到 @ConfigMapping 框架。这个更改弃用了旧的配置类，而是基于接口和方法签名的统一配置模型。

对于某些常用的配置类，兼容性层仍存在，但计划在以后的发行版本中删除。

从红帽构建的 Quarkus 3.20 开始，红帽构建器和运行时基础镜像已升级到使用 Red Hat Universal Base Image 9 (UBI 9)。

当从 UBI 8 升级到 UBI 9 时，请注意，系统依赖项、原生镜像构建或软件包和 GNU C 库(glibc)版本更新可能会影响应用程序的行为或运行时环境。根据需要检查和更新您的配置。

如果 UBI 9 时遇到问题，您可以手动切换到使用 UBI 8：

如需更多信息，请参阅以下资源：

在早期版本的 Red Hat build of Quarkus 中，当 Dev Services 被禁用或以 production 模式运行时，quarkus.datasource.reactive.url 和 quarkus.datasource.<datasource-name>.reactive.url 属性被隐式设置为未记录的默认，以带有数据库特定端口的 localhost 为目标。

从红帽构建的 Quarkus 3.20 开始，这些属性在禁用 Dev Services 时不再具有默认值，或者应用程序以 production 模式运行。如果没有设置属性，则会取消激活对应的数据源。如果应用程序尝试使用已停用的数据源，它将在启动时失败。详情请查看 Datasource usage failed if data is deactivated 或 no URL set release note。

如果您的应用程序需要活跃的数据源，并且希望它连接到 localhost 上的数据库，则必须明确设置 quarkus.datasource.reactive.url 或 quarkus.datasource.<datasource-name>.reactive.url 属性。例如：

quarkus.datasource.reactive.url=postgresql://localhost:5432/mydatabase

quarkus.datasource.reactive.url=postgresql://localhost:5432/mydatabase

在早期版本中，此配置被隐式设置。从这个版本开始，您必须定义用于激活数据源的 URL。

在以前的版本中，当 Dev Services 被禁用或生产模式中，红帽构建的 Quarkus 也会为数据源提供健康检查，即使 quarkus.datasource.jdbc.url, quarkus.datasource.<datasource.<datasource-name>.jdbc.url,quarkus.datasource.reactive.url, 或 quarkus.datasource.<datasource-name>.reactive.url 属性没有设置。这会导致对 JDBC 数据源成功进行不可靠的健康检查，对于被动数据源，几乎始终失败。

从红帽构建的 Quarkus 3.20 开始，没有 URL 的数据源不再贡献健康检查。为确保健康检查可用，请明确设置 quarkus.datasource.jdbc.url, quarkus.datasource.<datasource-name>.jdbc.url ,quarkus. datasource.reactive.url, 或 quarkus.datasource.<datasource.<datasource.<reactive.url 属性。

在 Red Hat build of Quarkus 3.20 中，即使数据源使用 quarkus.datasource.active=false 取消激活或缺少 URL，应用程序也会成功启动。当数据源首次访问时，通常会造成运行时失败，特别是在 Dev 服务被禁用或生产模式中时。

在这个版本中，如果红帽构建的 Quarkus 检测到使用了数据源，但会被取消激活或缺少 URL，则应用程序无法启动。

红帽构建的 Quarkus 现在在启动时强制执行更严格的验证，以便在早期捕获这些问题：

相同的验证适用于其 Flyway 和 Liquibase 的扩展，用于其 Flyway 和 LiquibaseFactory CDI Bean。

在 Red Hat build of Quarkus 3.20 中，quarkus-flyway 扩展将 Flyway 升级到版本 11，这会删除 cleanOnValidationError 配置参数。另外，调用 Flyway.validate （） 不再在验证错误时清除。

为了缓解这个变化，红帽构建的 Quarkus 3.20 引入了 quarkus.flyway.validate-at-start.clean-on-validation-error 配置属性，它提供与 cleanOnValidationError 类似的行为，但仅在应用程序启动时应用。

临时解决方案：如果您在明确调用 Flyway.validate （） 中需要之前 清理Error 的行为，请考虑捕获应用程序中验证错误，并使用 Flyway.clean （） 显式触发数据库清理。

这个更改需要手动干预。它不包括在 将应用程序迁移到红帽构建的 Quarkus 3.20 指南中的自动更新过程中。

如需更多信息，请参阅使用 Flyway 指南 的 Quarkus。

在 Red Hat build of Quarkus 3.20 中，Dev Services 使用的 IBM Db2 驱动程序和容器镜像已升级到 12 版本。

迁移应用程序到红帽构建的 Quarkus 3.20 指南中描述的自动更新将 IBM Db2 驱动程序和容器镜像升级到 12 版本。

查看 在升级到 Db2 Connect 12.1 驱动程序时有关 IBM 功能更改 的新许可证要求、配置步骤和 SSL/TLS 设置，以升级到 Db2 Connect 12.1。

这个更改需要手动干预。它不包括在 将应用程序迁移到红帽构建的 Quarkus 3.20 指南中的自动更新过程中。

在红帽构建的 Quarkus 3.20 中，Hibernate ORM 的 Bean Validation 集成的默认行为发生了变化。在以前的版本中，在数据定义语言(DDL)生成过程中不会考虑验证约束。在这个版本中，Hibernate ORM 默认在 DDL 中包括适用的验证限制，确保数据库模式与应用程序级别约束更加一致。

quarkus.hibernate-orm.validation.enabled 属性也已弃用。

有关迁移应用程序的这些更改和指南的更多信息，请参阅 迁移指南 3.19 或以下资源：

在 Red Hat build of Quarkus 3.20 中，quarkus.log aws.json 配置属性已弃用。要为日志记录启用 JSON 格式，请使用 quarkus.log aws.json.enabled 属性。

引进了这个更改来提高与 YAML 配置的兼容性，以前的结构需要使用特殊语法（如 ~ ）为 root 键分配值，从而导致混淆或容易出错的设置。

如需更多信息，请参阅 迁移指南 3.19。

在 Red Hat build of Quarkus 3.20 中，quarkus-opentelemetry 扩展引入了破坏更改，因为一些数据库出现的问题（如与 Redis 相关的值）被移到不同的软件包中。

OpenTelemetry 不维护数据库语义惯例的更改列表，因为它们尚不稳定。

如果您使用手动工具，可能需要手动干预。它不包括在 将应用程序迁移到红帽构建的 Quarkus 3.20 指南中的自动更新过程中。

在 Red Hat build of Quarkus 3.20 中，之前弃用的 quarkus-smallrye-opentracing 扩展和相关配置属性 quarkus.datasource.jdbc.tracing 已被删除。

quarkus-opentelemetry 扩展现在是首选的追踪解决方案。要使用 OpenTelemetry 启用 JDBC 追踪，请使用以下配置属性：

quarkus.datasource.jdbc.telemetry=true

quarkus.datasource.jdbc.telemetry=true

要迁移，请将 OpenTracing 扩展替换为 OpenTelemetry，并相应地更新您的配置。

从 Red Hat build of Quarkus 3.20 开始，如果您使用 quarkus-oidc-client 扩展，但没有将 OpenID Connect (OIDC)客户端配置为指向特定 URL，则 Keycloak 的 Dev Services 会自动以 dev 模式启动。

要禁用此行为，请在 application.properties 文件中添加以下属性：

quarkus.keycloak.devservices.enabled=false

quarkus.keycloak.devservices.enabled=false

在 Red Hat build of Quarkus 3.20 中，使用 WebAuthn4J 重新实施 quarkus-security-webauthn 扩展来增强安全性、与行业标准一致，并改进长期可维护性。

因此，这个更新与之前的扩展版本不兼容。

要平稳过渡到新实施，请使用以下信息：

此功能的状态从 preview 降级为 实验性，以允许进一步稳定。

如需更多信息，请参阅 Using Security with WebAuthn 指南。

这个更改需要手动干预。它不包括在 将应用程序迁移到红帽构建的 Quarkus 3.20 指南中的自动更新过程中。

在以前的版本中，红帽构建的 Quarkus 3.15 版本附带 @WithTestResource 版本被缺陷，因此没有宣布。

在 Red Hat build of Quarkus 3.20 中，这个问题已解决。在本发行版本中，早期 restrictToAnnotatedClass 字段已被 scope 替代。

在早期版本中，quarkus-junit5-mockito 依赖项被配置为使用 子类 模拟策略来创建模拟对象。

从红帽构建的 Quarkus 3.20 开始，依赖项现在被配置为默认 使用内联 模拟策略。

在 Red Hat build of Quarkus 3.20.0 中，quarkus-junit5-mockito 依赖项因为依赖项版本中有有意不匹配而临时无法正常工作。Mockito 的版本使用所需的 JUnit 5.11 或更高版本，但平台包含 JUnit 5.10。

要解决这个问题，红帽构建的 Quarkus 3.20.1 将 JUnit 升级到 5.12.1 版本。这个版本与 JUnit 和 Mockito 的版本一致，并恢复 quarkus-junit5-mockito 依赖项的兼容性。

此更新的影响应该最少。社区和 Camel Quarkus 中的测试没有显示任何回归问题。如需更多信息，请参阅相关问题 ：https://github.com/quarkusio/quarkus/issues/46858。

为确保所有 JUnit 工件的一致性，请导入 3.20.0 中使用的 JUnit BOM 版本，如下所示：

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>org.junit</groupId>
      <artifactId>junit-bom</artifactId>
      <version>5.10.5</version>
      <scope>import</scope>
      <type>pom</type>
    </dependency>
  </dependencies>
</dependencyManagement>

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>org.junit</groupId>
      <artifactId>junit-bom</artifactId>
      <version>5.10.5</version>
      <scope>import</scope>
      <type>pom</type>
    </dependency>
  </dependencies>
</dependencyManagement>

如果启用了 HTTP 压缩，quarkus.http.compress-media-types 配置属性定义要压缩的介质类型列表。在 Red Hat build of Quarkus 3.20 中，此属性的默认值已更改。新压缩的介质类型现在包含 application/json 和 application/xhtml+xml。

在 Red Hat build of Quarkus 3.20 中，REST 客户端配置更为严格，以减少检索配置所需的查找和组合数量：

从红帽构建的 Quarkus 3.20 开始，quarkus-qute 扩展会自动转义双引号(")、反斜杠(\)，如果设置了对应的模板变体，则 JSON 模板中的U+0000 到 U+001F）。扩展会自动为 src/main/resources/templates 目录中的模板分配一个变体。

默认情况下，java.net.URLConnection#getFileNameMap （） 决定模板文件的内容类型。您可以使用 quarkus.qute.content-types 配置来定义额外的后缀到内容类型映射。

要呈现未转义的值，请使用 raw 或 secure 属性，它们作为 java.lang.Object 的扩展方法实现，或者在 io.quarkus.qute.RawString 类中嵌套字符串值。

如需更多信息，请参阅 Quarkus "Qute 参考" 指南中的 Character escapes 部分。

在带有 quarkus-rest-jackson 扩展的 Quarkus 3.20 中，只有 ObjectMapperCustomizer Bean 应用到 Jackson JSON 处理器的默认 ObjectMapper 实例。

在早期版本中，所有自定义器 Bean （包括带有自定义限定符）都应用到默认的 ObjectMapper 实例。

这个更改需要手动干预。它不包括在 将应用程序迁移到红帽构建的 Quarkus 3.20 指南中的自动更新过程中。

如需更多信息，请参阅以下资源：

在以前的版本中，使用 quarkus-rest 扩展，带有空值的查询参数（如 ?foo= ）被反序列化，如下所示：

在 Red Hat build of Quarkus 3.20 中，此行为已更改：

相应地更新您的代码。

这个更改需要手动干预。它不包括在 将应用程序迁移到红帽构建的 Quarkus 3.20 指南中的自动更新过程中。

红帽构建的 Quarkus 3.20 弃用 quarkus-websockets 和 quarkus-websockets-client 扩展，该扩展实现了 Jakarta WebSocket 规格。

Red Hat build of Quarkus 计划在以后的发行版本中停止支持这些扩展。

为确保与即将推出的版本兼容，请迁移到 Quarkus WebSockets Next 扩展quarkus-websockets-next，它提供现代、效率更高的 WebSocket API。

如需更多信息，请参阅以下 Quarkus 资源：

这个更改需要手动干预。它不包括在 将应用程序迁移到红帽构建的 Quarkus 3.20 指南中的自动更新过程中。