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

随着红帽构建的 Quarkus 3.15，quarkus-spring-data-rest-extension 被升级，以便与最新的 Spring Boot 3 API 更新保持一致。

如果您在代码中使用 PagingAndSortingRepository 接口，则此升级可能会引入破坏更改。在以前的版本中，PagingAndSortingRepository 扩展 CrudRepository，它允许您的自定义存储库继承 CrudRepository 的方法。

要解决与这个更改相关的问题，您必须更新自定义存储库来直接扩展 ListCrudRepository 或 CrudRepository。此调整可确保持续访问所需的方法，并保持与更新的架构的兼容性。

在 Red Hat build of Quarkus 3.15 中，用来确定 Dev Services 是否启动的方法已更改。

在以前的版本中，要决定是否启动 Dev Services，红帽构建的 Quarkus 会检查是否定义了配置属性而无需扩展它。但是，如果属性扩展到空值，这种方法会导致问题。

现在，红帽构建的 Quarkus 首先检查扩展属性是否为空。当扩展属性结束为空时，这个更改可能会导致 Dev Services 意外启动。当未提供给定属性时，大多数 Dev Services 都会启动，例如 JDBC URL。

由于这个变化，您应该将配置属性调整为包含默认值，确保扩展的属性不为空。

例如，如果您使用 quarkus-test-oidc-server 组件模拟 OpenID Connect (OIDC)服务器，且 application.properties 文件包含：

%test.quarkus.oidc.auth-server-url=${keycloak.url}/realms/quarkus/

将属性值改为：

%test.quarkus.oidc.auth-server-url=${keycloak.url:replaced-by-test-resource}/realms/quarkus/

这样，如果没有定义 keycloak.url，默认的 replaced-by-test-resource 值可防止属性扩展到空值，从而避免 Dev Services 的意外启动。如果表达式中没有定义变量，则整个表达式将为空。

红帽构建的 Quarkus 3.15 将 GraalVM SDK 依赖项更新为版本 23.1.2，更正早期的超天并确保与最新的 GraalVM 功能兼容。

如果您使用 GraalVM 替换开发扩展，请将 org.graalvm.sdk:graal-sdk 依赖项替换为 org.graalvm.sdk:nativeimage。nativeimage 工件仅包含替换所需的类，使其更精简。

您可以通过运行 Migrating applications to Red Hat build of Quarkus 3.15 指南中所述的自动更新来应用此更改。

在 Red Hat build of Quarkus 3.15 中，Infinispan 15 组件已升级到 15.0 版本。

在之前的发行版本中，在 Infinispan 15 集成前，您可以使用以下 .Query.java 代码运行查询：

@Inject
RemoteCache<String, Book> booksCache;

…

QueryFactory queryFactory = Search.getQueryFactory(booksCache);
Query query = queryFactory.create("from book_sample.Book");
List<Book> list = query.execute().list();

但是，在这个版本里，此代码不再可以正常工作，因为 RemoteCache 现在是一个 @ApplicationScoped 代理 bean 和 Search.getQueryFactory 引发 ClassCastException。

要解决这个问题，使用 RemoteCache API 中的 查询 方法删除间接，如下所示：

@Inject
RemoteCache<String, Book> booksCache;

…

Query<Book> query = booksCache.<Book>query("from book_sample.Book");
List<Book> list = query.execute().list();

您必须手动应用此更改。Migrating applications to Red Hat build of Quarkus 3.15 指南中所述的自动更新不包括它。

在 Red Hat build of Quarkus 3.15 中，以下与打包相关的属性已被重命名或更改。如果您在配置中使用原始属性，它们仍可以正常工作，但会显示警告。

您可以通过运行 Migrating applications to Red Hat build of Quarkus 3.15 指南中所述的自动更新来应用此更改。

更新任何代码和配置文件，以反映这些更改并在构建过程中停止警告信息。

在 Red Hat build of Quarkus 3.15 中，弃用的 ProfileManager 类和 ProfileManager"getActiveProfile 方法被删除，因为 ProfileManager 无法处理多个配置集。

在这个版本中，需要以下配置更改：

要检索活跃的配置集，请使用 io.quarkus.runtime.configuration.ConfigUtils"getProfiles API。

您必须手动应用此更改。Migrating applications to Red Hat build of Quarkus 3.15 指南中所述的自动更新不包括它。

