Hibernate ORM 中文操作指南

实体必须：

另一方面，实体类可以是具体类或 abstract，并且可以拥有任意数量的其他构造函数。

每个实体类都必须注释 @Entity。

或者，可以通过为类提供基于 XML 的映射来将类标识为实体类型。

我们不会在这篇简介中对基于 XML 的映射做更多的说明，因为这并不是我们首选的方式。

每个实体类都有一个默认 access type，即：

Hibernate 根据属性级注解的位置自动确定访问类型。具体而言：

在 Hibernate 还只是个婴儿的时候，属性访问在 Hibernate 社区非常流行。然而，如今，字段访问 much 更常见。

如果 @Id 注释字段，其他映射注释也应该应用于字段，或

如果 @Id 注释 getter，其他映射注释应该应用于 getter。

原则上，可以使用显式 @Access 标注在属性级别混合字段和属性访问。我们不建议这样做。

像 Book 这样的实体类（它不扩展任何其他实体类）被称为 root entity。每个根实体都必须声明一个标识符属性。

一个实体类可以 extend 另一个实体类。

子类实体继承其扩展的每个实体的每个持续性属性。

根实体还可以扩展另一个类并从其他类继承映射的属性。但在这种情况下，声明映射的属性的类必须使用 @MappedSuperclass 注释。

根实体类必须声明一个带 @Id 注释的属性，或者从 @MappedSuperclass 中继承一个属性。子类实体总是继承根实体的标识符属性。它可能不会声明其自己的 @Id 属性。

标识符属性通常是字段：

但它可能是一个属性：

标识符属性必须带 @Id 或 @EmbeddedId 注释。

标识符值可能为：

我们将首先讨论第二个选项。

标识符通常是系统生成的，在这种情况下，应该带 @GeneratedValue 注释：

JPA 根据 GenerationType 中的定义为生成 ID 提供了以下策略：

表 12. 标准 id 生成策略

例如，此 UUID 是在 Java 代码中生成的：

此 id 映射到 SQL identity、auto_increment 或 bigserial 列：

@SequenceGenerator 和 @TableGenerator 注释分别允许进一步控制 SEQUENCE 和 TABLE 生成。

考虑此序列生成器：

值是使用如下定义的数据库序列生成的：

请注意，每次需要新标识符时，Hibernate 无需都转到数据库。相反，给定的进程会获取一个大小为 allocationSize 的 id 块，并且仅在块用尽时才需要访问数据库。当然，缺点是生成的标识符不连续。

任何标识符属性现在都可以使用 bookSeq 中指定的生成器：

实际上，将 @SequenceGenerator 注释放到使用它的 @Id 属性上非常常见：

正如您所见，JPA 为系统生成 ID 的最常见策略提供了非常充足的支持。但注释本身比它们应有的更具入侵性，并且没有明确定义的方法来扩展此框架以支持用于生成 ID 的自定义策略。在未注释为 @Id 的属性上也不能使用 @GeneratedValue。由于自定义 ID 生成是相当普遍的要求，Hibernate 提供了一个非常精细设计的框架，用于用户定义的 _ 生成器_，我们将在 User-defined generators 中予以讨论。

并非每个标识符属性都映射到（系统生成的）代理键。对系统用户来说有意义的主键被称为 natural keys。

当表的主键是自然键时，我们不会使用 @GeneratedValue 注释标识符属性，并且由应用程序代码负责为标识符属性分配一个值。

特别令人感兴趣的是由多个数据库列组成的自然键，并且此类自然键称为 composite keys。

如果你的数据库使用复合键，则需要多个标识符属性。有两种方法可以在 JPA 中映射复合键：

将这段文字用 Gemini 翻译成中文可能最直接的自然方式是在实体类中用多个 @Id 注释的字段表示，例如：

但这种方法有一个问题：我们可以使用什么对象标识一个 Book，并将其传递给接受标识符的 find() 等方法？

