将应用程序迁移到红帽构建的 Quarkus 3.27

• Quarkus 迁移指南 3.26：旧的配置类支持已不存在
• Quarkus Sunsetting 传统配置类博客

• 要迁移，请按如下所示替换条件构建步骤：

  • 之前使用的代码：

    @BuildStep(onlyIf = IsDevelopment.class)
    JsonRPCProvidersBuildItem createJsonRPCService() {
        return new JsonRPCProvidersBuildItem(...);
    }

    Copy to Clipboard Toggle word wrap

  • 更新的代码：

    @BuildStep
    JsonRPCProvidersBuildItem createJsonRPCService() {
        return new JsonRPCProvidersBuildItem(...);
    }

    Copy to Clipboard Toggle word wrap

• 类型：字符串
• 默认值： prod
• 环境变量： QUARKUS_TEST_INTEGRATION_TEST_PROFILE
• 配置时间：在构建时修复

• 更新应用程序依赖项以删除 Derby JDBC 驱动程序
• 更新 application.properties 或 application.yaml，以配置不同的数据库
• 将现有的 Derby 数据库模式和数据迁移到新数据库中

• Elasticsearch 版本 9.1
• OpenSearch 版本 3.1

• API 更改

  • 弃用的 Session 方法已被删除，或被 JPA equivalents 替代。

    要应用标记为 "Automatic" 的更改，请运行 Migrating applications to Red Hat build of Quarkus 3.27 指南中所述的更改，否则手动执行任何其他步骤。

    Expand

    弃用的 Session 方法	新的 JPA 等效	更新过程
    load (…​) without a lock 选项	getReference(…​)	自动
    get(…​)	find(…​)	自动
    delete(…​)	remove(…​)	自动
    save(…​)	persist(…​)	自动
    update(…​)	merge(…​)	Manual
    load (…​) with a lock 选项	find(…​)	Manual
    saveOrUpdate(…​)	持久性（新实体）/合并（持久性，然后分离的实体）	Manual

    Show more
    注意

    当从更新方法迁移到 合并 方法时，请注意以下区别：

    • 合并 会返回附加到持久性上下文的实体实例。确保您使用该实体并丢弃作为参数传递的实体。
    • 为确保正确合并，合并 可以加载实体。当在连续的多个实体中使用 合并 时，可能会发生 N+1 选择的问题。要避免这个问题，请在 合并 调用前载入会话中的所有实体，例如使用 Session"findMultiple。

    要应用此更改，请手动执行本发行注记中介绍的其他步骤。

    如需更多信息，请参阅 Hibernate ORM Defer to JPA。

  • 弃用的注解已被删除或替换为 JPA equivalents。要查看受影响的注解，请参阅 Hibernate ORM Annotations。

  • @Cascade 和 CascadeType 已被弃用，并被 JPA equivalents 替代，如 @OneToMany (cascade = …​)。

    要应用此更改，请运行 Migrating applications to Red Hat build of Quarkus 3.27 指南中的自动更新过程。

  • 代理自定义已更改。如果您使用 @Proxy，请考虑 @ConcreteProxy，或使用 Session#getReference 或 Hibernate"unproxy 方法。如需更多信息，请参阅 Hibernate ORM 替换 @Proxy。
  • org.hibernate.Metamodel 已被删除，并被 org.hibernate.metamodel.model.domain.JpaMetamodel 取代。
  • UserType 和 CompositeType 方法签名不再引用内部或服务提供商接口(SPI)类型。如需更多信息，请参阅 Hibernate ORM UserType 和 CompositeUserType 更改。
  • 各种 JDBC 类型已移至内部软件包。要将属性映射到这些类型，请使用 @JdbcTypeCode 而不是 @JdbcType。
  • LockOptions 类已弃用；受影响的方法有涉及 LockMode 的替代方案。LockOptions 类的一些已弃用的功能也已被删除。如需更多信息，请参阅 Hibernate ORM LockOptions。
  • Session#getLobHelper 方法已弃用。使用 Hibernate"getLobHelper 替代。如需更多信息，请参阅 Hibernate ORM Session#getLobHelper。