在早期版本中，会发现一个不需要的行为，无论生成的工件类型是什么，都会在构建系统的输出目录中生成 quarkus-app 目录。

在 Red Hat build of Quarkus 3.15 中，构建过程只为 fast-jar 软件包创建 quarkus-app 目录，这是默认的工件类型。如果您为不同的工件类型配置构建，则不会创建 quarkus-app 目录。

在 Red Hat build of Quarkus 3.15 中，用于生成运行时文件和配置文件的扩展注解处理器已被重新开发，提供了更大的灵活性，但使用新限制：

我们鼓励迁移至新的 @ConfigMapping 接口，但计划对旧的 @ConfigRoot 类的支持，以确保顺利迁移。计划稍后宣布弃用计划。

您必须手动应用此更改。Migrating applications to Red Hat build of Quarkus 3.15 指南中所述的自动更新不包括它。

在 Red Hat build of Quarkus 3.15 中，Hibernate ORM 扩展会验证它在运行时连接的数据库版本至少与构建时配置的成本至少相同。即使配置依赖于红帽构建的 Quarkus 支持的最低数据库版本，也会进行这个验证。

在这个版本中，旨在提醒应用程序开发人员是否尝试使用 Hibernate ORM 或红帽构建的 Quarkus 不再支持的数据库版本。如果您尝试使用不再支持的数据库版本，红帽构建的 Quarkus 不会启动并抛出异常。

这个更改会影响依赖以下数据库版本的应用程序：

如果您无法将数据库升级到受支持的版本，您仍然可以尝试使用它，虽然某些功能可能无法正常工作。要继续使用较早的、不受支持的数据库版本，请明确设置 db-version，如有必要，还要设置 dialect。

您必须手动应用此更改。Migrating applications to Red Hat build of Quarkus 3.15 指南中所述的自动更新不包括它。

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

在 Red Hat build of Quarkus 3.15 中，几个 Dev Services 的默认镜像更新至以下版本：

您可以通过运行 Migrating applications to Red Hat build of Quarkus 3.15 指南中所述的自动更新来应用此更改。

要使用这些服务的特定版本或分发，您必须手动覆盖应用程序属性中的默认容器镜像。

如需更多信息，请参阅 Quarkus "Dev Services for Elasticsearch" 指南中的 配置 镜像部分。

在 Red Hat build of Quarkus 3.15 中，Hibernate Object/Relational Mapping (ORM) auto-flush 功能已被优化。

现在，默认情况下，在运行 Hibernate 查询语言(HQL)、Java Persistence Query Language (JPQL)或原生查询之前，如果数据库检测到这些更改可能会影响查询结果，则 Hibernate ORM 只清除待处理的更改。

在大多数情况下，这种优化将提高应用程序的性能，如更有效地批处理，但可能会出现以下问题：

如果要恢复到之前的行为并选择替代的默认值，则会引入 quarkus.hibernate-orm.flush.mode 配置属性。将此属性设置为 always:quarkus.hibernate-orm.flush.mode=always。

您必须手动应用此更改。Migrating applications to Red Hat build of Quarkus 3.15 指南中所述的自动更新不包括它。

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

在 Red Hat build of Quarkus 3.15 中，Hibernate ORM 扩展已升级到 Hibernate ORM 6.6，并包括以下有问题的更改：

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

quarkus-hibernate-search-orm-outbox-polling 扩展依赖于数据库中的系统表，Hibernate ORM 连接，以及红帽构建的 Quarkus 3.15，这些系统表的 schema 可能会改变。

如果使用此扩展，则需要迁移数据库架构。有关如何迁移数据库模式的详情，请参考"Hibernate 搜索迁移"指南中的 Outbox 轮询数据库表 部分。

如果无法更新数据库模式，请应用以下设置来恢复之前的默认值：

您必须手动应用此更改。Migrating applications to Red Hat build of Quarkus 3.15 指南中所述的自动更新不包括它。

在 Red Hat build of Quarkus 3.15 中，io.quarkus:quarkus-panache-common 注解处理器已被删除，因为在使用带有 Panache 的 Hibernate ORM 时，不再需要它用于外部定义的实体，使用 Panache 的 Hibernate Reactive with Panache。