解决方案是编写一个单独的类，其字段与实体的标识符属性相匹配。每个此类 ID 类必须覆盖 equals() 和 hashCode()。当然，满足这些要求最简单的方法是将 ID 类声明为 record。

Book 实体的 @IdClass 注释将 BookId 标识为用于该实体的 ID 类。

这不是我们推荐的方法。相反，我们建议将 BookId 类声明为 @Embeddable 类型：

我们将在下面详细了解有关 Embeddable objects 的情况。

现在，实体类可以使用 @EmbeddedId 重用此定义，并且 @IdClass 注释不再是必需的：

第二种方法消除了部分重复代码。

无论哪种方式，我们现在都可以使用 BookId 来获取 Book 的实例：

实体可能具有由 Hibernate 用于乐观锁检查的属性。版本属性通常为 Integer、Short、Long、LocalDateTime、OffsetDateTime、ZonedDateTime 或 Instant 类型。

当实体持久化时，版本属性会由 Hibernate 自动分配，并在每次更新实体时自动递增或更新。

我们已经见过的 @Id 和 @Version 属性只是 basic attributes 的专门示例。

即使实体具有替代键，也应该始终能够写下唯一标识实体实例的字段组合，从系统用户的角度来看。字段组合就是自然键。在上面，我们 considered 讨论了自然键与主键重叠的情况。此处，自然键是实体的第二个唯一键，与其替代主键不同。

由于基于自然键检索实体是 extremely 常见的做法，因此 Hibernate 有一种方法可以标记组成自然键的实体的属性。每个属性都必须使用 @NaturalId 进行标注。

Hibernate 会为由注释字段映射的列自动生成一个 UNIQUE 约束。

正如我们将在 much later 中看到，完成这项额外工作的好处在于，我们可以利用优化的自然 ID 查找，充分利用二级缓存。

请注意，即使您已标识出自然键，我们仍建议在外部键中使用生成的代理键，因为这可以使您的数据模型 much 更易于更改。

实体的 basic 属性是映射到关联数据库表单个列的字段或属性。JPA 规范定义了一组非常有限的基本类型：

表 13. JPA 标准基本属性类型

Hibernate 通过以下类型略微扩展了此列表：

表 14. Hibernate 中的其他基本属性类型

@Basic 注释明确指明一个属性是基本属性，但通常不需要它，因为属性默认为基本属性。另一方面，如果一个非基本类型属性不能为 null，则强烈建议使用 @Basic(optional=false)。

请注意，基本类型属性默认情况下是 NOT NULL 推断得到的。

我们包括 Java enum_s on the list above. An enumerated type is considered a sort of basic type, but since most databases don’t have a native _ENUM 类型，JPA 提供了特殊 @Enumerated 注解，用于指定枚举值在数据库中应如何表示：

在 Hibernate 6 中，带 enum 注解的 @Enumerated(STRING) 映射到：

任何其他 enum 都映射到带 CHECK 约束的 TINYINT 列。

即使考虑到 DayOfWeek ，编码为整数也是模棱两可的。如果你查看 java.time.DayOfWeek ，你会发现 SUNDAY 编码为 6 。但在我的出生地， SUNDAY 是星期 first ！

因此，我们更喜欢 @Enumerated(STRING) 作为大多数 enum 属性。

PostgreSQL 是一个有趣的特殊情况。Postgres 支持 named ENUM 类型，必须使用 DDL CREATE TYPE 语句声明。遗憾的是，这些 ENUM 类型与语言集成不佳，也不受 Postgres JDBC 驱动程序的充分支持，因此 Hibernate 默认不使用它们。但是，如果您想在 Postgres 上使用命名枚举类型，只需像这样注释您的 enum 属性：

可以通过提供 converter 来略微扩展有限的预定义基本属性类型的集合。

JPA AttributeConverter 负责：

转换器大幅扩展了 JPA 可以处理的属性类型集合。

有两种应用转换器的方法：

例如，以下转换器将自动应用于类型为 BitSet 的任何属性，并负责将 BitSet 持续存储到类型为 varbinary 的列：

