hypersistence utils

迁移到版本 3

项目名称从 Hibernate Types 更改为 Hypersistence Utils，因为该项目的范围现在更广泛，还提供 Spring 实用程序。

因此，从 Hibernate Types 2.x 迁移到 Hypersistence Utils 3.x 时，您需要执行以下步骤：

1. 首先，您需要更改 Maven 或 Gradle 依赖项，如安装指南所示。
2. 其次，您需要将包名称从com.vladmihalcea.hibernate更改为io.hypersistence.utils.hibernate 。
3. 第三，您需要将包名称从com.vladmihalcea.spring更改为io.hypersistence.utils.spring 。

就是这样！

介绍

Hypersistence Utils 项目为您提供了适用于 Spring 和 Hibernate 的通用实用程序。

该项目的主要优点是它支持广泛的 Hibernate 版本，从 Hibernate ORM 6.6 、 6.5 、 6.4 、 6.3到6.2 、 6.1 、 6.0 、 5.6和 Hibernate 5.5 。

安装指南

根据您使用的 Hibernate 版本，您需要添加以下依赖项：

休眠 6.6、6.5、6.4 和 6.3

 <dependency>
    <groupId>io.hypersistence</groupId>
    <artifactId>hypersistence-utils-hibernate-63</artifactId>
    <version>3.9.0</version>
</dependency>

休眠 6.2

 <dependency>
    <groupId>io.hypersistence</groupId>
    <artifactId>hypersistence-utils-hibernate-62</artifactId>
    <version>3.9.0</version>
</dependency>

休眠 6.1 和 6.0

 <dependency>
    <groupId>io.hypersistence</groupId>
    <artifactId>hypersistence-utils-hibernate-60</artifactId>
    <version>3.9.0</version>
</dependency>

休眠 5.6 和 5.5

 <dependency>
    <groupId>io.hypersistence</groupId>
    <artifactId>hypersistence-utils-hibernate-55</artifactId>
    <version>3.9.0</version>
</dependency>

可选的 Maven 依赖项

Hypersistence Utils 项目定义了一系列可选依赖项，您必须在项目中显式声明这些依赖项才能使用它们。

所有这些依赖项（例如 Guava、Jackson 或 PostgreSQL JDBC Driver）都是可选的，原因是并非所有项目都需要它们。

此外，依赖版本非常重要，因为有时可能会发现安全问题，并在新版本中得到修复。

因此，依靠这个库为您提供依赖版本是一件非常危险的事情。

例如，该项目严重依赖的 Jackson Data Bind 库中发现了 65 个安全问题。

为了避免出现安全问题，您需要负责不断升级与 Hypersistence Utils 库一起使用的所有依赖项。

JSON 可选 Maven 依赖项

如果您使用 JSON 类型，那么您可能有兴趣根据您的 Hibernate 版本设置以下依赖项：

休眠6

< dependency >
    < groupId >com.fasterxml.jackson.module</ groupId >
    < artifactId >jackson-module-jakarta-xmlbind-annotations</ artifactId >
    < version >${jackson-module-jakarta-xmlbind-annotation}</ version >
</ dependency >

休眠5

< dependency >
    < groupId >com.fasterxml.jackson.core</ groupId >
    < artifactId >jackson-databind</ artifactId >
    < version >${jackson-databind.version}</ version >
</ dependency >

< dependency >
    < groupId >com.fasterxml.jackson.module</ groupId >
    < artifactId >jackson-module-jaxb-annotations</ artifactId >
    < version >${jackson-module-jaxb-annotation}</ version >
</ dependency >

Guava 可选 Maven 依赖项

如果您使用 Guava 映射Range ，则必须显式提供 Guava 依赖项：

< dependency >
    < groupId >com.google.guava</ groupId >
    < artifactId >guava</ artifactId >
    < version >${guava.version}</ version >
</ dependency >

Java 货币和货币 API 可选 Maven 依赖项

如果您要映射MonetaryAmount ，则必须显式提供 Moneta 依赖项：

< dependency >
    < groupId >org.javamoney</ groupId >
    < artifactId >moneta</ artifactId >
    < version >${moneta.version}</ version >
    < type >pom</ type >
</ dependency >

PostgreSQL 可选 Maven 依赖项

如果您要映射 PostgreSQL 特定的列类型（例如inet 、 hstore 、 array 、 interval ），那么您必须显式提供 PostgreSQL 依赖项：

< dependency >
    < groupId >org.postgresql</ groupId >
    < artifactId >postgresql</ artifactId >
    < version >${postgresql.version}</ version >
</ dependency >

特征

JSON

通用 JSON 类型

JsonType允许您映射 JSON 列类型，无论您使用的是 Oracle、SQL Server、PostgreSQL 还是 MySQL。

休眠6

如果您使用 Hibernate 6，则可以将任何 JSON 列映射到Map 、 List 、 POJO、 String或JsonNode实体属性：

 @ Type ( JsonType . class )
private Map < String , String > properties = new HashMap <>();

休眠5