在早期版本中，此注解处理器会在 classpath 中找到时自动运行。如果您在构建工具中覆盖了一组注解处理器，则需要显式添加它。

从注解处理器列表中删除对 io.quarkus:quarkus-panache-common 的所有引用。

您可以通过运行 Migrating applications to Red Hat build of Quarkus 3.15 指南中所述的自动更新来应用此更改。

<build>
    <plugins>
        <!-- other plugins -->
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <version>3.13.0</version> <!-- Necessary for proper dependency management in annotationProcessorPaths -->
            <configuration>
                <annotationProcessorPaths>
                    <path>
                        <groupId>io.quarkus</groupId>
                        <artifactId>quarkus-panache-common</artifactId>
                    </path>
                </annotationProcessorPaths>
            </configuration>
        </plugin>
        <!-- other plugins -->
    </plugins>
</build>

dependencies {
    annotationProcessor "io.quarkus:quarkus-panache-common"
}

在 Red Hat build of Quarkus 3.15 中，Quarkus Messaging extensions 中 同步方法的 执行模式现在默认为 worker 线程。在早期版本中，这些方法在 Vert.x 事件循环(I/O 线程)上运行。

例如，现在在 worker 线程上默认调用以下处理方法，而不是 Vert.x I/O 线程：

package org.acme;

import org.eclipse.microprofile.reactive.messaging.Incoming;
import org.eclipse.microprofile.reactive.messaging.Outgoing;

@Incoming("source")
@Outgoing("sink")
public Result process(int payload) {
    return new Result(payload);
}

要恢复到更早的行为，您可以使用 quarkus.messaging.blocking.signatures.execution.mode 配置属性。

可能的值有：

您还可以使用 @Blocking 和 @NonBlocking 注解来基于每个方法调整执行模式：

package org.acme;

import io.smallrye.common.annotation.NonBlocking;
import org.eclipse.microprofile.reactive.messaging.Incoming;

@Incoming("source")
@NonBlocking
public void consume(int payload) {
    // called on I/O thread
}

通过注解方法 @NonBlocking，您可以确保在 Vert.x 事件循环(I/O 线程)中调用它。

检查您的消息传递方法，以确保它们在所需的执行模式下运行，并根据需要更新您的代码或配置。

您必须手动应用此更改。Migrating applications to Red Hat build of Quarkus 3.15 指南中所述的自动更新不包括它。

在 Red Hat build of Quarkus 3.15 中，smallRye Reactive Messaging 扩展已被重命名为 quarkus-messaging sHistoryLimit，以反映它们对被动和阻塞工作负载的支持。

Maven 重新定位过程已被实现。您可以通过运行 Migrating applications to Red Hat build of Quarkus 3.15 指南中所述的自动更新来应用此更改。

将项目中旧扩展名称的所有实例替换为新名称。

配置 root 也已从 quarkus.smallrye-reactive-messaging. 更新至 quarkus.messaging。自动回退机制已就位，可恢复到旧的配置属性（如有必要）。

更新您的代码和配置，以反映这些更改。

在 Red Hat build of Quarkus 3.15 中，quarkus.opentelemetrySetConfiguration 命名空间下 的所有配置属性都已被删除。

这些属性已弃用，并保持在版本 3.2 和 3.8 中的向后兼容性。由于它们现已在 3.15 中删除，您必须进行以下更改来迁移应用程序：

更新您的代码和配置，以使用这些新属性和值。

您必须手动应用此更改。Migrating applications to Red Hat build of Quarkus 3.15 指南中所述的自动更新不包括它。

在 Red Hat build of Quarkus 3.15 中，弃用的注解 io.opentelemetry.extension.annotations.WithSpan 已被删除。更新您的代码，以使用新的 io.opentelemetry.instrumentation.annotations.WithSpan 注解。

检查并更改依赖旧注解的任何配置或代码，以确保与此次更新兼容。

您必须手动应用此更改。Migrating applications to Red Hat build of Quarkus 3.15 指南中所述的自动更新不包括它。

在 Red Hat build of Quarkus 3.15 中，OpenTelemetry (OTel) SDK 已升级到版本 1.39.0，并检测到版本 2.5.0。此升级强制使用 OpenTelemetry HTTP 语义约定中定义的新约定稳定性迁移。它还完成删除已弃用的标准。更新依赖于这些约定的任何代码或配置。