另一方面，如果我们 don’t 设置 autoapply=true，则我们必须通过使用 @Convert 注解显式应用转换器：

所有这些都很不错，但这可能不会让你惊讶，因为 Hibernate 超越了 JPA 所需的内容。

Hibernate 将“基本类型”视为由两个对象组成的婚姻结合：

映射基本属性时，我们可能明确指定 JavaType、JdbcType，或同时指定两者。

可嵌入对象是一种 Java 类，其状态映射到表的多个列，但没有它自己的持久性标识。也就是说，它是一个具有映射属性的类，但没有 @Id 属性。

可嵌入对象只能通过分配给实体的属性才能变得持久。由于可嵌入对象没有它自己的持久性标识，因此它在持久性方面的生命周期完全由它所属的实体的生命周期决定。

可嵌入类必须使用 @Embeddable 注释而不是 @Entity。

可嵌入类必须满足实体类满足的相同要求，但可嵌入类没有 @Id 属性除外。特别是，它必须有一个没有参数的构造函数。

或者，可将可嵌入式类型定义为 Java 记录类型：

在这种情况下，对没有参数的构造函数的需求会得到放宽。

我们现在可以将我们的 Name 类（或记录）用作实体属性的类型：

可嵌入式类型可以是嵌套的。也就是说，@Embeddable 类可能有一个属性，其类型本身是另一个不同的 @Embeddable 类。

另一方面，对可嵌入类型的引用是 never 多态的。一个 @Embeddable 类 F 可能继承第二个 @Embeddable 类 E，但类型为 E 的属性将始终引用该具体类 E 的实例，而永远不会引用 F 的实例。

通常，可嵌入类型将存储为“扁平化”格式。它们的属性会映射到其所属实体表的列。稍后在 Mapping embeddable types to UDTs or to JSON 中，我们将看到几种不同的选项。

可嵌入式类型的属性表示具有持久性标识的 Java 对象与不具有持久性标识的 Java 对象之间的关系。我们可以将其视为整体/部分关系。可嵌入式对象属于实体，不能与其他实体实例共享。而且，它仅在父实体存在的期间内存在。

接下来，我们将讨论另一种关系：具有各自不同的持久性标识和持久性生命周期的 Java 对象之间的关系。

association 是实体之间的关系。我们通常根据关联的 multiplicity 对关联进行分类。如果 E 和 F 都是实体类，则：

实体类之间的关联可以是：

在这个示例数据模型中，我们可以看到可能的关联类型：

用于映射关联的注释有三个：@ManyToOne、@OneToMany 和 @ManyToMany。它们共享一些通用的注释成员：

表 15. 定义关联的注解成员

当我们考虑各种类型的关联映射时，我们将解释这些成员的作用。

让我们从最常见的关联多重性开始。

多对一关联是我们能想象到的最基本的关联类型。它完全自然地映射到数据库中的外键。域模型中的几乎所有关联都将采用这种形式。

@ManyToOne 注释标记关联的“到一”端，因此单向多对一关联如下所示：

在这里，Book 表有一个外键列，其中保存着关联的 Publisher 的标识符。

大多数情况下，我们希望能够轻松地在两个方向上导航我们的关联。我们确实需要一种方法来获取给定 Book 的 Publisher，但我们也希望能够获取属于给定发布者的所有 Book。

为了使此关联变为双向，我们需要向 Publisher 类中添加集合值属性并对其进行 @OneToMany 注释。

为了明确表示这是一个双向关联，并重用已在 Book 实体中指定的任何映射信息，我们必须使用 mappedBy 注释成员引用 Book.publisher。

Publisher.books 字段称为关联的 unowned 端。

现在，我们热情地 hate 将强类型 mappedBy 引用推荐给关联的所有方。幸运的是， Metamodel Generator 为我们提供了一种使其更具类型安全的方法：

我们将在介绍的剩余部分中使用这种方法。

如果要修改双向关联，我们必须更改 owning side。