如果您使用 Hibernate 5，您可以提供 Hibernate 类型的完全限定名称：

 @Type(type = "io.hypersistence.utils.hibernate.type.json.JsonType")

或者，您可以将以下映射添加到 JPA 实体所在的同一包中的package-info.java类：

 @ TypeDef (
    name = "json" , typeClass = JsonType . class
)
package io . hypersistence . optimizer ;

import io . hypersistence . utils . hibernate . type . json . JsonType ;
import org . hibernate . annotations . TypeDef ;

稍后，您可以将Map 、 List 、 POJO、 String或JsonNode实体属性映射到 JSON 列，如下所示：

 @ Type ( type = "json" )
private Map < String , String > properties = new HashMap <>();

有关更多详细信息，请查看这篇文章。

最佳实践

将 JSON 列类型映射到POJO 、 List<POJO>或Map<String, POJO>时，需要确保POJO类型覆盖默认的equals和hashCode方法并根据 JSON 对象内容实现它们。

否则，Hibernate脏检查机制可能会触发意外的UPDATE语句。查看#134 问题了解更多详细信息。

数据库特定的 JSON 类型

甲骨文

使用 Oracle 时，您有多种选择：

• 您可以使用可与JSON 、 VARCHAR或BLOB列类型一起使用的通用JsonType ，只要您使用 JPA @Column注释的columnDefinition属性提示列类型即可。
• 您可以使用JsonStringType来映射存储 JSON 的VARCHAR2列类型。
• 您可以使用JsonBlobType来映射存储 JSON BLOB列类型。

有关更多详细信息，请查看这篇文章。

SQL服务器

使用 SQL Server 时，可以使用通用JsonType或JsonStringType来映射存储 JSON 的NVARCHAR列类型。

有关更多详细信息，请查看这篇文章。

PostgreSQL

使用 PostgreSQL 时，可以使用通用JsonType或JsonBinaryType来映射jsonb和json列类型。

有关更多详细信息，请查看这篇文章。

MySQL

使用 MySQL 时，可以使用通用JsonType或JsonStringType来映射json列类型。

有关更多详细信息，请查看这篇文章。

JSON 映射示例

• 如何使用 JPA 和 Hibernate 将 POJO 映射到 JSON 列
• 如何使用 Hibernate 将字符串 JPA 属性映射到 JSON 列
• 如何将 Jackson JsonNode映射到 JSON 列
• 如何使用 JPA 和 Hibernate 映射 JSON 集合
• 如何使用 JPA 和 Hibernate 将 Java Map 实体属性映射为 JSON 列
• 如何使用 Hibernate 将 Java 记录映射到 JSON 列
• 如何使用 JPA 和 Hibernate 映射多态 JSON 对象
• 如何使用 JPA 和 Hibernate 加密和解密 JSON 属性
• 为什么应该对 JSON 属性使用 Hibernate 动态更新
• 如何使用 JPA 和 Hibernate 映射 Oracle JSON 列
• 如何使用 JPA 和 Hibernate 映射 SQL Server JSON 列
• 如何自定义 Hypersistence Utils 使用的 Jackson ObjectMapper
• 如何自定义 Hypersistence Utils 使用的 JSON 序列化器
• 如何修复将 JSON 类型与本机 SQL 查询混合时的No Dialect mapping for JDBC type: 1111问题
• 如何修复column is of type jsonb but expression is of type record或bytea类型的问题

大批

• 如何使用 JPA 和 Hibernate 将 PostgreSQL ARRAY 映射到 Java List
• 如何使用 JPA 和 Hibernate 将 PostgreSQL ARRAY 映射到 Java 数组
• 使用 JPA 和 Hibernate 进行多维数组映射
• 如何使用 JPA 和 Hibernate 映射 HSQLDB ARRAY 类型

PostgreSQL 类型（例如 ENUM、INET、HSTORE、RANGE）

• Java 枚举到 PostgreSQL 枚举类型
• 如何使用 JPA 和 Hibernate 映射 PostgreSQL Inet 类型
• 如何使用 JPA 和 Hibernate 映射 PostgreSQL HStore 实体属性
• 如何使用 Hibernate 将 PostgreSQL Enum ARRAY 映射到 JPA 实体属性
• 如何使用 JPA 和 Hibernate 映射 PostgreSQL Range 列类型
• 如何使用 Hibernate 将 PostgreSQL 间隔映射到 Java Duration

通用类型

• 使用 JPA 和 Hibernate 映射MonetaryAmount的最佳方式
• 如何将java.time.YearMonth映射到 DATE 或 INTEGER 列
• 如何使用 JPA 和 Hibernate 映射java.time.Year和java.time.Month
• Character到可为空的 CHAR 列
• 用于简化UserType实现的ImmutableType实用程序

公用事业

春天

• 很棒的 BaseJpaRepository
• 最好的 Spring Data JpaRepository
• Spring Data findAll反模式
• Spring @Retry注解在失败时自动重试

BaseJpa存储库