另外，quarkus.otel.semconv-stability.opt-in 系统属性已被删除，因为 opting-in 不再被支持。更新依赖于此属性的任何代码或配置。

您必须手动应用此更改。Migrating applications to Red Hat build of Quarkus 3.15 指南中所述的自动更新不包括它。

在 Red Hat build of Quarkus 3.15 中，OpenTelemetry (OTel) REST 客户端 span 名称现在包含 HTTP 请求方法和路径，例如 GET /hello。较早的 REST 客户端范围名称仅包含 HTTP 方法。

更新依赖于 REST 客户端范围名称特定格式的代码或配置。

您必须手动应用此更改。Migrating applications to Red Hat build of Quarkus 3.15 指南中所述的自动更新不包括它。

在 Red Hat build of Quarkus 3.15 中，由数据库操作生成的 span 名称因我们使用的库中的更新而改变。

例如，在更改之前，用于创建数据库表的旧 span 名称是 DB Query。现在，在这一变化中，新范围名称为 CREATE TABLE {table_name}。

这个新的命名规则提供了更描述性和有意义的范围名称，可以准确反映执行的特定数据库操作。

因此，您可能会在可观察性工具中发现由数据库操作生成的 span 的不同名称。

检查和更新依赖于旧范围名称的任何自定义监控配置、警报或仪表板，以适应新的命名规则。

您必须手动应用此更改。Migrating applications to Red Hat build of Quarkus 3.15 指南中所述的自动更新不包括它。

有关数据库范围命名约定和最佳实践的更多信息，请参阅 OpenTelemetry 数据库 Span Semantic Conventions 规格。

在早期版本中，一些配置属性被错误地位于 quarkus.health 配置 root 下。

在 Red Hat build of Quarkus 3.15 中，这些属性已重新定位到 quarkus.smallrye-health 配置 root 以实现一致性：

在 Red Hat build of Quarkus 3.15 中，带有旧配置 root 的属性已被弃用，计划在以后的发行版本中删除。更新任何代码或配置，以使用新的属性位置。

您必须手动应用此更改。Migrating applications to Red Hat build of Quarkus 3.15 指南中所述的自动更新不包括它。

使用红帽构建的 Quarkus 3.15，Java Keystroke (JKS)不再是默认的密钥存储和信任存储格式。

反之，红帽构建的 Quarkus 根据文件扩展名决定格式，如下所示：

如果您的文件没有使用其中一个扩展，您必须设置文件格式。

例如，要指定 JKS 格式，请设置以下配置值：

在 Red Hat build of Quarkus 3.15 中，quarkus.oidc.authentication.user-info-required 属性现在会在 io.quarkus.oidc.UserInfo 注入 REST 端点时自动设置为 true。这个更改删除了手动配置此属性的需要，因为用户Info 通常会在使用属性时注入。

但是，在更复杂的设置中，如果多个 OIDC 租户安全端点，一些租户不支持 UserInfo，则这个更改可能会导致租户初始化失败。只有在不支持 UserInfo 的租户仍然配置为获取它时，会出现这种情况，可能会导致该租户保护的请求失败。

为了避免多租户设置中的此类故障，在不支持 UserInfo 的租户中将特定于 租户的 quarkus.oidc.<tenant-id>.authentication.user-info-required 属性设置为 false。这样可确保只有支持 UserInfo 的租户强制其收购。

您必须手动应用此更改。Migrating applications to Red Hat build of Quarkus 3.15 指南中所述的自动更新不包括它。

在 Red Hat build of Quarkus 3.15 中，Quarkus BOM 不再强制执行 org.junit-pioneer 的版本：junit-pioneer 依赖项。如果您在项目中使用此依赖项，则必须在构建文件中明确指定其版本。

要避免构建问题，请在 pom.xml 或 build.gradle 文件中定义版本；例如：

<properties>
    ...
    <junit-pioneer.version>2.2.0</junit-pioneer.version>
    ...
</properties>

您必须手动应用此更改。Migrating applications to Red Hat build of Quarkus 3.15 指南中所述的自动更新不包括它。

在 Red Hat build of Quarkus 3.15 for Quarkus REST （以前称为 RESTEasy Reactive）中），HAL）打包程序类的签名已被修改为包含集合中元素的类型：