事实上，经常需要更改双向关联的 both sides 。例如，如果将集合 Publisher.books 存储在二级缓存中，我们还必须修改该集合，以确保二级缓存与数据库保持同步。

也就是说，更新非自有端是 not 一项艰巨的要求，至少如果您确定知道自己在做什么的话。

这里我们使用 Set 作为集合的类型，但 Hibernate 也允许在此处使用 List 或 Collection，语义几乎没有差别。特别是，List 可能不包含重复元素，其顺序不会持久化。

我们将在 much later 中看到如何映射具有持久顺序的集合。

最简单的单一对一关联几乎与 @ManyToOne 关联完全相同，不同之处在于它映射到带有 UNIQUE 约束的外键列。

一对一关联必须注释 @OneToOne：

在这里，Author 表有一个外键列，其中包含关联的 Person 的标识符。

我们可以通过在 Person 实体中添加对 Author 的引用，使此关联变为双向：

Person.author 是非拥有端，因为它标有 mappedBy 的一侧。

这并不是一对一关联的唯一类型。

一种更优雅的方式来表示这种关系是这两个表之间共享一个主键。

要使用这种方法，必须像这样对 Author 类进行注释：

请注意，与之前的映射相比：

这可让 Hibernate 了解到与 Person 的关联是 Author 主键值的来源。

此处，Author 表中没有额外的外键列，因为 id 列包含 Person 的标识符。也就是说，Author 表的主键充当了指代 Person 表的外键的双重职责。

Person 类并不改变。如果关联是双向的，我们会像以前一样对非拥有端 @OneToOne(mappedBy = Author.PERSON)_ 进行注释。

单向多对多关联表示为集合值属性。它总是映射到数据库中的单独 association table。

通常情况下，多对多关联最终会变成伪装的实体。

例如，假设我们需要报告每位作者在书中所占的百分比贡献。该信息自然属于关联表。我们无法轻松地将它存储为 Book 的属性，也无法将其存储为 Author 的属性。

当这种情况发生时，我们需要更改 Java 模型，通常需引入一个新的实体类来直接映射关联表。在我们示例中，我们可以将此实体命名为 BookAuthorship ，它将包含与 Author 和 Book 的 @OneToMany 关联，以及 contribution 属性。

我们可以通过从一开始就避免使用 @ManyToMany 来躲避此类“发现”所造成的干扰。使用中间实体表示每个（或至少是 almost ）逻辑多对多关联几乎没有缺点。

多对多关联必须注释 @ManyToMany：

如果关联是双向的，我们向 Book 添加一个非常相似的属性，但这次我们必须指定 mappedBy 以指示这是关联的非拥有端：

请记住，如果我们希望修改集合，我们必须 change the owning side。

我们再次使用了 Set_s to represent the association. As before, we have the option to use _Collection 或 List。但在这种情况下，它 does 会影响关联的语义。

我们现在看到了以下类型的实体属性：

扫描此分类法，你可能会问：Hibernate 是否具有基本或可嵌入类型的多值属性？

好，实际上我们已经看到了它确实如此，至少在两种特殊情况下。因此，首先，让我们 recall JPA 将 byte[] 和 char[] 数组视为基本类型。Hibernate 会将 byte[] 或 char[] 数组持久保存到 VARBINARY 或 VARCHAR 列（分别）。

但在本节中，我们真正关注的是比这两个特例 other 的情况。那么， apart from _byte[] 和 char[]_ ，Hibernate 是否具有基本类型或可嵌入类型多值属性？

答案仍然是 it does。事实上，有两种不同的方法来处理这样的集合，即通过映射它：

因此，我们可以通过以下方式扩展我们的分类法：

实际上，这里有两种新的映射类型：@Array 映射和 @ElementCollection 映射。

在某些情况下，我们认为在我们的实体类中使用基本类型值的集合是合适的。但这种情况很少见。几乎所有多值关系都应映射到独立表之间的外键关联。几乎每个表都应通过实体类映射。

我们在接下来两个子部分中将要了解的功能，初学者使用得比专家多。因此，如果您是初学者，现阶段远离这些功能将节省您相同的麻烦。