BaseJpaRepository是默认 Spring Data JpaRepository的更好替代品，因为它不提供在 JPA 术语中没有意义的findAll方法或save方法。

要使用BaseJpaRepository实用程序，请确保在@EnableJpaRepositories配置中提供repositoryBaseClass属性，以引用 Hypersistence Utils 项目中的BaseJpaRepositoryImpl ：

 @ Configuration
@ EnableJpaRepositories (
    value = "your.repository.package" ,
    repositoryBaseClass = BaseJpaRepositoryImpl . class
)
public class JpaConfiguration {
    ...
}

your.repository.package是 Spring 存储库的 Java 包。

Hibernate存储库

虽然BaseJpaRepository是首选，但如果您需要使用默认的JpaRepository ，那么您至少也可以扩展HibernateRepository以弃用可能导致问题的方法。

要使用HibernateRepository ，请确保在@EnableJpaRepositories配置中包含io.hypersistence.utils.spring.repository包：

 @ Configuration
@ EnableJpaRepositories (
    value = {
        "io.hypersistence.utils.spring.repository" ,
        "your.repository.package" ,
        ...
    }
)
public class JpaConfiguration {
    ...
}

your.repository.package是 Spring 存储库的 Java 包。

标识符生成器

• BatchSequenceGenerator - Hibernate 批处理序列生成器

命名策略

• CamelCaseToSnakeCaseNamingStrategy - 如何使用 Hibernate 将camelCase属性映射到snake_case列名称

DTO 投影和 ResultTransformer

• ClassImportIntegrator - 如何使用 JPA 编写紧凑的 DTO 投影查询
• ListResultTransformer - 使用 Hibernate ResultTransformer 的最佳方法
• MapResultTransformer - 如何从 JPA 或 Hibernate 查询返回 Map 结果

SQL 语句计数验证器

• SQLStatementCountValidator - 如何在测试过程中检测 Hibernate N+1 查询问题

查询实用程序

• SQLExtract - 如何从 JPQL 或 JPA Criteria 获取 SQL 查询
• QueryStackTraceLogger - 如何查找 Hibernate 生成的 SQL 查询的来源

要求

• 您正在使用的 Hibernate ORM 版本支持的 Java 版本。
• SLF4J
• 杰克逊数据绑定

错误修复和增强功能

这个项目是免费的，就像 Libre 一样，而不是免费的。

不提供免费支持。只有源代码和二进制文件是免费提供的。

如果您在特定问题上需要帮助，您需要购买 Coaching Basic 或 Coaching Pro 计划。

提供您自己的修复

除了付费支持选项之外，您还可以选择提供自己的修复。为此，您需要执行以下操作：

1. 使用现有测试用例作为模板提供复制测试用例
2. 提供修复建议
3. 发送包含修复提案和测试用例的 Pull 请求

不过，由于时间不够，我会不时审核提交的 Pull Request，因此您可能需要等待几个月的时间才能审核并集成 Pull Request。

您是否正在为应用程序性能问题而苦苦挣扎？

想象一下，有一个工具可以自动检测您是否正确使用 JPA 和 Hibernate。不再有性能问题，不再需要花费无数时间试图找出应用程序几乎无法爬行的原因。

想象一下，在开发周期的早期发现您正在使用次优的映射和实体关系，或者您缺少与性能相关的设置。

此外，借助 Hypersistence Optimizer，您可以在测试期间检测所有此类问题，并确保不会将影响数据访问层性能的更改部署到生产环境。

Hypersistence Optimizer 是您期待已久的工具！

训练

如果您对现场培训感兴趣，我可以为您提供高性能 Java 持久性培训，该培训可以调整为一天、两天或三天的课程。欲了解更多详情，请查看我的网站。

咨询

如果您希望我审查您的应用程序并深入了解如何优化它以使其运行得更快，请查看我的咨询页面。

高性能 Java 持久性视频课程

如果您想以最快的方式学习如何加速 Java 数据库应用程序，那么您绝对应该参加我的高性能 Java 持久性视频课程。

高性能Java持久化书籍

或者，如果您更喜欢阅读书籍，您也会喜欢我的《高性能 Java 持久性》一书。

贡献指南

该项目使用 Maven 工具链，因为不同的模块使用不同的 Java 版本进行编译和测试。

Hypersistence Utils 6 需要 Java 11，而其他模块则使用 Java 8 编译。

要了解如何配置 Maven 工具链，请查看这篇文章。

该项目使用各种数据库系统进行集成测试，您可以使用DatasourceProvider实例（例如PostgreSQLDataSourceProvider ）配置 JDBC 连接设置，并且该项目使用 Testcontainers 来引导具有所需 Oracle、SQL Server、PostgreSQL 或 MySQL 的 Docker 容器按需实例。

如果您是定期贡献者，建议在本地设置所需的数据库或使用docker文件夹中提供的 Docker Compose 配置，因为按需引导容器速度较慢，并且您的测试将需要更长的时间来运行。

如果您想解决问题或添加对新功能的支持，请提供相关的集成测试用例，以证明改进按预期工作。