在每次代码中使用 HAL 打包程序类时，添加适当的 type 参数。

您必须手动应用此更改。Migrating applications to Red Hat build of Quarkus 3.15 指南中所述的自动更新不包括它。

@Path("/records")
public class RecordsResource {

    @Inject
    HalService halService;

    @GET
    @Produces({ MediaType.APPLICATION_JSON, RestMediaType.APPLICATION_HAL_JSON })
    @RestLink(rel = "list")
    public HalCollectionWrapper<Record> getAll() {
        List<Record> list = // ...
        HalCollectionWrapper<Record> halCollection = halService.toHalCollectionWrapper( list, "collectionName", Record.class);
        // ...
        return halCollection;
    }

    @GET
    @Produces({ MediaType.APPLICATION_JSON, RestMediaType.APPLICATION_HAL_JSON })
    @Path("/{id}")
    @RestLink(rel = "self")
    @InjectRestLinks(RestLinkType.INSTANCE)
    public HalEntityWrapper<Record> get(@PathParam("id") int id) {
        Record entity = // ...
        HalEntityWrapper<Record> halEntity = halService.toHalWrapper(entity);
        // ...
        return halEntity;
    }
}

虽然使用构造器创建 HAL 包装器仍可以正常工作，但该方法可能在以后的版本中被弃用。因此，开始使用 HalService bean 公开的帮助程序方法。

如需更多信息，请参阅"Quarkus REST"指南中的 Web 链接支持 部分。

在早期版本中，Quarkus REST （以前称为 RESTEasy Reactive）过滤器也会运行，即使请求的资源不是 REST 资源。在 Red Hat build of Quarkus 3.15 中，该行为已更改。现在，Quarkus REST 过滤器仅在 REST 资源上运行。

如果您需要过滤器应用到非Quarkus REST 资源，您可以通过为 NotFoundException 添加自定义 ExceptionMapper 来完成此操作，如下例所示：

package io.quarkus.resteasy.reactive.server.test.customproviders;

import jakarta.ws.rs.NotFoundException;
import jakarta.ws.rs.core.Response;
import jakarta.ws.rs.ext.ExceptionMapper;
import jakarta.ws.rs.ext.Provider;

@Provider
public class NotFoundExeptionMapper implements ExceptionMapper<NotFoundException> {
    @Override
    public Response toResponse(NotFoundException exception) {
        return Response.status(404).build();
    }
}

使用这个 ExceptionMapper，Quarkus REST 处理 "Not Found" 资源，允许过滤器按预期运行。在以前的版本中，过滤器总是在非 REST 资源上运行，这使得其他扩展很难有效地处理"未找到"场景。

您必须手动应用此更改。Migrating applications to Red Hat build of Quarkus 3.15 指南中所述的自动更新不包括它。

在 Red Hat build of Quarkus 3.15 中，io.quarkus.qute.TemplateInstance 类不再注册为非阻塞类型。因此，如果 Jakarta REST （以前称为 JAX-RS）资源方法返回 TemplateInstance 对象，它现在默认被视为阻止。

要恢复之前的非阻塞行为，请将 @io.smallrye.common.annotation.NonBlocking 注解应用到资源方法。

您必须手动应用此更改。Migrating applications to Red Hat build of Quarkus 3.15 指南中所述的自动更新不包括它。

在 Red Hat build of Quarkus 3.15 中，RESTEasy Reactive 扩展已重命名为 quarkus-rest fluentd，以反映它们对被动和阻塞工作负载的支持。

Maven 重新定位过程已被实现。您可以通过运行 Migrating applications to Red Hat build of Quarkus 3.15 指南中所述的自动更新来应用此更改。

将项目中旧扩展名称的所有实例替换为新名称。

大多数新扩展名称遵循以下命名约定：

配置根也已更新：

自动回退机制已就位，可恢复到旧的配置属性。

在 Red Hat build of Quarkus 3.15 中，quarkus-webjars-locator 扩展被重命名为 quarkus-web-dependency-locator，并改进了 mvnpm(Maven NPM)和 importmaps。

更新您的代码和配置，以使用新的扩展名称。

您必须手动应用此更改。Migrating applications to Red Hat build of Quarkus 3.15 指南中所述的自动更新不包括它。

如需更多信息，请参阅 Quarkus Web 依赖项 locator 指南。