我们先来讨论一下 @Array 映射。

让我们考虑在每周某些日期重复的日历事件。我们可能在_Event_ 实体中将其表示为类型为_DayOfWeek[]_ 或_List<DayOfWeek>_ 的属性。由于此数组或列表的元素数上限为 7，因此这是一个使用_ARRAY_ 类型列的合理案例。将此集合存储在单独的表中似乎没什么价值。

不幸的是，JPA 没有定义将 SQL 数组映射到标准方法，但以下是如何在 Hibernate 中进行映射：

@Array 注释是可选的，但限制数据库分配给_ARRAY_ 列的存储空间数量非常重要。通过在此处编写_@Array(length=7)，我们指定 DDL 应该使用列类型_TINYINT ARRAY[7] 生成。

仅出于好玩，我们在上面的代码中使用了一个枚举类型，但是数组元素时间可能是几乎任何 basic type。例如，Java 数组类型 String[]、UUID[]、double[]、BigDecimal[]、LocalDate[] 和 OffsetDateTime[] 通通允许，分别映射到 SQL 类型 VARCHAR(n) ARRAY、UUID ARRAY、FLOAT(53) ARRAY、NUMERIC(p,s) ARRAY、DATE ARRAY 和 TIMESTAMP(p) WITH TIME ZONE ARRAY。

具体来讲，DB2 和 SQL Server 都没有数组类型列。在此类数据库中，Hibernate 会退而使用更糟糕的方法：它使用 Java 序列化将数组编码成二进制表示形式，并将二进制流存储在 VARBINARY 列中。很明显，这样做很糟糕。您可以要求 Hibernate 通过注释属性 @JdbcTypeCode(SqlTypes.JSON) 来做些 slightly 不那么糟糕的事情，以便将数组序列化为 JSON 而不是二进制格式。但在此时，最好直接承认失败，转而使用 @ElementCollection 。

或者，我们可以将该数组或列表存储在单独的表中。

JPA does 定义了将集合映射到辅助表的标准方法：@ElementCollection 注释。

实际上，我们不应该在此处使用数组，因为数组类型无法 proxied，因此 JPA 规范甚至没有说它们受支持。相反，我们应该使用 Set、List 或 Map。

在其中，每个集合元素作为辅助表的单独行存储。默认情况下，此表具有以下定义：

这是合适的，但它仍然是我们希望避免的映射。

上面的代码将生成一个包含三列的表：

a foreign key of the Event table,

a TINYINT encoding the enum, and

an INTEGER encoding the ordering of elements in the array.

它没有替代主键，而是一个复合键，其中包含 Event 的外键和顺序列。

当我们（不可避免地）发现需要向该表添加第四列时，我们的 Java 代码必须完全更改。很可能，我们最终会意识到需要添加一个单独的实体。所以，在我们的数据模型发生小更改的情况下，这种映射并不十分稳健。

我们可以就“元素集合”的多得多进行讨论，但我们不会这么做，因为我们不想让你拿起枪对自己开枪。

让我们停下来，回想起我们到目前为止了解过的注释。

表 16. 声明实体和可嵌入类型

表 17. 声明基本和嵌入式属性

表 18. 转换器和复合基本类型

表 19. 系统生成的标识符

表 20. 声明实体关联

呼！这已经是许多注释了，我们甚至没有开始 O/R 映射的注释！

实体类应覆盖 equals() 和 hashCode()，尤其是在关联 represented as sets 时。

初次使用 Hibernate 或 JPA 的人经常会困惑究竟应将哪些字段包含在 hashCode() 中。以及有更多经验的人经常会十分虔诚地认为一个或另一个方法是唯一正确的途径。事实上，没有一种正确的方法，但存在一些约束。因此，请牢记以下原则：

将任何不可变的非生成字段包含在哈希中是没有问题的。

也就是说，基于实体的生成标识符实现 equals() 和 hashCode() 也可用作 if you’re careful。