• 行为更改

  • 更严格的注解验证

    现在，错误的映射注解会引发异常，而不是被忽略。示例包括冲突 @Basic 和 @ManyToOne 注释，或者 @Id 和 @Version 上的属性转换器使用。如需更多信息，请参阅 Hibernate ORM 域模型验证。

  • 第二级缓存使用情况

    StatelessSession 现在默认使用第二级缓存。此更改会影响迁移使用第二级缓存和 无状态会话 的应用。如需更多信息，请参阅 Hibernate ORM StatelessSession 和 second-Level 缓存。

  • 批处理操作更改

    StatelessSession 不遵循 quarkus.hibernate-orm.jdbc.statement-batch-size 设置。由于 StatelessSession 操作旨在立即执行，因此不需要隐式批处理操作。您可以使用显式批处理操作，如 'insertMultiple （）'。如需更多信息，请参阅 Hibernate ORM StatelessSession 和 JDBC 批处理。

  • 查询验证

    不再接受模糊的查询字符串。这主要会影响 type-unsafe 查询，当没有将类传递给 Session""createQuery 时，或使用 Panache 创建查询时。现在，没有 select 子句的查询，但带有非抓取 加入，现在必须指定预期的行为。如需更多信息，请参阅 带有隐式 SELECT 和没有显式结果类型的 Hibernate ORM Query。

  • 对由原生查询返回的日期和时间值的更改

    在以前的版本中，java.sql 类型用于表示原生查询返回的日期和时间类型。现在，如果没有特定类型指令，原生查询会返回 java.time 类型。如需更多信息，请参阅 原生查询返回的 Hibernate ORM 临时类型。

• 最小数据库版本

  最低所需的数据库版本已更新，以使用相应供应商仍然支持最旧的版本。

  请特别注意以下更新：

  • IBM DB2：从 10.5 更新至 11.1 的最低版本
  • MariaDB：将最小版本从 10.4 更新至 10.6
  • Microsoft SQL Server：从 11.0 (2012)更新至 12.0 (2014)的最低版本.

  • PostgreSQL：从 12.0 更新至 13.0 的最低版本

    有关当前最小版本的更多信息，请参阅 Hibernate ORM 支持的 dialects。

• MySQL/MariaDB 存储引擎

  使用 quarkus.hibernate-orm.dialect.storage-engine 设置 MySQL/MariaDB 存储引擎已被弃用。使用 quarkus.hibernate-orm.dialect.mariadb.storage-engine=…​ 或 quarkus.hibernate-orm.dialect.mysql.storage-engine=…​。

• DDL/schema 更改

  • 自定义数据库初始化脚本（特别是 H2 数据库）可能需要更改，以避免使用引号。
  • 现在，基本阵列被映射到数据库中的正确阵列结构，而不是序列化为二进制数据。您可以通过将 quarkus.hibernate-orm.unsupported-properties."hibernate.type.preferred_array_jdbc_type" 设置为 VARBINARY 来恢复此行为。否则，如果您的实体映射包含数组，则需要对数据库 schema 和手动更新数据。如需更多信息，请参阅 Hibernate ORM Array 映射更改。
  • char/Character 属性现在映射到 varchar (1)，而不是 char (1)。
  • 在 Oracle 和 Microsoft SQL Server 上，时间戳属性有不同的默认子秒精度。
  • 在 Oracle 上，float 和 double 属性映射到 binary_float 和 binary_double，而不是 float (p)、real 或 double 精度类型。如需更多信息，请参阅 Hibernate ORM 更改会影响 DDL。

• 注解处理器更改

  • Hibernate ORM 注解处理器的 Maven 工件已从 org.hibernate.orm:hibernate-jpamodelgen 改为 org.hibernate.orm:hibernate-processor。在 Maven 中，更新 annotationProcessorPath。

  • 注释处理器 org.hibernate.jpamodelgen.rhgsMetaModelEntityProcessor 已弃用，而使用 org.hibernate.processor.HibernateProcessor。

    要应用此更改，请运行 Migrating applications to Red Hat build of Quarkus 3.27 指南中的自动更新过程。

• Hibernate ORM 组件的上下文和依赖项注入(CDI)限制

  • 某些可插拔组件（可能在 CDI 初始化之前检索）不再是 CDI Bean。

    如果您需要提供此类组件的自定义实施，并且需要访问该实施中的 CDI，请考虑使用 Arc.container （）.instance (OtherBean.class).get （） 来检索其他 Bean。有关受影响的组件列表，请参阅 迁移指南 3.24。

• JSON/XML 映射

  在以前的版本中，在数据库中为 JSON/XML 序列化的 Hibernate ORM 的"格式映射器"默认依赖于全局 REST 层序列化设置。

  现在，最好隔离数据库层和 REST 层序列化，以帮助确保数据库格式稳定性并防止不必要的迁移。但是，如果满足以下条件，当前的发行版本默认会失败：

  • 您的应用程序有一个 Hibernate 映射，涉及存储在数据库中的 XML 或 JSON。
  • REST 层的 XML 或 JSON 序列化设置是自定义的。

  如果发生这种情况，您可以更新数据库序列化设置：

  • 基于 Jacks 的 JSON 序列化

    如果应用程序中应用的 ObjectMapper 自定义不会影响数据库中存储的 JSON 格式，请通过指定 quarkus.hibernate-orm.mapping.format.global=ignore 来绕过该 ObjectMapper。

    否则，实施自定义 FormatMapper bean。首先，将格式映射器委派给全局 REST 层序列化。

    如需更多信息，请参阅 Quarkus "使用 Hibernate ORM 和 Jakarta Persistence" 指南中的 迁移指南 3.26 和 自定义 JSON/XML serialization/deserialization 部分。

    然后，执行以下操作之一：

    • 如果要依赖全局配置的 ObjectMapper 并依赖于 REST 层序列化需求，请继续使用此委派格式映射器。
    • 准备并测试迁移脚本以更新 JSON 数据。您可以使用 Hibernate ORM 的默认格式，或者根据您的需要调整 FormatMapper 实现格式化 JSON。

  • 基于 JSON-B 的 JSON 序列化

    这个场景与基于 Jackson 的映射程序相同。如需更多信息，请参阅 迁移指南 3.26。

  • 基于 JAXB 的 XML 序列化

    Hibernate ORM 7.0 中的 XML 序列化格式更改也会有影响。虽然 Quarkus 内置的 JAXB 格式映射器使用传统格式，但删除或绕过使用 quarkus.hibernate-orm.mapping.format.global=ignore 格式的格式不兼容。

    为缓解缓解，创建一个委派到 Hibernate ORM 的映射器的映射程序。如需更多信息，请参阅 迁移指南 3.26。

    然后，执行以下操作之一：

    • 如果要依赖旧格式，请继续使用这个委派的格式映射器。
    • 准备并测试迁移脚本以更新 XML 数据。您可以使用 Hibernate ORM 的默认格式，或者根据您的需要调整 FormatMapper 实现格式化 XML。

• Hibernate ORM 7.0 迁移指南
• Hibernate ORM 7.1 迁移指南
• Hibernate ORM 7.1 用户指南
• Quarkus 迁移指南 3.24
• Quarkus 迁移指南 3.26
• 使用 Hibernate ORM 和 Jakarta Persistence 指南进行 quarkus

• API 更改

  ReactiveIdentifierGenerator API 已更新，现在扩展了 org.hibernate.generator.Generator，这需要额外的方法。

  此更改会影响定义自定义标识符生成器的用户，方法是使用 @GenericGenerator 注释和实施自己的生成器类。

  要实施新的 API，请更新使用 @GenericGenerator 定义的自定义标识符生成器。

  在 Generator 接口中，更新以下方法：

  • generatedOnExecution （） ：如果在查询执行过程中生成标识符，则返回 true，如果在应用程序代码中生成标识符，则返回 false。
  • getEventTypes （） ：指定标识符在 插入 或更新操作期间是否有 变化。

• 最小数据库版本

  quarkus-hibernate-reactive 扩展与其最低支持的数据库版本与 Hibernate ORM 7.1 dialect 要求保持一致。有关当前最小版本的更多信息，请参阅 Hibernate ORM 支持的 dialects。

• 弃用的类会被移除，以替代其推荐的替代方案。值得注意的是，org.hibernate.search.mapper.orm.masindexing.MassIndexingMonitor 被 org.hibernate.search.mapper.pojo.masindexing.MassIndexingMonitor 替代。
• MassIndexingMonitor SerialaddToTotalCount 方法已弃用，并替换为 Mas IndexingMonitor"typeGroupMonitor (..)
• projection DSL 中的 multi （） 方法已弃用，并替换为 .list （）/.set （）/sortedSet （）/collector (…​)。
• 日志记录类别已更新。特别是 org.hibernate.search.elasticsearch.request 日志记录类别，用于记录发送到 Elasticsearch 的每个请求，并已重命名为 org.hibernate.search.elasticsearch.client.request。如需更多信息，请参阅所有可用日志记录类别的列表。
• 改进了搜索 DSL 接口，使其包含额外的 SR 类型参数参考指南。
• mass 索引日志的格式已更改为以精简格式显示更多信息。
• 指标聚合 countDistinct （） 已被弃用，并替换为 count （） aggregation: . count （）.field (.).distinct （）的选项。

• Hibernate Search 8.0 迁移指南
• Hibernate Search 8.1 迁移指南
• Hibernate Search 8.1 参考指南
• Quarkus 使用 Hibernate Search with Hibernate ORM 和 Elasticsearch/OpenSearch 指南

• 删除 ZooKeeper 依赖项
• 删除了对一些较旧的协议或 API 版本的支持
• 与依赖已弃用功能的旧客户端或代理不兼容
• Quarkus 应用程序的 Java 版本 11 的最低要求
• 客户端指标的改进

• Apache Kafka 4.0 文档
• Quarkus Apache Kafka 参考指南

• 使用 OpenTelemetry 指标 指南
• Quarkus 迁移指南 3.25: OpenTelemetry 指标

• Sunsetting 传统配置类
• Quarkus 迁移指南 3.14
• 迁移到 @ConfigMapping

受影响的模块列表：

• quarkus-hibernate-orm-rest-data-panache
• quarkus-hibernate-reactive-rest-data-panache
• quarkus-mongodb-rest-data-panache
• spring-data-rest