Skip to content

11. Hibernate

上一章演示了 Kotlin 应用程序如何通过 JDBC 驱动程序与数据库交互:打开连接,执行 SQL 命令,逐列读取结果行,并把它们复制到对象中。这种复制过程——从行到对象,以及从对象到 [INSERT]、[UPDATE] 和 [DELETE] 命令——是重复性的。可以借助一种工具将其自动化:“对象关系映射器”(ORM)。本章介绍 Java 世界中使用最广泛的 ORM,即 Hibernate,以及它所实现的标准 Jakarta Persistence。Kotlin 没有同等分量的自有 ORM:它直接使用 Java 平台的 ORM——首推 Hibernate——就像使用其他 Java 库一样。你只需了解几条规则,就能编写出可与 Hibernate 配合使用的 Kotlin 实体:本章会随着内容的推进逐一介绍它们。

本章重新审视第 10 章中商品的示例代码,并以税款计算应用程序的第 7 版收尾,该版本的 [dao] 层使用 Hibernate。

11.1. 什么是 ORM?

11.1.1. 对象与表

Kotlin 应用程序处理的是 对象:商品有名称、价格和库存量;订单有客户和订单行列表,每个订单行都引用一个商品。关系数据库则把同样的 信息存放在 表中:每个商品在 [articles] 表中占一行,每个订单在 [orders] 表中占一行,行与行之间的关系由外键表示。这两个世界并不完全吻合:

  • 对象直接引用其他对象([order.client]);而一行则包含另一行的主键值([client_id]);
  • 对象可以包含集合([order.lines]);而表只包含单个值;集合由另一张表中指向该订单的行来表示;
  • Kotlin 类型([String]、[BigDecimal]、[LocalDate]、[Boolean])与 SQL 类型([varchar(30)]、[decimal(10,2)]、[date]、[bit])并不相同;
  • 对象用 Kotlin 查询(集合上的 [filter]、[map]……操作),而表用 SQL 查询。

ORM 在这两个世界之间架起桥梁。我们一劳永逸地定义类与表之间的对应关系(模型,即“映射”);之后由它负责:

  • 把用面向对象语言(HQL)编写或通过代码(Criteria API)构造的查询转换为 SQL 和 [SELECT] 命令;
  • 根据读取的行创建对象(这称为 实例化);
  • 存储已读取的对象,并检测其中被修改、添加或删除的对象;
  • 生成把这些更改反映到数据库中的 [INSERT]、[UPDATE]、和 [DELETE] 命令;
  • 必要时,还可以根据类创建和更新数据库模式(表、列、索引)。

使用 Hibernate 和 MySQL 的应用程序的架构如下:

Image

  • [1]:应用程序。其 [dao] 层不再直接与 JDBC 驱动程序通信,而是通过 [Session] 对象和 HQL 查询与 Hibernate 通信;
  • [2]:Hibernate,独立于 DBMS:模型、查询转换、变更跟踪、模式生成;
  • [3]:特定于 DBMS 的 方言 (此处为 [MySQLDialect]):它了解该 DBMS 的 SQL 语法、列类型和函数。主要 DBMS 的方言是 Hibernate 本身的一部分:无需向项目添加任何东西;
  • [4]:DBMS 的 JDBC 驱动程序,即第 10 章讨论的那个(MySQL Connector/J):Hibernate 并不取代 JDBC,而是使用它;
  • [5]:DBMS。

无论应用程序是用 Java 还是 Kotlin 编写的,这一模式都不会改变:Hibernate 是一个 Java 库,Kotlin 代码像调用其他 Java 库一样调用它(第 5 章),而对 Hibernate 来说,编译后的 Kotlin 类与其他任何 Java 类并无二致。

11.1.2. Jakarta Persistence 与 Hibernate

Hibernate 由 Gavin King 于 2001 年创建,以应对当时 Java EE 平台中“实体 Bean”的繁琐。它大获成功,以至于它的思想被纳入一项标准,即 JPA (Java Persistence API),于 2006 年随 Java EE 5 发布。当 Java EE 被移交给 Eclipse 基金会并更名为 Jakarta EE 时,JPA 变成了 Jakarta Persistence,其包名从 [javax.persistence] 变为 [jakarta.persistence] (3.0 版,2020 年)。当前版本是 Jakarta Persistence 3.2 (2024 年)。

Jakarta Persistence 是一个 规范:包含一组接口([EntityManagerFactory]、[EntityManager]……)、注解([@Entity]、[@Id]、[@Column]……)以及一种查询语言 JPQL。它由多个产品实现:Hibernate ORM (使用最广泛,用于 Spring Boot 和 Quarkus)、EclipseLink (参考实现)……本课程使用 Hibernate ORM 7.4.5,它实现了 Jakarta Persistence 3.2。

Hibernate 提供两种使用方式:

  • 只通过标准接口:这种情况下,代码仅依赖 [jakarta.persistence],原则上可以切换实现;
  • 通过它自己的(“原生”)API,该 API 功能更丰富,其接口 扩展了 标准接口:[SessionFactory] 就是一个 [EntityManagerFactory],而 [Session] 就是一个 [EntityManager]。

我们使用 Hibernate 自己的 API,这也是其文档的推荐做法:它提供了所有标准方法([persist]、[find]、[merge]、[remove]……)以及 Hibernate 的扩展。不过,注解始终是标准所定义的那些。下表列出了对应关系:

Jakarta Persistence
Hibernate
作用
[EntityManagerFactory]
[SessionFactory]
针对某个数据库的 Hibernate 配置:一个重量级对象,只创建一次,由整个应用程序共享
[EntityManager]
[Session]
数据库会话:一个轻量级的、生命周期短暂的对象
[EntityTransaction]
[Transaction]
事务
JPQL
HQL
查询语言;HQL 是 JPQL 的超集
[CriteriaBuilder]
[HibernateCriteriaBuilder]
通过代码构造查询

在 Kotlin 生态系统中,你还会遇到性质不同的数据访问库,例如 Exposed (来自 JetBrains),它允许你用专用的 Kotlin 语言编写 SQL 查询。这些库比完整的 ORM 更轻量;Hibernate 仍然是 Spring 应用程序(无论是 Java 还是 Kotlin)的标准,也是我们所要学习的。

11.1.3. 库

本章使用的库如下(它们在关于依赖的附录中有汇总):

Gradle 依赖
作用
[org.hibernate.orm:hibernate-core] 7.4.5.Final
Hibernate 本身;它包含 Jakarta Persistence 3.2 的 API([jakarta.persistence-api])及其自身的依赖项(用于生成类的 Byte Buddy、用于查询分析的 ANTLR、用于日志的 JBoss Logging 等)
[com.mysql:mysql-connector-j] 9.7.0
MySQL 的 JDBC 驱动程序,即第 10 章中的那个
[ch.qos.logback:logback-classic] 1.5.38
Logback,它将接收 Hibernate 的日志

Hibernate 通过 JBoss Logging 写日志(执行的 SQL 命令、警告等),这是一个小型库,它只是把消息转发给在类路径中找到的日志系统:Log4j 2,或 Logback(通过 SLF4J),或者在都没有的情况下,转发给 JDK 自带的日志系统 [java.util.logging]。在没有配置的情况下,后者会把每条消息显示为两行,在大多数控制台中是红色的,这使得程序输出难以阅读。因此,我们在项目中添加 Logback,并通过 [logback.xml] 文件对其进行配置。

除了这些库之外,还有两个 Kotlin 编译器插件 ,用于使 Kotlin 类适应 Hibernate 的要求:[kotlin("plugin.jpa")] 和 [kotlin("plugin.allopen")]。我们在查看第一个实体时会明白为什么需要它们。

11.1.4. 代码优先或数据库优先

模型(类与表之间的映射)可以通过两种方式构建:

  • 代码优先:你编写 Kotlin 类,Hibernate 据此推断出数据库模式,然后可以自行创建它。本章采用这种方式;
  • 数据库优先:数据库已经存在,通过 Hibernate 的逆向工程工具(Hibernate Tools)或开发环境提供的工具(IntelliJ IDEA 可以根据数据库表生成 Java 和 Kotlin 实体),从其模式生成类。这是需要使用现有数据库的应用程序所采用的方式。生成的代码与我们手工编写的代码相似。

11.2. 第一个示例

11.2.1. 项目

本章的示例是一个多项目 Gradle 构建的子项目(参见第 6 章),位于 [11-hibernate] 文件夹中:

11-hibernate/
  settings.gradle.kts     the list of the subprojects
  build.gradle.kts        the root project: the plugins and their versions
  gradlew, gradlew.bat    the Gradle wrapper
  tools/                  library: the compact SQL log
  articles/               library: the Article entity and the [hbarticles] database
  first/                  a first example
  model/                  the model: annotations, XML file, creation script
  crud/                   persist, find, merge, remove
  hql/                    HQL queries
  criteria/               Criteria API queries
  relations/              relationships between entities
  clients/                the evolution of the database schema
  async/                  Hibernate, virtual threads and coroutines
  transactions/           transactions
  concurrency/            optimistic concurrency
  rawsql/                 native SQL
  bulkupdate/             bulk updates
  injection/              Hibernate and Spring
  TaxV7/                  the tax calculation application, version 7

文件 [settings.gradle.kts] 声明了各个子项目:

// 第 11 章:Hibernate

// 如果机器上找不到 jvmToolchain(25) 所要求的 JDK,Gradle 会自行下载
plugins {
    id("org.gradle.toolchains.foojay-resolver-convention") version "1.0.0"
}

rootProject.name = "hibernate"

// 本章示例共用的两个库
include("tools", "articles")
// 示例
include("first", "model", "crud", "hql", "criteria", "relations", "clients",
    "async", "transactions", "concurrency", "rawsql", "bulkupdate", "injection")
// [Tax] 应用程序第 7 版:用 Hibernate 编写的 [dao] 层
include("TaxV7:tax-dao-hibernate", "TaxV7:tax-ui-hibernate")

// 重用第 5 版(第 6 章)的 [business] 层和 [ui] 层:复合构建
includeBuild("../06-architectures")
  • 第 3–6 行:该插件允许 Gradle 在机器上找不到 JDK 25 时自行下载它(第 2 章);
  • 第 8 行:根项目的名称;
  • 第 11 行:各示例共用的两个库;
  • 第 13–14 行:一个子项目,仅作示例。Gradle 不要求按依赖顺序列出各子项目;它会根据子项目之间声明的依赖自行推断;
  • 第 16 行:税款计算应用程序第 7 版的两个子项目。名称 [TaxV7:tax-dao-hibernate] 指的是文件夹 [TaxV7/tax-dao-hibernate];
  • 第 19 行:第 6 章的复合结构,应用程序 TaxV7 将重用其中的 [business] 层和 [ui] 层。

根项目连同版本一起声明了各子项目所用的插件:

1
2
3
4
5
6
7
// 第 11 章:根项目。插件在此声明(带版本),由子项目应用
plugins {
    kotlin("jvm") version "2.4.20" apply false
    kotlin("plugin.jpa") version "2.4.20" apply false
    kotlin("plugin.allopen") version "2.4.20" apply false
    kotlin("plugin.spring") version "2.4.20" apply false
}
  • 第 3 行:用于 JVM 的 Kotlin 插件;
  • 第 4–5 行:实体所需的两个 Kotlin 编译器插件(稍后介绍);
  • 第 6 行:为 Spring 配置的“all-open”插件(第 6 章),由 [injection] 示例使用;
  • [apply false]:插件在这里只是连同版本一起声明;每个子项目应用自己需要的插件,而无需重复写版本。

第一个示例是子项目 [first]。它独立于其他子项目:

// 第一个示例:一个实体、一个数据库、Hibernate 生成的几条 SQL 语句
plugins {
    kotlin("jvm")
    // 实体的无参构造函数(为 JPA 配置的 "no-arg" 插件)
    kotlin("plugin.jpa")
    // 实体和属性被设为 open(非 final):Hibernate 可以从中派生代理
    kotlin("plugin.allopen")
    application
}

repositories {
    mavenCentral()
}

dependencies {
    // Hibernate 和 MySQL JDBC 驱动
    implementation("org.hibernate.orm:hibernate-core:7.4.5.Final")
    runtimeOnly("com.mysql:mysql-connector-j:9.7.0")
    // Logback:它接收 Hibernate 日志(仅在运行时)
    runtimeOnly("ch.qos.logback:logback-classic:1.5.38")
}

// 以这种方式标注的类由 [allopen] 插件打开
allOpen {
    annotation("jakarta.persistence.Entity")
    annotation("jakarta.persistence.MappedSuperclass")
    annotation("jakarta.persistence.Embeddable")
}

kotlin {
    jvmToolchain(25)
    compilerOptions {
        allWarningsAsErrors = true
        javaParameters = true
    }
}

application {
    // 由 [gradlew -q :first:run] 运行的程序,在 11-hibernate 文件夹中启动
    mainClass = "first.MainKt"
}

// 在 Windows 上,由 Gradle(run、bootRun 等)启动的程序的屏幕输出以 UTF-8 编码,
// 否则带重音符号的字符在 IntelliJ IDEA 控制台或终端中会出现乱码
tasks.withType<JavaExec>().configureEach {
    jvmArgs("-Dstdout.encoding=UTF-8", "-Dstderr.encoding=UTF-8")
}
  • 第 3–8 行:应用的插件:Kotlin、两个实体插件,以及用于运行程序的 [application] ;
  • 第 17–20 行:Hibernate、MySQL 的 JDBC 驱动程序和 Logback。驱动程序和 Logback 只在运行时使用([runtimeOnly]):程序代码不引用它们的任何类;
  • 第 24–27 行:[allopen] 插件的配置(下文介绍);
  • 第 31–34 行:本课程的标准编译选项(JDK 25,警告视为错误);
  • 第 40 行:子项目的主类。[first] 包中的 [Main.kt] 文件会被编译为 [first.MainKt] 类(第 3 章);
  • 第 43–46 行:由 Gradle 启动的程序以 UTF-8 编码输出,以便带重音符号的字符在 Windows 上能正确显示(第 2 章)。

要运行某个示例,请进入 [11-hibernate] 文件夹,并通过路径([run] 指定子项目的任务 [:first:run]);Gradle 会先构建它所依赖的子项目(在 Linux 和 macOS 上,输入 [./gradlew]):

> cd 11-hibernate
> gradlew -q :first:run

程序在子项目文件夹([11-hibernate/first])中执行。所使用的数据库是本地 MySQL 服务器上的 [hbfirst] 数据库,该服务器即 Laragon 服务器(参见附录)。该数据库不需要预先存在:MySQL 会创建它。

11.2.2. 实体 [Article]

对象存储在表中的类称为 实体。我们的第一个实体是商店中的商品,对应第 10 章中的表 [articles] :

package first

import jakarta.persistence.Entity
import jakarta.persistence.GeneratedValue
import jakarta.persistence.GenerationType
import jakarta.persistence.Id
import java.math.BigDecimal

// 商店的一件商品:一个普通的 Kotlin 类,外加几个注解
@Entity
class Article(
    // 表的列,声明为主构造函数的属性
    var name: String,
    var price: BigDecimal,
    var currentStock: Int,
    var minimumStock: Int,
) {
    // 由 DBMS 生成的主键:在商品被保存之前为 null
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    var id: Int? = null

    // 显示
    override fun toString() = "[%d, %s, %.2f, %d, %d]".format(id, name, price, currentStock, minimumStock)
}
  • 第 10 行:注解 [@Entity] (位于包 [jakarta.persistence] 中)使该类成为实体。这是一个普通的 Kotlin 类,不继承任何 Hibernate 类;它被称为 POJO (“Plain Old Java Object”,简单老式 Java 对象);
  • 第 13–16 行:在主构造函数中声明的属性(第 4 章)。它们是 [var]:Hibernate 必须能够修改它们的值,应用程序也必须能够修改(以更改价格或库存量)。每个属性成为一个同名的列;
  • 第 19–21 行:主键由 [@Id] 注解指定。这里没有命名约定:必须有该注解。[@GeneratedValue(strategy = GenerationType.IDENTITY)] 表示其值将由 DBMS 生成(MySQL 的 [AUTO_INCREMENT] 列)。标识符不是构造函数的参数:它将由 DBMS 提供。它的类型是 [Int?],初始值是 [null],表示“尚未记录到数据库中”。类型 [Int?] 被编译为 [java.lang.Integer],而类型 [Int] 被编译为 [int] (第 3 章);
  • 第 24 行:便于查看的商品显示格式。格式 [%.2f] 按照通行的文化习惯显示带两位小数的价格(法国用逗号,而结果中使用的英文区域设置用句点)。

注解放在哪里?在字节码中,一个 Kotlin 属性对应多个 Java 元素:一个私有字段、一个访问器([getX])、一个修改器([setX]),以及在本例中还有一个构造函数参数。放在属性之前、没有进一步指定的注解,会由 Kotlin 2.4 根据它所接受的目标来定位:如果它是构造函数属性且注解允许,就放在构造函数参数上;如果注解允许,还会另外放在 Kotlin 属性本身上;否则放在字段上。Jakarta Persistence 注解([@Id]、[@Column]……)不适用于 Kotlin 参数或属性,而只适用于 Java 字段和方法:因此它们被放在 字段 上。这正是我们想要的:由于 [@Id] 注解在字段上,Hibernate 直接访问字段(即使字段是私有的,它也通过反射读写)。你可以使用 JDK 的 [javap] 工具来验证这一点,它可以显示 [.class] 文件的内容。你也可以通过前缀指定注解的目标:[@field:Column(length = 30)] 把它放在字段上,[@get:Transient] 则放在访问器上。

Jakarta Persistence 要求两样 Kotlin 类默认不提供的东西:

  • 一个 无参构造函数,Hibernate 用它创建从数据库读取的对象(然后再填充它们的字段)。我们的类只有一个构造函数,带有四个参数。在 Java 中,需要手动添加一个受保护的无参构造函数。在 Kotlin 中,则由针对 JPA 配置的编译器 插件 [no-arg]([kotlin("plugin.jpa")])把它添加到任何带有 [@Entity]、[@Embeddable]、或 [@MappedSuperclass] 注解的类中。这个构造函数存在于字节码中,Hibernate 通过反射找到它,但在 Kotlin 代码中不可见:[Article()] 仍然是编译错误(“[no value passed for parameter 'name'.]”)。请注意,它 不会执行 属性初始化:声明为 [var x = "a"] 的属性,在由 Hibernate 创建的对象中会被设为 [null] ,直到 Hibernate 给它赋值为止(构建文件中的 [noArg { invokeInitializers = true }] 选项会改变这一行为)。对于存储在数据库中的属性,这不是问题,因为 Hibernate 会给它们赋以读取到的值;
  • 非 final 的类和方法。为了实现懒加载(我们在讨论关系时会介绍),Hibernate 在运行时创建 代理:即从实体派生的类,其方法在第一次调用时从数据库加载对象。要使其工作,类及其方法必须可以被重写。在 Java 中,这是默认行为;在 Kotlin 中,类及其成员默认是 final 的(第 4 章)。[all-open] ([kotlin("plugin.allopen")])插件由构建文件中的 [allOpen] 块配置,它使带有所列注解之一的类——以及它们的属性和方法——成为非 final 的([open])。第 6 章的 [plugin.spring] 插件就是同一个插件,只是针对 Spring 注解进行了配置。

有了这两个插件,实体就可以写成普通的 Kotlin 类。没有它们的话,你就必须写 [open class Article(...)],为每个属性声明 [open] ,并添加一个无参的次构造函数:在下一个示例中,我们会对一个没有注解的类这样做。

为什么不使用 数据类 ([data class],第 4 章)呢?它似乎非常适合表示表中的一行。然而,对实体来说这是个糟糕的主意,原因有几个:

  • 生成的 [equals] 和 [hashCode] 方法会比较主构造函数的 所有 属性,而这些属性是可修改的。因此,一旦价格被修改,实体的哈希码就会改变:存储在 [HashSet] 中或用作 [HashMap] 键的商品就再也找不到了。Hibernate 自己就用这些方法来存储关系集合([Set])的元素;
  • 代表两个不同行(有两个不同标识符)但值相同的两个对象会被视为相等,而从数据库读取后又被修改过的商品,再次读取时却不再等于它自身;
  • 生成的 [toString] 方法会显示所有属性:有关系时,它会遍历关联的对象,这可能导致这些对象从数据库加载(意外的 SQL 查询)、会话已关闭时抛出异常,甚至在两个相互引用的实体之间出现无限递归;
  • 方法 [copy] 创建一个具有相同标识符的 新 对象,而会话并不认识它:这会导致同一行对应两个对象,可能造成混乱;
  • 程序员无法把数据类声明为 open([open])。[all-open] 插件无论如何都会把它打开,这使得可以创建代理(我们用 [javap] 工具验证过这一点),但它并不能纠正前面的任何问题。

因此,实体是一个普通的类:它的标识是表中的行,而不是其属性的值。与在 Java 中一样,它保留从 [equals]/[hashCode] 继承自 [Any] 的方法(对象标识),只要你不混用来自不同会话的对象,这就没有问题。对于不是实体的查询结果(投影),数据类在 Hibernate 中仍然非常有用,我们稍后会看到。这与 Java 中的规则相同:实体不能是 record。

最后一点说明:Hibernate 不识别 Kotlin 的可空类型。属性 [name] 的类型是 [String] (不可空)这一事实,并不会告诉 Hibernate 该列是必填的;只有注解 [@Column(nullable = false)] 才会告诉它这一点,我们将在结果中看到。

11.2.3. [SessionFactory] 和 [Session]

该程序使用三个 Hibernate 对象:

  • [SessionFactory] 表示针对某个数据库配置好的 Hibernate:实体列表、数据库和选项。创建它的开销很大(Hibernate 要分析实体,连接服务器以确定其版本,并为常见操作准备 SQL):每个数据库、每个应用程序只在启动时创建一个。它是 线程安全的:应用程序的所有线程都可以使用它;
  • [Session] 表示与数据库之间的一个 工作会话 。它在需要时获取连接,存储它读取或保存的实体,并知道如何把这些实体的更改提交到数据库。它是一个轻量级的、生命周期短暂的、非线程安全的对象:每个工作单元打开一个,然后关闭;
  • [Transaction]:在 Hibernate 中,所有对数据库的写入都发生在显式事务中,该事务由 [session.beginTransaction()] 开启,并由 [commit] (提交)或 [rollback] (回滚)结束。

[SessionFactory] 和 [Session] 实现了 [AutoCloseable] 接口:它们与 Kotlin 函数 [use] (第 3 章)一起使用,该函数在代码块结束时关闭它们,无论代码块是正常结束还是因异常而结束(相当于 Java 中带资源的 [try] 语句)。

11.2.4. 程序

package first

import org.hibernate.jpa.HibernatePersistenceConfiguration
import java.math.BigDecimal

fun main() {
    // SessionFactory:为 [hbfirst] 数据库配置的 Hibernate
    HibernatePersistenceConfiguration("first")
        // 实体
        .managedClass(Article::class.java)
        // 数据库;如果不存在,MySQL 会创建它
        .jdbcUrl("jdbc:mysql://localhost:3306/hbfirst?createDatabaseIfNotExist=true")
        .jdbcCredentials("root", "")
        // 显示格式化的、不带颜色的 SQL 语句
        .showSql(true, true, false)
        .createEntityManagerFactory().use { sessionFactory ->

            // 表先被删除,再根据实体重新创建
            sessionFactory.schemaManager.drop(false)
            sessionFactory.schemaManager.create(false)

            // 在事务中添加三件商品
            sessionFactory.openSession().use { session ->
                val transaction = session.beginTransaction()
                println("--- persist")
                session.persist(Article("bike", BigDecimal(500), 10, 5))
                session.persist(Article("pump", BigDecimal(10), 10, 2))
                session.persist(Article("bow", BigDecimal(600), 4, 1))
                println("--- commit")
                transaction.commit()
            }

            // 用新的会话读取表
            println("--- reading the articles")
            sessionFactory.openSession().use { session ->
                val articles: List<Article> = session
                    .createSelectionQuery("from Article order by name", Article::class.java)
                    .resultList
                articles.forEach { println(it) }
            }
        }
}
  • 第 8–16 行:创建 [SessionFactory]。配置 Hibernate 有多种方式(我们稍后会讨论);我们使用 Hibernate 7 的 [HibernatePersistenceConfiguration] 类,它是 Jakarta Persistence 3.2 引入的 [PersistenceConfiguration] 类的增强版,允许通过代码配置一切。它的参数是持久化单元的名称——一个可以自由选择的、会出现在 Hibernate 消息中的名称。每个方法都返回配置对象本身,因此可以链式调用;
  • 第 10 行:实体列表。[Article::class.java] 是 Java 对象 [Class] (Kotlin 类 [KClass] 并不合适:Hibernate 是一个 Java 库);
  • 第 12–13 行:数据库 [hbfirst] 的 JDBC URL,格式与第 10 章相同,以及用户([root],在 Laragon 中没有密码)。URL 的参数 [createDatabaseIfNotExist=true] 是 MySQL 驱动程序的一个选项:如果数据库不存在,就创建它;
  • 第 15 行:[showSql(true, true, false)] 指示 Hibernate 把它执行的每条 SQL 命令打印到控制台,格式化为多行(第二个参数),不带颜色(第三个参数)。查看发送到服务器的 SQL 是理解 Hibernate 行为的最佳方式:在所有示例中我们都会这样做;
  • 第 16 行:[createEntityManagerFactory] 构造 [SessionFactory] (方法名遵循标准;返回的类型是 Hibernate 的)。函数 [use] 将在程序结束时关闭它;在代码块内,它被称为 [sessionFactory];
  • 第 19–20 行:[SchemaManager] 对象属于 [SessionFactory] (Jakarta Persistence 3.2),负责管理实体的表:[drop(false)] 在这些表存在时删除它们,而 [create(false)] 创建它们(参数 [false] 指明不删除或创建数据库本身)。这对示例和测试很方便;实际应用程序以不同的方式管理其数据库,我们稍后会看到。Kotlin 把 Java 方法 [getSchemaManager()] 呈现为属性 [schemaManager] (第 4 章);
  • 第 23 行:[openSession()] 打开一个会话,它在 [use] 块结束时关闭;
  • 第 24 行:事务开始;
  • 第 26–28 行:[persist] 把三件新商品添加到会话中:它们将被存储到数据库中。没有为标识符指定任何值;它将由 DBMS 生成;
  • 第 30 行:[commit] 提交事务。在此之前,会话会把为保存它所存储的更改而仍需发送的 SQL 命令发给服务器:这被 称为 把 会话 “刷新”(flush)到数据库;
  • 第 36–38 行:用 HQL(Hibernate 的查询语言)编写的查询:按名称字母顺序排列的商品。它引用的是实体 [Article] 及其属性 [name],而不是表。[createSelectionQuery] 的第二个参数是结果类型:属性 [resultList] (即 Java 方法 [getResultList])返回一个 [List<Article>];
  • 第 39 行:显示商品。

如果在 [beginTransaction] 和 [commit] 之间发生异常,事务既不会被提交,也不会被我们的代码显式回滚:我们稍后会看到一种使用高阶函数来更安全地编写事务的方法。

子项目中的 [src/main/resources/logback.xml] 文件用于配置 Logback。它显示级别为 [INFO] 或更高的 Hibernate 消息,每条一行(级别、日志名称、消息):

<?xml version="1.0" encoding="UTF-8"?>
<!-- Logback 配置:Hibernate 的信息性消息,每条一行 -->
<configuration>
    <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
        <encoder>
            <pattern>%-5level %logger - %msg%n</pattern>
        </encoder>
    </appender>
    <root level="INFO">
        <appender-ref ref="CONSOLE"/>
    </root>
</configuration>

结果:

> gradlew -q :first:run
INFO  org.hibernate.orm.jpa - HHH008540: Processing PersistenceUnitInfo [name: first]
INFO  org.hibernate.orm.core - HHH000001: Hibernate ORM core version 7.4.5.Final
WARN  org.hibernate.orm.connections.pooling - HHH10001002: Using built-in connection pool (not intended for production use)
INFO  org.hibernate.orm.connections.pooling - HHH10001005: Database info:
    Database JDBC URL [jdbc:mysql://localhost:3306/hbfirst?createDatabaseIfNotExist=true]
    Database driver: MySQL Connector/J
    Database dialect: MySQLDialect
    Database version: 8.0.46
    Default catalog/schema: hbfirst/undefined
    Autocommit mode: false
    Isolation level: REPEATABLE_READ
    JDBC fetch size: none
    Pool: DriverManagerConnectionProvider
    Minimum pool size: 1
    Maximum pool size: 20
INFO  org.hibernate.orm.core - HHH000489: No JTA platform available (set 'hibernate.transaction.jta.platform' to enable JTA platform integration)
Hibernate:
    drop table if exists Article
Hibernate:
    create table Article (
        id integer not null auto_increment,
        currentStock integer not null,
        minimumStock integer not null,
        name varchar(255),
        price decimal(38,2),
        primary key (id)
    ) engine=InnoDB
--- persist
Hibernate:
    insert
    into
        Article
        (currentStock, minimumStock, name, price)
    values
        (?, ?, ?, ?)
Hibernate:
    insert
    into
        Article
        (currentStock, minimumStock, name, price)
    values
        (?, ?, ?, ?)
Hibernate:
    insert
    into
        Article
        (currentStock, minimumStock, name, price)
    values
        (?, ?, ?, ?)
--- commit
--- reading the articles
Hibernate:
    select
        a1_0.id,
        a1_0.currentStock,
        a1_0.minimumStock,
        a1_0.name,
        a1_0.price
    from
        Article a1_0
    order by
        a1_0.name
[1, bike, 500.00, 10, 5]
[3, bow, 600.00, 4, 1]
[2, pump, 10.00, 10, 2]

说明:

  • 第 2–17 行:Hibernate 的提示性消息:持久化单元的名称、Hibernate 版本,以及数据库的特征(URL、驱动程序、所选方言、服务器版本、事务隔离级别、连接池大小)。Hibernate 查询了服务器,以选择适合其版本的 [MySQLDialect] 方言;
  • 第 4 行:一条警告。Hibernate 管理它自己的小型连接池,该连接池不适用于生产环境的应用程序。我们将在 Spring 中看到如何为它提供第 10 章中的 HikariCP 连接池;对于我们的示例,内置的连接池就足够了;
  • 第 18–28 行:根据实体删除并创建表 [Article] :表名与实体名相同,列以属性命名,而列 [id] 是主键,其值是生成的([auto_increment])。类型为 [Int] 的属性所对应的列是 [not null]:它被编译为 [int];[Int] 不可能等于 [null]。类型为 [String] 和 [BigDecimal] 的属性接受值 [NULL],尽管 这些类型在 Kotlin 中是不可空的:对 Hibernate 而言,它们是 Java 引用([java.lang.String]、[java.math.BigDecimal]),可以被设为 [null];
  • 请注意默认类型:字符串对应 [varchar(255)] ,[decimal(38,2)] 对应 [BigDecimal] (38 位数字,其中包括 2 位小数)。这些很少是你想要的:下一段说明如何指定它们;
  • 第 29–51 行:配置好的三条 [INSERT] 命令在调用 [persist] 时 就被执行了,早于 [commit]。这是键由 DBMS 生成([IDENTITY])所导致的结果:会话一接管某个实体,就必须知道它的标识符,而要获得标识符,就必须执行插入(JDBC 驱动程序会返回生成的键;参见第 10 章)。对于其他生成方式,插入会推迟到会话同步时进行。参数值([?])没有显示:我们将看到如何让它们显示出来;
  • 第 53–63 行:HQL 查询 [from Article order by name] 被转换成了 [SELECT ... ORDER BY] 语句。Hibernate 给表分配了别名 [a1_0] ,并为读取的每一行创建了一个 [Article] 对象(第 64–66 行),使用的是由 [no-arg] 插件添加的无参构造函数。

我们没有编写任何 SQL 语句,也没有编写任何读取列的代码:这正是 ORM 的全部意义所在。我们也可以看到,这并不意味着不再需要理解 SQL:要判断生成的 SQL 是否正确、是否高效,你得会读懂它。

11.3. 模型

Hibernate 分三步根据实体构建其模型:

  • 首先,它应用 默认规则:凡是没有指定的内容,都会被赋予一个合理的值(这称为“约定优于配置”);
  • 然后,它使用放在实体上的 注解 来补充或更正这些值;
  • 最后,它应用 XML 映射文件 ([orm.xml]),这些文件可以完整地描述一个不带注解的类,或者修改其注解所指定的内容。

11.3.1. 默认规则

我们在第一个示例中已经看到了其中的要点:

  • 实体带有注解 [@Entity] ,并有一个由 [@Id] 指定的标识符;这两个注解都是必需的;
  • [@Id] 注解的位置决定了访问模式:放在字段上时,Hibernate 直接读写字段;放在 getter 或 setter([getId])上时,则通过 getter 和 setter([getX]/[setX])访问。通过字段访问是最常见的方式:它允许类拥有任何它想要的方法。在 Kotlin 中,放在属性之前的注解会应用到字段上(正如我们所见):这样无需任何显式指定就实现了通过字段访问。若要通过 getter 和 setter 访问,则需要写成 [@get:Id];
  • 任何带有幕后字段的属性都会存储在某一列中,除非它带有 Jakarta Persistence 注解 [@Transient] 或注解 [@kotlin.jvm.Transient](它会给字段添加 Java 修饰符 [transient]);计算属性的自定义访问器如果不使用 [field] (第 4 章),就没有字段:它永远不会被存储;
  • 表名是实体名(简单类名),列名是属性名。这些名称随后要经过一个 命名策略:Hibernate 的策略保持名称不变,而另一种策略——我们将在下面试用——会把它们转换成“蛇形命名”([currentStock] 变成 [current_stock])。Spring Boot 默认使用后者;
  • 被编译为基本类型的类型(不可空的 [Int]、[Double]、[Boolean])所对应的列会变成 [NOT NULL];被编译为引用的类型([Int?]、[String]、[BigDecimal]、[LocalDate],无论在 Kotlin 中是否可空)所对应的列接受值 [NULL]。因此,要让类型为 [String] 的属性所对应的列成为必填,就必须使用注解 [@Column(nullable = false)],尽管 Kotlin 类型本身已经禁止值 [null];
  • SQL 类型根据方言选择。在 MySQL 中:[integer] 对应 [Int],[bigint] 对应 [Long],[bit] 对应 [Boolean],[varchar(255)] 对应 [String],[decimal(38,2)] 对应 [BigDecimal],[date] 对应 [LocalDate],[datetime(6)] (精确到微秒)对应 [LocalDateTime]。枚举([enum class])默认按其序号存储(参见第 3 章);注解 [@Enumerated(EnumType.STRING)] 则按名称存储,这更可靠;
  • 引用另一个实体或实体集合的属性定义了一种关系(我们稍后会讨论)。

11.3.2. 注解与 XML 映射文件

子项目 [model] 定义了以两种不同方式配置的两个实体。它的构建文件与 [first] 的相同,只是把 Logback 依赖换成了对下文所述的 [tools] 库的依赖(它提供 Logback 及其配置)。第一个实体通过注解来配置:

package model

import jakarta.persistence.Column
import jakarta.persistence.Entity
import jakarta.persistence.GeneratedValue
import jakarta.persistence.GenerationType
import jakarta.persistence.Id
import jakarta.persistence.Table
import jakarta.persistence.Transient
import java.math.BigDecimal
import java.time.LocalDate

// 一个由注解配置的实体
@Entity
@Table(name = "products")
class Product(
    // 必填字符串,最多 50 个字符
    @Column(nullable = false, length = 50)
    var name: String,

    // 强制指定列的名称和 SQL 类型
    @Column(name = "price_excl_tax", nullable = false, precision = 10, scale = 2)
    var priceExclTax: BigDecimal,

    // 可选字符串(NULL 列),最多 200 个字符
    @Column(length = 200)
    var description: String? = null,

    // 一个可选日期:可空类型
    var withdrawalDate: LocalDate? = null,
) {
    // 主键:@Id,无论其名称是什么
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    var code: Int? = null

    // 一个没有列的属性
    @Transient
    var selected = false

    // computed 属性没有字段:它从不被保存
    val priceInclTax: BigDecimal
        get() = priceExclTax * BigDecimal("1.2")
}
  • 第 3–9 行:Jakarta Persistence 注解。对 [jakarta.persistence.Transient] 的显式导入,优先于 Kotlin 默认导入的同名注解 [kotlin.jvm.Transient];
  • 第 15 行:[@Table] 指定表名;
  • 第 18–19 行:[@Column] 指定列;[nullable = false] 使其成为必填([NOT NULL]);[length = 50] 设置其长度([varchar(50)]);
  • 第 22–23 行:[@Column] 还指定了列名([price_excl_tax]),以及对于十进制数,指定其精度(数字总位数)和标度(小数点后的位数):[decimal(10,2)];
  • 第 26–27 行:一个最多 200 个字符的可选描述:该列接受值 [NULL]。该属性的类型是 [String?],默认值为 [null]:Kotlin 类型与该列相匹配。让属性的可空或不可空类型与列的可选或必填性质相匹配是一种良好的做法,尽管 Hibernate 只读取注解;
  • 第 30 行:一个可选的日期。类型 [LocalDate] (第 5 章)表示不含时间的日期:它与 SQL 类型 [date] 相关联;
  • 第 32–35 行:主键,无论名称如何,都由 [@Id] 指定;
  • 第 38–39 行:[@Transient] 把属性排除在模型之外:在这里,指的是对用户界面有用但不属于数据库的信息;
  • 第 42–43 行:一个计算属性。它的访问器不使用字段:没有什么需要保存,而访问字段的 Hibernate 会忽略它。两个 [BigDecimal] 之间的运算符 [*] 是 Kotlin 标准库添加到 [BigDecimal] 的函数 [times] (第 4 章,运算符重载):我们写 [priceExclTax * BigDecimal("1.2")] ,而不是 Java 的 [priceExclTax.multiply(new BigDecimal("1.2"))]。

第二个实体没有注解:

package model

import java.time.LocalDateTime

// 一个没有任何注解的类:它的映射由 [supplier.orm.xml] 文件描述
// [jpa] 和 [allopen] 插件看不到它:它被声明为 [open]
// 并且有自己的无参构造函数
open class Supplier(
    private var companyName: String,
    private var phone: String?,
) {
    private var number: Int? = null
    private var creationDate: LocalDateTime? = null

    // Hibernate 所需的无参构造函数
    protected constructor() : this("", null)
}
  • 第 8 行:由于该类没有用 [@Entity] 注解,[no-arg] 和 [all-open] 插件不会识别它。所以我们自己把它声明为 [open],以便 Hibernate 能从中派生出代理;
  • 第 9–13 行:私有属性:Kotlin 既不为它们生成访问器,也不生成修改器,只生成一个私有字段,Hibernate 将读写该字段。这与 Java 类中的私有字段完全等价;
  • 第 16 行:Hibernate 所需的无参构造函数,手工编写:一个次构造函数,它用任意值调用主构造函数(第 4 章),Hibernate 会用从数据库读取的值替换这些值。它是受保护的:应用程序代码不会使用它。

它与表的映射由位于子项目 [src/main/resources/META-INF] 文件夹中的一个 XML 文件描述(这与 Java 中的文件相同):

<?xml version="1.0" encoding="UTF-8"?>
<!-- [Supplier] 类到其表的映射,用 XML 描述(Jakarta Persistence 3.2) -->
<entity-mappings xmlns="https://jakarta.ee/xml/ns/persistence/orm"
                 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                 xsi:schemaLocation="https://jakarta.ee/xml/ns/persistence/orm
                                     https://jakarta.ee/xml/ns/persistence/orm/orm_3_2.xsd"
                 version="3.2">
    <entity class="model.Supplier" access="FIELD">
        <table name="suppliers">
            <!-- 唯一索引:两个供应商不能有相同的公司名称 -->
            <index name="ix_suppliers_company_name" column-list="companyName" unique="true"/>
        </table>
        <attributes>
            <id name="number">
                <generated-value strategy="IDENTITY"/>
            </id>
            <basic name="companyName">
                <column nullable="false" length="60"/>
            </basic>
            <basic name="phone">
                <column name="tel" length="20"/>
            </basic>
            <!-- 由 DBMS 计算的默认值:Hibernate 从不写入此列 -->
            <basic name="creationDate">
                <column nullable="false" insertable="false" updatable="false"
                        column-definition="datetime(6) default current_timestamp(6)"/>
            </basic>
        </attributes>
    </entity>
</entity-mappings>
  • 第 3–7 行:Jakarta Persistence 3.2 映射文件的 XML 模式;
  • 第 8 行:所描述的类,通过字段访问;
  • 第 9–12 行:表,以及公司名称上的唯一索引:任何两个供应商都不能有相同的公司名称。等价的注解是 [@Table(name = "suppliers", indexes = [Index(...)])] (在 Kotlin 中,作为注解参数传入的数组写在方括号中);
  • 第 14–16 行:标识符,由 DBMS 生成;
  • 第 17–18 行:一个最多 60 个字符的必填列;
  • 第 20–21 行:属性 [phone] 存储在列 [tel] 中;
  • 第 24–26 行:创建日期有一个由 DBMS 计算的默认值。[column-definition] 属性提供列定义的 SQL 文本,它会被原样复制到 [CREATE TABLE] 命令中;[insertable="false"] 和 [updatable="false"] 表示 Hibernate 绝不能写入该列,这使得 DBMS 可以使用 [current_timestamp(6)]。

注解能做的一切都可以用 XML 完成。注解的优点是把配置放在属性旁边,这也是最常见的方式;而 XML 文件则使类保持独立于 Jakarta Persistence,并把配置集中在一处。两种方式可以结合使用:发生冲突时,以 XML 文件为准。Jakarta Persistence 不支持像其他 ORM 框架(例如 C# 中的 Entity Framework 或 Kotlin 中的 Exposed)那样通过代码来配置模型。

程序先显示 Hibernate 构建的模型,然后显示用于创建这些表的 SQL 脚本:

package model

import jakarta.persistence.metamodel.SingularAttribute
import org.hibernate.boot.model.naming.PhysicalNamingStrategySnakeCaseImpl
import org.hibernate.cfg.AvailableSettings
import org.hibernate.jpa.HibernatePersistenceConfiguration
import java.io.StringWriter

fun main() {
    // 建表脚本将写入这个对象
    val script = StringWriter()
    // 一个从不连接服务器的 SessionFactory
    HibernatePersistenceConfiguration("model")
        // 一个带注解的实体和一个用 XML 描述的映射
        .managedClass(Product::class.java)
        .mappingFile("META-INF/supplier.orm.xml")
        // 没有数据库:给出 DBMS 及其版本,用于 SQL 方言
        .property(AvailableSettings.JAKARTA_HBM2DDL_DB_NAME, "MySQL")
        .property(AvailableSettings.JAKARTA_HBM2DDL_DB_MAJOR_VERSION, "8")
        .property(AvailableSettings.ALLOW_METADATA_ON_BOOT, false)
        // "蛇形命名"的列名:companyName -> company_name
        .property(AvailableSettings.PHYSICAL_NAMING_STRATEGY,
            PhysicalNamingStrategySnakeCaseImpl::class.java.name)
        // 建表脚本,不执行
        .property(AvailableSettings.JAKARTA_HBM2DDL_SCRIPTS_ACTION, "create")
        .property(AvailableSettings.JAKARTA_HBM2DDL_SCRIPTS_CREATE_TARGET, script)
        .property(AvailableSettings.HBM2DDL_DELIMITER, ";")
        .property(AvailableSettings.FORMAT_SQL, true)
        .createEntityManagerFactory().use { sessionFactory ->

            // Hibernate 构建的模型:实体和属性(Jakarta Persistence API)
            for (entity in sessionFactory.metamodel.entities) {
                println("entity ${entity.name} (${entity.javaType.name})")
                for (attribute in entity.attributes) {
                    val id = attribute is SingularAttribute<*, *> && attribute.isId
                    println("  %-14s %s%s".format(attribute.name, attribute.javaType.simpleName,
                        if (id) " (identifier)" else ""))
                }
            }
        }
    // 建表脚本,去掉各行 4 个空格的缩进
    println("--- creation script")
    script.toString().trim().lines()
        .map { it.removePrefix("    ") }
        .forEach { println(it.trimEnd()) }
}
  • 第 11 行:一个 [StringWriter] (位于包 [java.io] 中),即写入内存中字符串的写入流,将接收 SQL 脚本;
  • 第 15–16 行:带注解的实体由 [managedClass] 声明,XML 文件由 [mappingFile] 声明;
  • 第 18–20 行:数据库永远不会存在:这个 [SessionFactory] 仅用于检查模型。因此,这里没有 JDBC URL。为了在不查询服务器的情况下选择 SQL 方言,Hibernate 需要 DBMS 的名称及其版本;[ALLOW_METADATA_ON_BOOT] 属性([hibernate.boot.allow_jdbc_metadata_access])阻止它在启动时连接。配置属性的名称是 [AvailableSettings] 接口中的常量;
  • 第 22 行:“蛇形命名”的命名约定,通过其类的名称([::class.java.name])表示;
  • 第 25–28 行:Hibernate 会把建表脚本(["create"])写入 [script] 对象而不执行它;各命令以分号结尾,并格式化为多行;
  • 第 32 行:属性 [metamodel] (Jakarta Persistence 的 [getMetamodel] 方法)提供对模型的访问:它的实体([EntityType])以及每个实体的属性([Attribute]);
  • 第 33–37 行:对每个实体,显示其名称和类;对每个属性,显示其名称、Java 类型以及它是否为标识符。在第 35 行,[attribute is SingularAttribute<*, *>] 测试之后是一次 智能转换 (第 4 章):在表达式 [&&] 的后续部分,[attribute] 是一个 [SingularAttribute],因此可以读取其属性 [isId]。[<*, *>] 投影取代了 Java 的 [<?, ?>];
  • 第 42–45 行:按原样显示的脚本,去掉了 Hibernate 在各行前面添加的四个空格([removePrefix] 仅在前缀存在时才删除它)。

结果:

> gradlew -q :model:run
WARN  connection - HHH102003: No appropriate connection provider encountered; client must supply connections
entity Product (model.Product)
  code           Integer (identifier)
  description    String
  name           String
  priceExclTax   BigDecimal
  withdrawalDate LocalDate
entity Supplier (model.Supplier)
  number         Integer (identifier)
  companyName    String
  creationDate   LocalDateTime
  phone          String
--- creation script
create table products (
    code integer not null auto_increment,
    price_excl_tax decimal(10,2) not null,
    withdrawal_date date,
    name varchar(50) not null,
    description varchar(200),
    primary key (code)
) engine=InnoDB;

create table suppliers (
    number integer not null auto_increment,
    creation_date datetime(6) default current_timestamp(6) not null,
    tel varchar(20),
    company_name varchar(60) not null,
    primary key (number)
) engine=InnoDB;

alter table suppliers
   add constraint ix_suppliers_company_name unique (company_name);
  • 第 2 行:Hibernate 的警告证实它无法建立连接;
  • 第 3–13 行:两个实体及其属性(先是标识符,然后其他属性按字母顺序排列;实体的顺序没有意义)。属性 [selected] 和计算属性 [priceInclTax] 没有出现在模型中。显示的类型是 Java 类型:[Integer] 对应 [Int?];
  • 第 15–21 行:表 [suppliers],由 XML 文件描述。命名策略把 [companyName] 和 [creationDate] 改成了 [company_name] 和 [creation_date];名称是固定的列 [tel] 保持不变。列 [creation_date] 的定义取自 XML 文件,并补充了 [not null];
  • 第 23–30 行:表 [products]。SQL 类型来自注解([varchar(50)]、[decimal(10,2)])或来自方言对某个类型的特定选择([integer]、[date]);
  • 第 32–33 行:唯一索引,在 MySQL 中由唯一性约束([unique])创建。

11.3.3. 生成的标识符

注解 [@GeneratedValue] 表示标识符的值是生成的。它的参数 [strategy] 指定生成方式:

策略
标识符的生成方式
[IDENTITY]
由 DBMS 在插入行时生成(MySQL 的 [AUTO_INCREMENT] 列、SQL Server 和 PostgreSQL 的 [IDENTITY] )
[SEQUENCE]
由 DBMS 的序列生成(PostgreSQL、Oracle),Hibernate 在插入之前查询该序列
[TABLE]
由 Hibernate 管理的计数器表生成
[UUID]
由 Hibernate 生成:一个随机的通用标识符,例如 [java.util.UUID]
[AUTO] (默认)
由 Hibernate 选择;对于没有序列的 MySQL,它使用一张名为 [<table>_SEQ] 的表来模拟序列

使用 MySQL 时,我们总是使用 [IDENTITY],它对应 [AUTO_INCREMENT] 列的自然行为。我们已经看到了其结果:[INSERT] 命令在调用 [persist] 时就被执行,而且 Hibernate 无法把多次插入合并为一个批处理(我们稍后会讨论批处理)。对于使用序列的 DBMS,则更倾向于使用 [SEQUENCE] 策略,它可以在插入之前就知道 ID。

在 Kotlin 中,生成的标识符最好声明为 [var id: Int? = null]:值 [null] 清楚地表示“尚未登记”。我们也会遇到 [var id: Int = 0],其中值 0 起到这个作用;Hibernate 接受这种写法(对于基本类型的标识符,它把 0 视为“尚未登记”的值),但这种约定可读性较差。

11.3.4. 可选值与 [NULL] 列

因此,一列是否可选,取决于属性的类型(被编译为基本类型还是引用)以及 [nullable] 的 [@Column] 属性;在 Kotlin 中,属性类型也指明值是否可以缺失([String?])或不可缺失([String])。你必须谨慎选择,并确保两者一致:这条规则既表达了代码约束(“该值可以缺失”),也表达了数据库约束。几点说明:

  • [@Column(nullable = false)] 表示 Hibernate 创建的模式中的 [NOT NULL] 约束,Hibernate 在发送 [INSERT] 或 [UPDATE] 命令之前也会使用它:如果字段为 [null],它就不会发送命令,而是抛出 [PropertyValueException] 错误(“not-null property references a null or transient value”)。当存在 Jakarta Validation(见下文)时,Hibernate 的这项检查默认被禁用:此时验证交由其注解来完成,或者在没有注解时交给 DBMS,由它拒绝该命令。在 Kotlin 中,这种情形比在 Java 中少见:编译器禁止把 [null] 赋给类型为 [String] 的属性;
  • 要在任何数据库访问之前执行更全面的验证,我们使用 Jakarta Validation ([hibernate-validator] 库)及其注解 [@NotNull]、[@Size(max = 30)]、[@Positive]……当它存在于类路径中时,Hibernate 会在保存实体之前验证它们,并使用这些注解来创建列。在 Kotlin 中,这些注解也接受参数作为目标:当应用于构造函数属性时,Kotlin 2.4 会同时把它们应用于参数和字段,验证器读取的是字段。早期版本只把它们放在参数上:你必须指定字段目标 [@field:Size(max = 30)],这种写法在许多示例中仍然可以见到;
  • 无需使用 [Optional] (第 4 章):Kotlin 的可空类型([var description: String? = null])直接表明某个值是可选的,并且使用运算符 [?.] 和 [?:] 来读取它(第 3 章):[product.description ?: "(no description)"]。

11.4. 后续示例:两个公共库

以下各段中的示例几乎都使用 [hbarticles] 数据库及其 [articles] 表,表中填充了第 10 章中的六条记录。我们不在每个子项目中重复 Hibernate 实体和配置,而是把它们放在一个库——即 [articles] 子项目——中,其他子项目依赖于它。我们还把 [showSql] 的 SQL 日志——对我们的示例来说过于冗长——替换为更紧凑的日志,放在第二个库,即 [tools] 子项目中。

11.4.1. 紧凑的 SQL 日志

Hibernate 不直接写入控制台([showSql]),而是可以把它的活动转发给日志系统(此处为 Logback),每个消息类别写入不同的日志记录器:

日志
级别
消息
[org.hibernate.SQL]
[DEBUG]
执行的 SQL 命令
[org.hibernate.orm.jdbc.bind]
[TRACE]
SQL 命令中每个参数的值
[org.hibernate.orm.resource.jdbc]
[TRACE]
其中包括事务的开始、确认和取消等
[org.hibernate.orm.jdbc.batch]
[TRACE]
SQL 命令批处理的执行
[org.hibernate.orm.jdbc.error]
[WARN]
DBMS 报告的错误

日志只记录级别等于或高于其自身级别的消息。因此,只需在 [logback.xml] 文件中为这些日志设置所需的级别,就能捕获这些消息。我们通过一个使消息更紧凑的布局类来处理它们:

package tools

import ch.qos.logback.classic.Level
import ch.qos.logback.classic.Logger
import ch.qos.logback.classic.spi.ILoggingEvent
import ch.qos.logback.core.LayoutBase
import org.slf4j.LoggerFactory

// Hibernate 所执行 SQL 语句的紧凑日志:一个 Logback 布局
class SqlLog : LayoutBase<ILoggingEvent>() {

    // 消息的布局:返回要写入的文本("":不写入任何内容)
    override fun doLayout(event: ILoggingEvent): String {
        val message = event.formattedMessage
        return when (event.loggerName) {
            SQL -> sqlStatement(message)
            PARAMETERS -> parameter(message)
            TRANSACTIONS -> transaction(message)
            ERRORS -> dbError(message)
            BATCHES -> batch(message)
            else -> ""
        }
    }

    companion object {
        // 所使用的 Hibernate 日志记录器
        const val SQL = "org.hibernate.SQL"
        const val PARAMETERS = "org.hibernate.orm.jdbc.bind"
        const val TRANSACTIONS = "org.hibernate.orm.resource.jdbc"
        const val ERRORS = "org.hibernate.orm.jdbc.error"
        const val BATCHES = "org.hibernate.orm.jdbc.batch"

        // 写在单行上的子句的最大长度
        private const val WIDTH = 100

        // 执行一批 SQL 语句:"Executing JDBC batch (3 / 3) - [...]"
        private val BATCH = Regex("""Executing JDBC batch \((\d+) / \d+\).*""")

        // 绑定到 SQL 语句的参数:"binding parameter (1:VARCHAR) <- [bike]"
        private val PARAMETER = Regex("""binding parameter \((\d+):\w+\) <- \[(.*)]""")

        // 由 Hibernate 格式化的 SQL 语句,使其更紧凑:每个子句一行(select、from……)
        private fun sqlStatement(sql: String): String {
            // 非空行,去掉行尾空格
            val lines = sql.lines().map { it.trimEnd() }.filter { it.isNotBlank() }
            // 各子句:一个顶层行(缩进最少的)及其后的各行
            val indentation = lines.minOfOrNull { indentation(it) } ?: 0
            val clauses = mutableListOf<MutableList<String>>()
            for (line in lines) {
                if (clauses.isEmpty() || indentation(line) == indentation) clauses.add(mutableListOf())
                clauses.last().add(line.substring(indentation))
            }
            // 如果不太长,每个子句写在一行上
            var start = ""
            return buildString {
                for (clause in clauses) {
                    val line = start + clause.joinToString(" ") { it.trim() }
                    if (line == "insert" || line == "delete") {
                        // [insert into ...]、[delete from ...]:单独一行
                        start = "$line "
                        continue
                    }
                    if (line.length <= WIDTH) {
                        append("    SQL> ").append(line).append('\n')
                    } else {
                        // 子句太长:保留 Hibernate 的各行
                        clause.forEachIndexed { i, l ->
                            append("    SQL> ").append(if (i == 0) start else "").append(l).append('\n')
                        }
                    }
                    start = ""
                }
            }
        }

        // 行首的空格数
        private fun indentation(line: String) = line.length - line.trimStart().length

        // SQL 语句某个参数的值
        private fun parameter(message: String): String =
            PARAMETER.matchEntire(message)
                ?.let { "    SQL> -- parameter ${it.groupValues[1]} = ${it.groupValues[2]}\n" } ?: ""

        // 事务的开始、提交和回滚(忽略其他消息)
        private fun transaction(message: String): String = when {
            message.startsWith("HHH10003002") -> "    SQL> -- start of transaction\n"
            message.startsWith("HHH10003004") -> "    SQL> -- transaction committed (COMMIT)\n"
            message.startsWith("HHH10003006") -> "    SQL> -- transaction rolled back (ROLLBACK)\n"
            else -> ""
        }

        // DBMS 报告的错误(给出其错误码的那一行被忽略)
        private fun dbError(message: String): String =
            if (message.startsWith("HHH000247")) "" else "    SQL> -- failure: $message\n"

        // 一批 SQL 语句的执行(忽略其他消息)
        private fun batch(message: String): String =
            BATCH.matchEntire(message)
                ?.let { "    SQL> -- execution of a batch of ${it.groupValues[1]} statement(s)\n" } ?: ""

        // 不记录 SQL 日志地执行一个操作并返回其结果
        fun <T> withoutLog(action: () -> T): T {
            val loggers = listOf(SQL, PARAMETERS, TRANSACTIONS, ERRORS, BATCHES)
                .map { LoggerFactory.getLogger(it) as Logger }
            // 当前级别,在结束时恢复
            val levels: List<Level?> = loggers.map { it.level }
            loggers.forEach { it.level = Level.OFF }
            try {
                return action()
            } finally {
                loggers.zip(levels).forEach { (logger, level) -> logger.level = level }
            }
        }
    }
}
  • 第 10 行:Logback 布局派生自 Java 类 [LayoutBase<ILoggingEvent>] (注意括号:这是对父类构造函数的调用,第 4 章);它的方法 [doLayout] (第 13–21 行)接收每条消息([ILoggingEvent])并返回要写出的文本。Logback 根据类名通过反射自行创建该对象:它需要一个无参构造函数,也就是该类隐式的主构造函数;
  • 第 15–21 行:处理方式取决于发出消息的日志(对日志通道使用 ***[when] ,第 3 章)。各分支使用 ***[companion object] 中的常量;
  • 第 25 行:类的“静态”成员存储在它的伴生对象中(第 4 章);
  • 第 27–31 行:所用 Hibernate 日志的名称,以及公开的编译期常量([const val]);其他子项目通过 [SqlLog.SQL]……来引用它们;
  • 第 37–40 行:两个正则表达式(第 5 章),写成原始字符串(["""..."""]),这样就不必像 Java 那样把反斜杠写两遍(["\\((\\d+)..."]);
  • 第 43–71 行:由 Hibernate 格式化([format_sql])的 SQL 命令,分散在许多行中,每列占一行。我们使它更紧凑。非空行被分组为子句(第 47–51 行):子句以顶层行([select]、[from]、[where]……)开头,并包含其后缩进的各行。[minOfOrNull] 给出最小的缩进量,如果没有任何行则给出 [null] ,此时用运算符 [?:] 把它替换为 0。然后,每个子句如果不超过 100 个字符,就写在单独一行上,前面加 [SQL>](第 63–64 行);否则保留其各行(第 67–68 行)。子句 [insert] 和 [delete] 会与其后的子句合并(第 58–61 行)。文本由 [buildString] (第 5 章)构造,其代码块以 [StringBuilder] 作为接收者:在其中调用 [append] 时无需前缀;
  • 第 80–82 行:返回参数值的 Hibernate 消息形如 [binding parameter (1:VARCHAR) <- [bike]]。如果整条消息与正则表达式匹配,[matchEntire] 就返回一个 [MatchResult] ,否则返回 [null];[?.let] 根据捕获的分组(参数编号及其值)构造文本,而 [?: ""] 在不匹配时返回空字符串;
  • 第 85–89 行:在 [org.hibernate.orm.resource.jdbc] 日志的众多消息中,只保留指示事务开始、提交和回滚的那些。每条 Hibernate 消息都以一个唯一标识它的代码([HHH10003002]……)开头。不带参数的 [when] (第 3 章)取代了 Java 的 [if] 序列;
  • 第 93–94 行:DBMS 中的错误。Hibernate 把它写成两条消息:一条提供错误码(我们忽略它),另一条提供错误文本;
  • 第 97–99 行:一批 SQL 命令的执行,我们将在本章末尾遇到它;
  • 第 102–111 行:函数 [withoutLog] 执行不带日志的 SQL 操作。这是一个高阶函数(第 7 章):它的参数是函数 [() -> T],并返回该操作的结果(使用 [Runnable] 的 Java 做不到这么轻松)。它使用 Logback 的 API:每个日志([Logger])都有一个级别,可以在运行时修改([level] 属性,对应 Java 方法 [getLevel]/[setLevel])。我们把这五个日志设为 [OFF] 级别,执行该操作,然后在 [finally] 子句中恢复原来的级别,这样即使操作抛出异常,它们也能保持原有级别。原来的级别可能是 [null] (从其父日志继承级别的日志),因此类型是 [List<Level?>];[zip] 把每个日志与其原来的级别关联起来,而 [(logger, level)] 解构(第 3 章)为每一对中的两个元素命名;
  • 第 104 行:[LoggerFactory] 是 SLF4J 中返回日志的类;由于 Logback 是 SLF4J 当前的实现,返回的对象是 [ch.qos.logback.classic.Logger],类型转换 [as Logger] 表明了这一点。

[tools] 子项目还包含各示例所使用的 [logback.xml] 文件(它与 Java 中的文件相同)。它放在类路径的根目录([src/main/resources])下,程序启动时 Logback 会找到它:

<?xml version="1.0" encoding="UTF-8"?>
<!-- 本章示例的 Logback 配置 -->
<configuration>

    <!-- 紧凑的 SQL 日志:由 [tools.SqlLog] 类提供布局 -->
    <appender name="SQL" class="ch.qos.logback.core.ConsoleAppender">
        <encoder class="ch.qos.logback.core.encoder.LayoutWrappingEncoder">
            <layout class="tools.SqlLog"/>
        </encoder>
    </appender>

    <!-- 其他消息:级别、日志记录器的短名称、文本 -->
    <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
        <encoder>
            <pattern>%-5level %logger{0} - %msg%n</pattern>
        </encoder>
    </appender>

    <!-- SQL 语句(DEBUG)、它们的参数、事务、批处理(TRACE)和错误 -->
    <logger name="org.hibernate.SQL" level="DEBUG" additivity="false">
        <appender-ref ref="SQL"/>
    </logger>
    <logger name="org.hibernate.orm.jdbc.bind" level="TRACE" additivity="false">
        <appender-ref ref="SQL"/>
    </logger>
    <logger name="org.hibernate.orm.resource.jdbc" level="TRACE" additivity="false">
        <appender-ref ref="SQL"/>
    </logger>
    <logger name="org.hibernate.orm.jdbc.batch" level="TRACE" additivity="false">
        <appender-ref ref="SQL"/>
    </logger>
    <logger name="org.hibernate.orm.jdbc.error" level="WARN" additivity="false">
        <appender-ref ref="SQL"/>
    </logger>

    <!-- Hibernate 内置的连接池对我们的示例已经足够:它的警告被静默 -->
    <logger name="org.hibernate.orm.connections.pooling" level="ERROR"/>

    <!-- 删除空数据库的表会产生无害的错误:它们被静默 -->
    <logger name="org.hibernate.tool.schema" level="OFF"/>

    <!-- 所有其他日志记录器:只记录警告和错误 -->
    <root level="WARN">
        <appender-ref ref="CONSOLE"/>
    </root>
</configuration>
  • 第 6–10 行:一个“追加器”(appender)负责写出消息,这里是写到控制台。它使用我们的布局,通过其类名([tools.SqlLog])来标识;
  • 第 13–17 行:用于其他消息的第二个“追加器”:级别、日志短名称、文本;
  • 第 20–34 行:上表中的 Hibernate 日志及其级别。它们的消息被发送到“追加器” [SQL] ,并且只发送到它([additivity="false"]:它们不会再被额外转发给根日志);
  • 第 37 行:关于 Hibernate 内置连接池的警告被抑制;
  • 第 40 行:Hibernate 删除表时从其外键开始;在空数据库上,这些删除会失败但没有后果,不过 Hibernate 会把这一点冗长地记入日志。这些消息被抑制;
  • 第 43–45 行:其他日志只记录警告和错误。

[tools] 子项目的构建文件是一个库的构建文件(第 6 章):

// 库:Hibernate 所执行 SQL 语句的紧凑日志
plugins {
    kotlin("jvm")
    // 库插件:它添加 [api] 配置
    `java-library`
}

repositories {
    mavenCentral()
}

dependencies {
    // Logback,它将接收 Hibernate 日志(JBoss Logging 会检测到它);
    // [api]:SqlLog 类派生自 Logback 的一个类,它的使用者必须看到这个类
    api("ch.qos.logback:logback-classic:1.5.38")
}

kotlin {
    jvmToolchain(25)
    compilerOptions {
        allWarningsAsErrors = true
        javaParameters = true
    }
}
  • 第 5 行:库插件,它添加了 [api] 配置;
  • 第 15 行:唯一的依赖,Logback。它用 [api] 而不是 [implementation] 声明:类 [SqlLog] 派生自 Logback 的一个类,使用它的子项目必须在编译时能看到这个父类。用 [api] 声明的依赖会提供给该库的使用者,既用于编译,也用于运行时。

库通常不会把自己的日志配置强加给使用它的应用程序;我们在这里这样做,是为了避免在每个示例中重复这个文件。

11.4.2. 实体与商品数据库

[articles] 子项目中的 [Article] 实体使用了上一段中的注解:

package articles

import jakarta.persistence.Column
import jakarta.persistence.Entity
import jakarta.persistence.GeneratedValue
import jakarta.persistence.GenerationType
import jakarta.persistence.Id
import jakarta.persistence.Table
import jakarta.persistence.UniqueConstraint
import java.math.BigDecimal

// 商店的一件商品,带有指定其表的注解
// 一个普通类(不是数据类);[jpa] 插件为它添加一个无参构造函数,
// [allopen] 插件使它及其属性成为 open(非 final)
@Entity
@Table(
    name = "articles",
    uniqueConstraints = [UniqueConstraint(name = "uk_articles_name", columnNames = ["name"])]
)
class Article(
    // 商品名称:必填,最多 30 个字符,唯一(参见 @Table)
    @Column(nullable = false, length = 30)
    var name: String,
    // 价格:10 位数字,其中小数点后 2 位
    @Column(nullable = false, precision = 10, scale = 2)
    var price: BigDecimal,
    // 当前库存和最低库存,低于最低库存就需要补货
    var currentStock: Int,
    var minimumStock: Int,
) {
    // 主键,由 DBMS 生成(AUTO_INCREMENT):在商品被保存之前为 null
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    var id: Int? = null
        // 应用程序不得修改:标识符由 Hibernate 管理
        protected set

    // 显示
    override fun toString() = "[%d, %s, %.2f, %d, %d]".format(id, name, price, currentStock, minimumStock)
}
  • 第 13–14 行:提醒一下 [jpa] 和 [allopen] 插件为该类所做的事情;
  • 第 16–18 行:表名为 [articles],与第 10 章相同。参数 [uniqueConstraints] 在列 [uk_articles_name] 上声明了一个名为 [name] 的唯一性约束:两件商品不能同名。如果没有显式名称,Hibernate 会生成一个难以辨认的名称([UK3f8k...]),它会出现在错误消息中。数组类型的注解参数在 Kotlin 中写在方括号内([[UniqueConstraint(...)]]、[["name"]]);用作另一个注解的实参的注解,写法中不带 [@];
  • 第 22–23 行:一个不超过 30 个字符的必填名称;
  • 第 25–26 行:格式为 [decimal(10,2)] 的价格;
  • 第 28–29 行:两个库存量,类型为 [Int]:列为 [NOT NULL];
  • 第 32–36 行:标识符。该属性的修饰符声明为 [protected]:应用程序可以读取标识符,但不能更改它,因为它由 Hibernate 管理(出于同样的原因,Java 类没有 [setId] 方法)。它不能是 [private]:该属性是公开的([all-open]),而 Kotlin 禁止在公开属性上使用 private 修饰符,因为派生类可能重新定义它(“[private setters for open properties are prohibited.]”);
  • 第 39 行:与第一个示例中相同的 [toString] 方法。

这个类的 Java 版本有近九十行,包括两个构造函数和大约十个访问器([getX]/[setX]);在 Kotlin 中,主构造函数的属性和两个插件就起到了这些作用。

[BaseArticles] 对象包含 [hbarticles] 数据库的 Hibernate 配置:

package articles

import org.hibernate.SessionFactory
import org.hibernate.cfg.AvailableSettings
import org.hibernate.jpa.HibernatePersistenceConfiguration
import tools.SqlLog
import java.math.BigDecimal

// [hbarticles] 数据库:Hibernate 配置和数据库初始化
// 一个 [object]:单个实例,没有构造函数(相当于 Java 的工具类)
object BaseArticles {

    // 数据库;如果不存在,MySQL 会创建它(createDatabaseIfNotExist)
    const val URL = "jdbc:mysql://localhost:3306/hbarticles?createDatabaseIfNotExist=true"
    const val USER = "root"
    const val PASSWORD = ""

    // Hibernate 配置:实体、数据库、所记录 SQL 的格式化
    fun configuration(): HibernatePersistenceConfiguration =
        HibernatePersistenceConfiguration("articles")
            .managedClass(Article::class.java)
            .jdbcUrl(URL)
            .jdbcCredentials(USER, PASSWORD)
            .property(AvailableSettings.FORMAT_SQL, true)

    // [hbarticles] 数据库的 SessionFactory,使用前面的配置
    fun createSessionFactory(): SessionFactory = configuration().createEntityManagerFactory()

    // (重新)创建 [articles] 表及其六件商品,不记录 SQL 日志
    fun initialize(sessionFactory: SessionFactory) = SqlLog.withoutLog {
        // 先删除再创建实体的表
        sessionFactory.schemaManager.drop(false)
        sessionFactory.schemaManager.create(false)
        // 六件商品,在事务中添加
        sessionFactory.inTransaction { session ->
            session.persist(Article("bike", BigDecimal(500), 10, 5))
            session.persist(Article("pump", BigDecimal(10), 10, 2))
            session.persist(Article("bow", BigDecimal(600), 4, 1))
            session.persist(Article("arrows - set of 6", BigDecimal(100), 12, 20))
            session.persist(Article("diving suit", BigDecimal(300), 8, 2))
            session.persist(Article("diver's oxygen tanks", BigDecimal(120), 10, 5))
        }
    }
}
  • 第 11 行:一个 [object] (第 4 章):单例,在首次使用时创建。这相当于 Java 的工具类(一个带有静态成员和私有构造函数的 [final] 类);
  • 第 14–16 行:数据库 URL 和用户,它们是公开的,以便其他子项目可以使用;
  • 第 19–24 行:Hibernate 配置。它由一个公开函数返回,这使得示例可以在创建 [SessionFactory] 之前对其进行补充。[FORMAT_SQL] ([hibernate.format_sql])属性指示 Hibernate 格式化 SQL,然后把它传给 [org.hibernate.SQL] 日志:[SqlLog] 类随后压缩的正是这份格式化后的输出;
  • 第 27 行:来自 [SessionFactory] 数据库 [hbarticles] 的会话工厂,一个函数体为表达式的函数;
  • 第 30–41 行:一个函数,它重新创建带有六条记录的表 [articles] ,不记录 SQL 日志:我们不希望在示例结果中看到这次初始化所产生的 SQL。传给 [withoutLog] 的代码块是写在括号之后的 lambda,括号在这里被省略了(第 7 章);
  • 第 35 行:[sessionFactory.inTransaction { session -> ... }] 打开一个会话,开始一个事务,把会话传给 lambda 并执行它,提交事务(如果 lambda 抛出异常则回滚),然后关闭会话。这是编写工作单元的最短方式;我们会经常使用它及其变体 [inSession] (不带事务的会话)、[fromTransaction]、和 [fromSession] (它们返回 lambda 的结果)。这些 Java 方法的参数是函数式接口([Consumer<Session>]、[Function<Session, R>]):Kotlin 在那里直接接受 lambda(SAM 转换,第 7 章);
  • 第 36–41 行:[BigDecimal(500)] 调用 [BigDecimal] 的构造函数,它接收一个整数;它返回的值与 Java 方法 [BigDecimal.valueOf(500)] 相同。

[articles] 子项目依赖于 [tools] 子项目、Hibernate 和 JDBC 驱动程序:

// 库:[Article] 实体和 [hbarticles] 数据库的 SessionFactory 工厂
plugins {
    kotlin("jvm")
    // 实体的无参构造函数(为 JPA 配置的 "no-arg" 插件)
    kotlin("plugin.jpa")
    // 实体和属性被设为 open(非 final):Hibernate 可以从中派生代理
    kotlin("plugin.allopen")
    // 库插件:它添加 [api] 配置
    `java-library`
}

repositories {
    mavenCentral()
}

dependencies {
    // 紧凑的 SQL 日志(以及 Logback)
    api(project(":tools"))
    // Hibernate:[api],因为库的使用者会处理 SessionFactory、Session……
    api("org.hibernate.orm:hibernate-core:7.4.5.Final")
    // MySQL JDBC 驱动:只在运行时有用
    runtimeOnly("com.mysql:mysql-connector-j:9.7.0")
}

// 以这种方式标注的类由 [allopen] 插件打开
allOpen {
    annotation("jakarta.persistence.Entity")
    annotation("jakarta.persistence.MappedSuperclass")
    annotation("jakarta.persistence.Embeddable")
}

kotlin {
    jvmToolchain(25)
    compilerOptions {
        allWarningsAsErrors = true
        javaParameters = true
    }
}
  • 第 5–9 行:该库定义了一个实体;它同时应用两个实体插件和库插件;
  • 第 18 行:对构建中另一个子项目的依赖,通过其路径([":tools"])标识;
  • 第 20 行:Hibernate,用 [api] 声明:直接使用该库的子项目会操作它的类型([SessionFactory]、[Session]……);
  • 第 22 行:JDBC 驱动程序,仅在运行时需要;
  • 第 26–29 行:[all-open] 插件的配置。

这样,各示例子项目只需要一个依赖:[articles] 子项目。Gradle 会添加它的依赖(称为 传递依赖):用于编译和执行的 [api] 依赖,以及用于执行的 [runtimeOnly] 依赖。下面是 [crud] 子项目的构建文件:

// 基本操作:persist、find、merge、remove;实体的各种状态
plugins {
    kotlin("jvm")
    // 没有 [jpa] 或 [allopen] 插件:该子项目不定义任何实体
    // (Article 类在 [articles] 子项目中编译)
    application
}

repositories {
    mavenCentral()
}

dependencies {
    // [Article] 实体和 [hbarticles] 数据库(包含 Hibernate、MySQL 和 SQL 日志)
    implementation(project(":articles"))
}

kotlin {
    jvmToolchain(25)
    compilerOptions {
        allWarningsAsErrors = true
        javaParameters = true
    }
}

application {
    // 由 [gradlew -q :crud:run] 运行的程序,在 11-hibernate 文件夹中启动
    mainClass = "crud.MainKt"
}

// 在 Windows 上,由 Gradle(run、bootRun 等)启动的程序的屏幕输出以 UTF-8 编码,
// 否则带重音符号的字符在 IntelliJ IDEA 控制台或终端中会出现乱码
tasks.withType<JavaExec>().configureEach {
    jvmArgs("-Dstdout.encoding=UTF-8", "-Dstderr.encoding=UTF-8")
}
  • 第 4 行:该子项目不定义任何实体:它不需要 [jpa] 和 [allopen] 插件,这些插件用于编译带注解的类,在这里就是 [articles] 子项目中的那些类;
  • 第 15 行:唯一的依赖;
  • 第 31–34 行:由 Gradle 启动的程序以 UTF-8 编码输出,以便带重音符号的字符在 Windows 上能正确显示(第 2 章)。

11.4.3. 配置 Hibernate 的其他方式

我们使用 [HibernatePersistenceConfiguration] 以编程方式配置 Hibernate。还有其他方式,你可以在应用程序和文档中见到:

  • [META-INF/persistence.xml] 文件,Jakarta Persistence 采用的传统方式:它描述一个或多个持久化单元(实体类、连接属性、选项),工厂通过 [Persistence.createEntityManagerFactory("articles")] 创建;
  • [hibernate.properties] (或 [hibernate.cfg.xml])文件,是 Hibernate 特有的,由 [org.hibernate.cfg.Configuration] 类读取:[Configuration().addAnnotatedClass(Article::class.java).buildSessionFactory()]。这是旧版本 Hibernate 中使用的方式;
  • 在 Spring Boot 应用程序中,使用文件 [application.properties] 中的属性 [spring.datasource.*] 和 [spring.jpa.*]:Spring Boot 自己创建工厂。

各处的属性都是相同的([hibernate.format_sql]、[jakarta.persistence.jdbc.url]……):变化的只是指定它们的方式。

11.5. 基本操作:添加、读取、更新、删除

11.5.1. [crud] 程序

[crud] 子项目演示了四种基本操作(CRUD:创建、读取、更新、删除),以及通过会话对实体的跟踪。为了使这种跟踪可见,它使用了 Hibernate 的一些内部方法(其“SPI”,即服务提供者接口),这些方法是为 Hibernate 的扩展而不是应用程序设计的:它们被归集在文件末尾的工具函数中,写成 [Session] 的 扩展函数 (第 4 章)。事务使用会话的 [inTransaction] 方法编写,这是一个高阶函数:[session.inTransaction { ... }] 开始一个事务,执行代码块,然后提交事务,或者在代码块抛出异常时 回滚它。代码不会再在出错时遗漏 [commit] 或 [rollback] 。

package crud

import articles.Article
import articles.BaseArticles
import org.hibernate.Session
import org.hibernate.engine.spi.PersistenceContext
import org.hibernate.engine.spi.SessionImplementor
import java.math.BigDecimal

fun main() {
    BaseArticles.createSessionFactory().use { sessionFactory ->
        // [articles] 表被重新创建,含六件商品
        BaseArticles.initialize(sessionFactory)
        sessionFactory.openSession().use { session ->
            // 1 - 按主键搜索
            println("--- find(1)")
            val bike = session.find(Article::class.java, 1) ?: error("no article no. 1")
            println(bike)
            println("--- find(1) a second time")
            val bike2 = session.find(Article::class.java, 1)
            println("same object: ${bike === bike2}")

            // 2 - 在事务中添加一件商品
            println("--- persist")
            val x = Article("x", BigDecimal(100), 10, 1)
            session.inTransaction {
                println("before persist: state=${session.state(x)}, id=${x.id}")
                session.persist(x)
                println("after persist: state=${session.state(x)}, id=${x.id}")
            }

            // 3 - 修改:只需修改对象即可
            println("--- modification of the price")
            session.inTransaction {
                x.price *= BigDecimal("1.1")
                println("session modified: ${session.isDirty}, " +
                    "original price=${session.originalValue(x, "price")}, current price=${x.price}")
                println("--- commit")
            }
            println("after commit: session modified: ${session.isDirty}")

            // 4 - 删除
            println("--- remove")
            session.inTransaction {
                session.remove(x)
                println("before commit: state=${session.state(x)}")
            }
            println("after commit: state=${session.state(x)}")

            // 5 - 一个游离对象,修改后与会话合并
            println("--- detach and merge")
            val bow = session.find(Article::class.java, 3) ?: error("no article no. 3")
            session.detach(bow)
            println("after detach: state=${session.state(bow)}")
            bow.price = BigDecimal(550)
            session.inTransaction {
                val managedBow = session.merge(bow)
                println("merge: same object=${bow === managedBow}, " +
                    "state of the returned object=${session.state(managedBow)}")
            }

            // 6 - 会话所跟踪的实体
            println("--- the tracked entities")
            bike.currentStock--
            session.displayTrackedEntities()
        }
    }
}

// 会话的持久化上下文(Hibernate 内部 API):一个扩展属性
private val Session.trackingContext: PersistenceContext
    get() = unwrap(SessionImplementor::class.java).persistenceContext

// 商品相对于会话的状态(Hibernate 内部 API)
private fun Session.state(article: Article): String = when {
    // 被会话跟踪的对象:MANAGED、DELETED……
    trackingContext.isEntryFor(article) -> trackingContext.getEntry(article).status.name
    // 会话未知的对象:从未保存(没有标识符)或已游离
    article.id == null -> "TRANSIENT"
    else -> "DETACHED"
}

// 属性从数据库读取时的值(Hibernate 内部 API)
private fun Session.originalValue(entity: Any, property: String): Any? =
    trackingContext.getEntry(entity).getLoadedValue(property)

// 会话持久化上下文中的实体(Hibernate 内部 API)
private fun Session.displayTrackedEntities() {
    for ((entity, entry) in trackingContext.reentrantSafeEntityEntries()) {
        val persister = entry.persister
        println("${persister.entityName} #${entry.id} ${entry.status}")
        // 属性的当前值,与从数据库读取的值进行比较
        val current = persister.getValues(entity)
        val originals = entry.loadedState
        persister.propertyNames.forEachIndexed { i, name ->
            val modification = if (current[i] == originals[i]) ""
                else " (modified, original value: ${originals[i]})"
            println("    $name : ${current[i]}$modification")
        }
    }
    println("session modified: $isDirty")
}

结果:

> gradlew -q :crud:run
--- find(1)
    SQL> select a1_0.id, a1_0.currentStock, a1_0.minimumStock, a1_0.name, a1_0.price
    SQL> from articles a1_0
    SQL> where a1_0.id=?
    SQL> -- parameter 1 = 1
[1, bike, 500.00, 10, 5]
--- find(1) a second time
same object: true
--- persist
    SQL> -- start of transaction
before persist: state=TRANSIENT, id=null
    SQL> insert into articles (currentStock, minimumStock, name, price)
    SQL> values (?, ?, ?, ?)
    SQL> -- parameter 1 = 10
    SQL> -- parameter 2 = 1
    SQL> -- parameter 3 = x
    SQL> -- parameter 4 = 100
after persist: state=MANAGED, id=7
    SQL> -- transaction committed (COMMIT)
--- modification of the price
    SQL> -- start of transaction
session modified: true, original price=100, current price=110.0
--- commit
    SQL> update articles
    SQL> set currentStock=?, minimumStock=?, name=?, price=?
    SQL> where id=?
    SQL> -- parameter 1 = 10
    SQL> -- parameter 2 = 1
    SQL> -- parameter 3 = x
    SQL> -- parameter 4 = 110.0
    SQL> -- parameter 5 = 7
    SQL> -- transaction committed (COMMIT)
after commit: session modified: false
--- remove
    SQL> -- start of transaction
before commit: state=DELETED
    SQL> delete from articles
    SQL> where id=?
    SQL> -- parameter 1 = 7
    SQL> -- transaction committed (COMMIT)
after commit: state=DETACHED
--- detach and merge
    SQL> select a1_0.id, a1_0.currentStock, a1_0.minimumStock, a1_0.name, a1_0.price
    SQL> from articles a1_0
    SQL> where a1_0.id=?
    SQL> -- parameter 1 = 3
after detach: state=DETACHED
    SQL> -- start of transaction
    SQL> select a1_0.id, a1_0.currentStock, a1_0.minimumStock, a1_0.name, a1_0.price
    SQL> from articles a1_0
    SQL> where a1_0.id=?
    SQL> -- parameter 1 = 3
merge: same object=false, state of the returned object=MANAGED
    SQL> update articles
    SQL> set currentStock=?, minimumStock=?, name=?, price=?
    SQL> where id=?
    SQL> -- parameter 1 = 4
    SQL> -- parameter 2 = 1
    SQL> -- parameter 3 = bow
    SQL> -- parameter 4 = 550
    SQL> -- parameter 5 = 3
    SQL> -- transaction committed (COMMIT)
--- the tracked entities
articles.Article #1 MANAGED
    currentStock : 9 (modified, original value: 10)
    minimumStock : 5
    name : bike
    price : 500.00
articles.Article #3 MANAGED
    currentStock : 4
    minimumStock : 1
    name : bow
    price : 550
session modified: true

说明:

  • 第 17 行:[session.find(Article::class.java, 1)] 搜索主键为 1 的记录。如果该键不存在,它返回 [null] ;随后运算符 [?:] 会抛出异常([error],第 3 章),而 [bike] 的类型是 [Article],它是不可空的。生成的 SQL(结果的第 3–6 行)是一条参数化的 [SELECT],其参数被设为 1:紧凑日志现在会显示参数值;
  • 第 20 行:对 [find(Article::class.java, 1)] 的第二次调用不会发送任何 SQL 命令,并返回同一个对象(第 9 行)。[===] 运算符比较引用(即 Java 的 [] 运算符),而 [] 会调用 [equals] (第 3 章)。会话把它读取或保存的实体存储在它的 持久化上下文——也称为 一级缓存中:在查询数据库之前,[find] 会先检查所请求的实体是否已在其中。一个会话中绝不会有两个对象对应数据库中的同一行;
  • 第 25–29 行:添加一件商品。在 [persist] 之前,该对象是 [TRANSIENT] (“瞬时的”):会话不认识它,它的标识符是 [null] (第 12 行)。[persist] 把它纳入会话,会话立即执行命令 [INSERT] (第 13–18 行)以获得生成的键,并把它放入字段 [id] 中(Hibernate 直接写入该字段:属性的 protected 修饰符并不妨碍这一点)。此后该商品是 [MANAGED] (“受管的”或“持久的”),其标识符为 7(第 19 行)。事务在 [inTransaction] 代码块开始时打开,在结束时提交(结果的第 11 行和第 20 行)。代码块的参数([Transaction])没有被使用:它没有命名;
  • 第 35 行:要修改数据库中的某一行,只需修改对象即可。不需要 [update] 方法:会话保留了所读取或保存的值的一份副本(原始状态),并把当前值与之比较。这被 称为 “脏检查”(dirty checking)。这里 Kotlin 把 [*=] 运算符翻译为 [x.price = x.price * BigDecimal("1.1")]:一个新的 [BigDecimal] 对象(它是不可变的)被赋给该属性;
  • 第 36–37 行:属性 [isDirty] (即 Java 方法 [isDirty()])表示会话中是否包含尚未提交到数据库的更改:这里是的(第 23 行)。函数 [originalValue] (第 84–85 行)从持久化上下文中读取价格的原始值 100,而当前值是 110.0;
  • 第 38 行:代码块结束。随后的 [commit] 使会话与数据库同步(“刷新”,flush):执行 [UPDATE] 命令(第 25–32 行),然后提交事务。此后,会话没有待处理的更改(第 34 行);
  • 请注意,[UPDATE] 命令会写入表中的 所有 列,而不仅仅是发生变化的那一列。这是 Hibernate 的默认行为:所有商品的修改都使用同一条一次性预先准备好的 SQL 命令。相比之下,放在实体上的 [@DynamicUpdate] 注解会指示它每次生成仅限于被修改列的查询;
  • 第 45–48 行:删除。[remove] 把商品的状态改为 [DELETED] (第 37 行);[commit] 发送命令 [DELETE] (第 38–40 行)。此后会话不再识别该对象:它变成 [DETACHED] (“游离的”,第 42 行);
  • 第 52–55 行:读取弓(第 44–47 行),然后通过 [detach] 使其脱离会话:会话忘记了它(第 48 行)。此后对其价格的任何更改都会被忽略。游离对象在应用程序中很常见:它是由现已关闭的会话读取的对象——例如在先前的 HTTP 查询期间——随后由用户修改;
  • 第 57 行:[session.merge(bow)] 把游离对象合并到会话中。会话从数据库读取该商品(第 50–53 行),把游离对象的状态复制到它所管理的实体中,并返回后者:这不是同一个对象(第 54 行)。传给 [merge] 的对象仍然是游离的;返回的对象才是接下来必须使用的。[commit] 记录新的价格(第 55–62 行);
  • 第 64 行:更新自行车的库存,不使用事务;
  • 第 71–72 行:会话的持久化上下文,通过 扩展属性获得:在接下来的函数中,[trackingContext] 被当作会话的属性。[unwrap] 提供对会话内部接口 [SessionImplementor] 的访问;
  • 第 75–80 行:商品的状态,由不带参数的 [when] 计算。首先,使用 [isEntryFor] 检查会话是否与该商品相关联:[getEntry] 方法对未知对象返回 [null] (Java 代码正是据此测试的),但在 Hibernate 中它仍被标注为 [@NonNull] 。Kotlin 会考虑 Java 库中的这些可空性注解:它认为 [getEntry] 返回不可空的 [EntityEntry] ,并把对其结果使用 [?.] 的检查(“[unnecessary safe call on a non-null receiver of type 'EntityEntry'.]”)标记为不必要(这是一个警告,因而在我们的编译选项下就是错误)。这种情况虽然罕见,但很有启发性:Java 库中的类型始终恰好是其注解所规定的那样;
  • 第 88–101 行:显示持久化上下文。对每个被跟踪的实体([EntityEntry]),显示其名称、标识符和状态,随后是每个属性的当前值,以及原始值(如果不同)。[EntityPersister] 对象是 Hibernate 中了解实体与其表之间映射的对象:它提供属性的名称及其值。[for ((entity, entry) in ...)] 循环解包数组的每个元素,即一个 [Map.Entry] (第 5 章);[forEachIndexed] 遍历属性名称及其索引。两个值(可以是 [==])之间的 [null]——运算符取代了 Java 的 [Objects.equals]。在扩展函数中,[isDirty] 指的是接收者(即会话)的属性;
  • 结果的第 65–75 行:会话跟踪着自行车(其库存已从 10 变为 9)和弓。对自行车的更改没有被保存:会话是在未同步的情况下关闭的。这里没有 [commit],而会话在关闭时不会自动同步。

11.5.2. 实体的状态

相对于会话而言,实体处于以下状态之一(Jakarta Persistence 将它们称为“新建”、“受管”、“游离”和“已移除”):

状态
含义
瞬时([TRANSIENT])
该对象由构造函数调用创建,从未被登记过:它没有标识符,也没有任何会话知道它
受管([MANAGED])
该对象已被会话读取或保存,会话正在跟踪它:对它所做的更改将在下一次同步时反映到数据库中
已删除([DELETED])
该对象已被标记为删除([remove]):下一次同步将发送命令 [DELETE]
游离([DETACHED])
该对象对应数据库中的一行,但读取它的会话已关闭,或者已忘记它([detach]、[clear]):除非把它合并到某个会话中([merge]),否则它的更改会被忽略

同步 (“刷新”,flushing)会话会向 DBMS 发送 SQL 命令,把对受管实体所做的更改传播出去。这发生在:

  • 事务的 [commit] 阶段 ;
  • 执行某个结果可能依赖于尚未提交的更改的查询之前([FlushMode.AUTO] 模式,即默认模式):这样查询就能看到会话中的数据;
  • 显式调用 [session.flush()] 时。此时命令会被执行,但要等到事务 [commit] 时才会被永久保存。

下面概述使用 Hibernate 的工作流程:我们打开一个会话和一个事务,读取实体,把它们当作普通对象来修改,添加它们([persist]),删除它们([remove]),然后提交事务,它会把所有必要的命令一次性成批发送给数据库。会话充当“工作单元”。它是一个为短生命周期而设计的轻量级对象:一个工作单元,例如 Web 应用程序中的一次 HTTP 请求。你不会在应用程序的整个生命周期中使用同一个会话——否则它会在其持久化上下文中累积被跟踪的实体。

在 Kotlin 中,这个周期自然地通过 Hibernate 的高阶函数来实现:[sessionFactory.inTransaction { session -> ... }] 用于完整的工作单元(会话和事务),[sessionFactory.fromTransaction { session -> ... }] 用于需要返回结果的情形,而 [session.inTransaction { ... }] 用于在已经打开的会话内执行事务。简而言之,它们相当于用于事务的 [use] 函数。

11.6. HQL 查询

11.6.1. HQL 与 JPQL

要通过主键以外的方式检索实体,查询要用一种类似 SQL 的语言来编写,但它引用的是实体和属性,而不是表和列:HQL (Hibernate Query Language,Hibernate 查询语言)。Jakarta Persistence 定义了一种类似的语言 JPQL (Jakarta Persistence Query Language),HQL 是它的超集:JPQL 查询也是有效的 HQL 查询。Hibernate 把查询转换为 DBMS 方言的 SQL,由 DBMS 执行它。

与 SQL 的一些差异:

  • 我们使用实体名([Article]),而不是表名([articles]),使用属性名([currentStock]),而不是列名。实体名和属性名区分大小写,与 Kotlin 中一样。对于我们的 Kotlin 实体,属性名与 Kotlin 属性的名称相同(Hibernate 访问的是存储它的字段,而该字段以属性命名);
  • 子句 [select] 在 HQL 中是可选的:[from Article] 返回实体 [Article]。JPQL 则要求写成 [select a from Article a];
  • 实体之间的关系通过点号来遍历([p.category.name]),连接由 Hibernate 自己编写,我们稍后会看到。

查询由会话的 [createSelectionQuery] 方法创建,该方法接收 HQL 文本和结果类型([Article::class.java],即实体的 Java 类),并返回一个 [SelectionQuery<T>] 对象。然后可以为其参数赋值,并通过 [getResultList] (返回列表)、[getSingleResult] (返回单个结果;结果为零个或多个时抛出异常)、[getSingleResultOrNull] (没有结果时返回 [null] )或 [getResultStream](返回流)来执行它。与所有 Java 类一样,Kotlin 允许把这些无参数的 [getXxx] 方法写成属性:[query.resultList]、[query.singleResult]、[query.singleResultOrNull]。Jakarta Persistence 的 [createQuery] 方法同样存在,它既用于读取查询,也用于更新。

11.6.2. 程序 [hql]

子项目 [hql] 提供了若干查询示例。它只有一个依赖:[articles] 库(提供 Hibernate、MySQL 驱动和精简的 SQL 日志);它不定义任何实体,因此既不需要 [jpa] 插件,也不需要 [allopen] 插件:

// HQL / JPQL 查询
plugins {
    kotlin("jvm")
    // 没有 [jpa] 或 [allopen] 插件:这里没有实体(Article 在 [articles] 中编译)
    application
}

repositories {
    mavenCentral()
}

dependencies {
    // [Article] 实体和 [hbarticles] 数据库(包含 Hibernate、MySQL 和 SQL 日志)
    implementation(project(":articles"))
}

kotlin {
    jvmToolchain(25)
    compilerOptions {
        allWarningsAsErrors = true
        javaParameters = true
    }
}

application {
    // 由 [gradlew -q :hql:run] 运行的程序
    mainClass = "hql.MainKt"
}

// 在 Windows 上,由 Gradle(run、bootRun 等)启动的程序的屏幕输出以 UTF-8 编码,
// 否则带重音符号的字符在 IntelliJ IDEA 控制台或终端中会出现乱码
tasks.withType<JavaExec>().configureEach {
    jvmArgs("-Dstdout.encoding=UTF-8", "-Dstderr.encoding=UTF-8")
}

程序:

package hql

import articles.Article
import articles.BaseArticles
import org.hibernate.query.SemanticException
import java.math.BigDecimal

// 针对 [articles] 表的 HQL / JPQL 查询

// 一个投影:商品名称及其库存值(一个数据类,不是实体)
data class StockValue(val name: String, val value: BigDecimal)

// 一条用 Kotlin 编写的业务规则(一个扩展函数):
// 如果商品的库存低于最低库存,则该商品缺货
fun Article.isOutOfStock() = currentStock < minimumStock

fun main() {
    BaseArticles.createSessionFactory().use { sessionFactory ->
        // [articles] 表被重新创建,含六件商品
        BaseArticles.initialize(sessionFactory)
        sessionFactory.openSession().use { session ->
            // 1 - 过滤和排序
            println("--- the articles to restock, in alphabetical order")
            val hql = "from Article where currentStock < minimumStock order by name"
            val toOrder = session.createSelectionQuery(hql, Article::class.java).resultList
            toOrder.forEach(::println)

            // 2 - 投影:只请求有用的列
            println("--- value of the stock of each article")
            val values = session
                .createSelectionQuery(
                    """
                    select name, price * currentStock from Article
                    order by price * currentStock desc""", StockValue::class.java
                )
                .resultList
            for ((name, value) in values) {
                println("%s : %.2f euros".format(name, value))
            }

            // 3 - 单个结果;值 [minPrice] 通过命名参数传入
            println("--- the first article over 200 euros")
            val minPrice = BigDecimal(200)
            val article: Article? = session
                .createSelectionQuery(
                    """
                    select a from Article a
                    where a.price > :minPrice order by a.price""", Article::class.java
                )
                .setParameter("minPrice", minPrice)
                .setMaxResults(1)
                .singleResultOrNull
            println(article ?: "none")

            // 4 - 聚合:计算由 DBMS 完成
            println("--- aggregates")
            val nbArticles = session
                .createSelectionQuery("select count(*) from Article", Long::class.java)
                .singleResult
            val stockValue = session
                .createSelectionQuery("select sum(price * currentStock) from Article", BigDecimal::class.java)
                .singleResult
            println("%d articles, value of the stock: %.2f euros".format(nbArticles, stockValue))

            // 5 - like 和 in;用 Kotlin 列表作为参数的值
            println("--- like and in")
            val names = listOf("bow", "pump", "racket")
            val results = session
                .createSelectionQuery(
                    """
                    select name from Article
                    where name like 'b%' or name in :names""", String::class.java
                )
                .setParameter("names", names)
                .resultList
            println(results.joinToString(", "))

            // 6 - 分页:按价格升序,每页两件商品的第三页
            println("--- pagination")
            val pageSize = 2
            val pageNumber = 3
            val page = session.createSelectionQuery("from Article order by price", Article::class.java)
                .setFirstResult((pageNumber - 1) * pageSize)
                .setMaxResults(pageSize)
                .resultList
            val text = page.joinToString(", ") { "%s (%.2f euros)".format(it.name, it.price) }
            println("page $pageNumber : $text")

            // 7 - 不正确的查询在创建时就被拒绝,不必等到执行
            println("--- incorrect query")
            try {
                session.createSelectionQuery("from Article where stock < minimumStock", Article::class.java)
            } catch (e: SemanticException) {
                println("${e.javaClass.simpleName} : ${e.message}")
            }

            // 8 - 用 Kotlin 编写的规则无法转换为 SQL:在内存中过滤
            println("--- in-memory filtering")
            session.createSelectionQuery("from Article", Article::class.java).resultStream.use { stream ->
                stream.filter { it.isOutOfStock() }.forEach(::println)
            }
        }
    }
}

结果:

> gradlew -q :hql:run
--- the articles to restock, in alphabetical order
    SQL> select a1_0.id, a1_0.currentStock, a1_0.minimumStock, a1_0.name, a1_0.price
    SQL> from articles a1_0
    SQL> where a1_0.currentStock<a1_0.minimumStock
    SQL> order by a1_0.name
[4, arrows - set of 6, 100.00, 12, 20]
--- value of the stock of each article
    SQL> select a1_0.name, (a1_0.price*a1_0.currentStock)
    SQL> from articles a1_0
    SQL> order by (a1_0.price*a1_0.currentStock) desc
bike : 5000.00 euros
bow : 2400.00 euros
diving suit : 2400.00 euros
arrows - set of 6 : 1200.00 euros
diver's oxygen tanks : 1200.00 euros
pump : 100.00 euros
--- the first article over 200 euros
    SQL> select a1_0.id, a1_0.currentStock, a1_0.minimumStock, a1_0.name, a1_0.price
    SQL> from articles a1_0
    SQL> where a1_0.price>?
    SQL> order by a1_0.price
    SQL> limit ?
    SQL> -- parameter 1 = 200
    SQL> -- parameter 2 = 1
[5, diving suit, 300.00, 8, 2]
--- aggregates
    SQL> select count(*)
    SQL> from articles a1_0
    SQL> select sum((a1_0.price*a1_0.currentStock))
    SQL> from articles a1_0
6 articles, value of the stock: 12300.00 euros
--- like and in
    SQL> select a1_0.name
    SQL> from articles a1_0
    SQL> where a1_0.name like 'b%' escape '' or a1_0.name in (?, ?, ?)
    SQL> -- parameter 1 = bow
    SQL> -- parameter 2 = pump
    SQL> -- parameter 3 = racket
bike, bow, pump
--- pagination
    SQL> select a1_0.id, a1_0.currentStock, a1_0.minimumStock, a1_0.name, a1_0.price
    SQL> from articles a1_0
    SQL> order by a1_0.price
    SQL> limit ?, ?
    SQL> -- parameter 1 = 4
    SQL> -- parameter 2 = 2
page 3 : bike (500.00 euros), bow (600.00 euros)
--- incorrect query
SemanticException : Could not interpret path expression 'stock'
--- in-memory filtering
    SQL> select a1_0.id, a1_0.currentStock, a1_0.minimumStock, a1_0.name, a1_0.price
    SQL> from articles a1_0
[4, arrows - set of 6, 100.00, 12, 20]

说明:

  • 第 24–26 行:[where] 子句比较实体的两个属性;[order by] 子句按名称排序:它们会变成 SQL 命令中的 [WHERE] 和 [ORDER BY] 子句。查询由 [resultList] (即 [getResultList] 方法)执行,它返回一个 [List<Article>];[forEach(::println)] 通过各元素的 [toString] 方法显示每个元素;
  • 第 30–38 行:一个 投影。该查询返回的不是实体,而是每项两个值:名称和库存价值。生成的 SQL 只取回必要的列,并自行完成计算。结果类型是第 11 行的数据类 [StockValue]:Hibernate 为每一行创建一个对象,按顺序把 [select] 子句中的值传给它的构造函数(Java 课程中使用的是记录)。这些对象不是实体:会话不会跟踪它们。数据类非常适合这个角色,我们还利用了它的 解构:[for ((name, value) in values)] (第 37 行);
  • 第 32–34 行:查询写在 原始字符串 (["""..."""],第 5 章)中,比写在单行里的长字符串更易读。与 Java 文本块不同,原始字符串会保留各行的缩进以及 开头的换行;这在这里无关紧要,因为空格和换行在 HQL 中不起作用:无需调用 [trimIndent];
  • 第 44–53 行:以 JPQL 的方式编写的查询,带有别名([a])。[:minPrice] 是一个 命名参数,其值由 [setParameter] 给出。它会变成 SQL 命令的一个参数([?] 位于 [WHERE] 子句中,其值由日志显示):因此无需担心 SQL 注入,因为值是与命令文本分开传递的。这正是第 10 章对预处理语句应用的规则。[setMaxResults(1)] 把结果限制为一行:即 MySQL 的 [LIMIT] 子句。[singleResultOrNull] 返回一个 [Article?]:可空类型清楚地表明可能没有结果,而 Elvis 运算符 [?:] 在这种情况下显示 [none] ;
  • 必须强调 Kotlin 特有的一个陷阱。它的 字符串模板 使人极易写出 ["... where a.price > $minPrice"]。程序能够运行,但值会被复制进查询文本:正是这种拼接为注入打开了大门(第 10 章),而且 Hibernate 还得为每个值解析一条新的查询。我们 绝不 使用字符 [$] 在 HQL 查询中设置值:值要通过命名参数传递。直接写在查询文本中的字面值(例如第 72 行的 ['b%'] )同样会被复制到 SQL 命令的文本中,日志中可以看到:对于程序常量这是可以接受的,但对于来自外部的值则绝对不行;
  • 第 57–63 行:聚合函数 [count] 和 [sum] 由 DBMS 计算:传输的只有结果,而不是各行数据。[Long::class.java] 指的是 Java 中基本类型 [long] 的类(Kotlin 类型 [Long] 会被编译为 [long]),而 Java 课程使用的是 [Long.class],即包装类 [java.lang.Long];Hibernate 两者都接受(包装类应写成 [Long::class.javaObjectType])。HQL 还支持 [avg]、[min]、[max],以及 [group by] 和 [having] 子句;
  • 第 67–76 行:SQL 的 [like] 运算符,以及 [in] 运算符,其操作数是一个接受 Kotlin 列表的参数(Kotlin 的 [List] 就是 Hibernate 的 [java.util.List]):Hibernate 会把它展开为与列表元素数量相同的 SQL 参数。HQL 支持大量针对字符串([upper]、[length]、[substring]……)、日期和数字的函数,并把它们翻译成 DBMS 的方言;
  • 第 82–85 行:分页,用于逐页显示很长的列表。[setFirstResult] 跳过前面各页的条目,而 [setMaxResults] 保留所请求页的条目:即 MySQL 的 [LIMIT ?, ?] 子句,其两个参数为 4 和 2。分页只有在已排序的列表上才有意义([order by])。第 86–87 行使用 [joinToString] 及其转换函数构造页面显示(第 5 章);
  • 第 91–94 行:查询使用了一个不存在的 [stock] 属性。错误在创建查询时就被检测到,早于任何执行,因为 Hibernate 会解析 HQL 文本并将其与模型比较:它抛出 [SemanticException] (Hibernate 的消息是英文的)。语法错误则会导致 [SyntaxException]。请注意,[createSelectionQuery] 返回的值被忽略了:在 Kotlin 中,不要求必须使用函数的结果;
  • 第 15 行和第 99–100 行:查询不能使用 Kotlin 函数,例如扩展函数 [isOutOfStock]:Hibernate 不知道它的代码,即使知道,也不一定知道如何把它写成 SQL。可以读取所有实体并在内存中过滤:[resultStream] ([getResultStream] 方法)返回一个 Java 的 [Stream<Article>],它会保持一个 JDBC 资源处于打开状态,使用后必须关闭:[use] 函数负责处理这一点,因为 [Stream] 是 一个 [AutoCloseable]。结果是正确的,但整张表都被传输了(最后一条 SQL 命令没有 [WHERE] 子句):对于大表,应当避免这样做。更好的做法是把条件写在查询中,如第 24 行所示。该扩展函数也展示了一种非常“Kotlin 风格”的做法:无需修改实体的类,就能为实体写一条业务规则(第 4 章)。

11.6.3. 命名查询与编译期验证

写在字符串中的查询只在运行时才被解析。有两种方法可以更早地发现错误:

  • 命名查询:应用于实体的 [@NamedQuery(name = "Article.outOfStock", query = "from Article where currentStock < minimumStock")] 注解声明一个查询,Hibernate 在启动时、创建 [SessionFactory] 时解析它。随后通过名称执行它:[session.createNamedSelectionQuery("Article.outOfStock", Article::class.java)]。它在 Kotlin 中的写法与 Java 完全相同;该注解是可重复的:有多少个查询要声明,就应用多少次;
  • Hibernate 注解处理器 (“Hibernate Processor”,库 [org.hibernate.orm:hibernate-processor])。在 Java 中,它由 [javac] 在编译期间执行:它检查注解中的查询,并为每个实体生成一个“元模型”类([Article_] 对应 [Article]),我们将在 Criteria API 中再次看到它。这个机制并不只适用于 Kotlin:我们在下面讨论静态元模型时会回过头来说明。

11.7. Criteria API

11.7.1. 用代码构建查询

HQL 查询是一个字符串,可以通过拼接来构造(在 Kotlin 中也可以使用模板):一旦查询依赖于许多可选条件(例如搜索表单),这种做法就既不可靠又难以阅读。Jakarta Persistence 提供了另一种编写查询的方式:Criteria API,其中查询是一棵通过方法调用构建的对象树。Hibernate 会把这棵树翻译成 SQL,就像处理 HQL 查询一样(它也会把 HQL 翻译成这样一棵树)。子项目 [criteria] (其 [build.gradle.kts] 与子项目 [hql] 的相同,只是程序名称不同)包含了上一个程序中的若干查询:

package criteria

import articles.Article
import articles.BaseArticles
import jakarta.persistence.criteria.Path
import jakarta.persistence.criteria.Predicate
import org.hibernate.Session
import java.math.BigDecimal
import kotlin.reflect.KProperty1

// 用 Criteria API 构建的查询

// 一个投影:商品名称及其库存值
data class StockValue(val name: String, val value: BigDecimal)

// 用属性引用(Article::price)而不是字符串("price")指定的属性:
// 名称由编译器检查,并且返回路径的类型就是该属性的类型
fun <X, T> Path<X>.get(property: KProperty1<X, T>): Path<T> = get(property.name)

fun main() {
    BaseArticles.createSessionFactory().use { sessionFactory ->
        // [articles] 表被重新创建,含六件商品
        BaseArticles.initialize(sessionFactory)
        sessionFactory.openSession().use { session ->
            // 查询元素的工厂
            val cb = session.criteriaBuilder

            // 1 - 过滤和排序;属性用字符串指定
            println("--- the articles to restock, in alphabetical order")
            val query = cb.createQuery(Article::class.java)
            val a = query.from(Article::class.java)
            query.select(a)
                .where(cb.lt(a.get<Int>("currentStock"), a.get<Int>("minimumStock")))
                .orderBy(cb.asc(a.get<String>("name")))
            session.createSelectionQuery(query).resultList.forEach(::println)

            // 2 - 投影到数据类;属性用引用指定
            println("--- value of the stock of each article")
            val projection = cb.createQuery(StockValue::class.java)
            val p = projection.from(Article::class.java)
            val value = cb.prod(p.get(Article::price), p.get(Article::currentStock))
                .`as`(BigDecimal::class.java)
            projection.select(cb.construct(StockValue::class.java, p.get(Article::name), value))
                .orderBy(cb.desc(value))
            for ((name, v) in session.createSelectionQuery(projection).resultList) {
                println("%s : %.2f euros".format(name, v))
            }

            // 3 - 根据所提供的条件构建的查询
            println("--- search: maximum price 150 euros")
            search(session, maxPrice = BigDecimal(150)).forEach(::println)
            println("--- search: maximum price 150 euros and name starting with [d]")
            search(session, maxPrice = BigDecimal(150), nameStart = "d").forEach(::println)

            // 4 - 聚合
            println("--- aggregates")
            val count = cb.createQuery(Long::class.java)
            count.select(cb.count(count.from(Article::class.java)))
            val nbArticles = session.createSelectionQuery(count).singleResult
            val sum = cb.createQuery(BigDecimal::class.java)
            val s = sum.from(Article::class.java)
            val articleValue = cb.prod(s.get(Article::price), s.get(Article::currentStock))
                .`as`(BigDecimal::class.java)
            sum.select(cb.sum(articleValue))
            val stockValue = session.createSelectionQuery(sum).singleResult
            println("%d articles, value of the stock: %.2f euros".format(nbArticles, stockValue))
        }
    }
}

// 价格不超过 [maxPrice] 且名称以 [nameStart] 开头的商品,
// 每个条件只在不为 null 时才使用
fun search(session: Session, maxPrice: BigDecimal? = null, nameStart: String? = null): List<Article> {
    val cb = session.criteriaBuilder
    val query = cb.createQuery(Article::class.java)
    val a = query.from(Article::class.java)
    // 条件,逐个添加
    val conditions = buildList<Predicate> {
        maxPrice?.let { add(cb.le(a.get(Article::price), it)) }
        nameStart?.let { add(cb.like(a.get(Article::name), "$it%")) }
    }
    query.select(a).where(conditions).orderBy(cb.asc(a.get(Article::price)))
    return session.createSelectionQuery(query).resultList
}

结果:

> gradlew -q :criteria:run
--- the articles to restock, in alphabetical order
    SQL> select a1_0.id, a1_0.currentStock, a1_0.minimumStock, a1_0.name, a1_0.price
    SQL> from articles a1_0
    SQL> where a1_0.currentStock<a1_0.minimumStock
    SQL> order by a1_0.name
[4, arrows - set of 6, 100.00, 12, 20]
--- value of the stock of each article
    SQL> select a1_0.name, (a1_0.price*a1_0.currentStock)
    SQL> from articles a1_0
    SQL> order by (a1_0.price*a1_0.currentStock) desc
bike : 5000.00 euros
bow : 2400.00 euros
diving suit : 2400.00 euros
arrows - set of 6 : 1200.00 euros
diver's oxygen tanks : 1200.00 euros
pump : 100.00 euros
--- search: maximum price 150 euros
    SQL> select a1_0.id, a1_0.currentStock, a1_0.minimumStock, a1_0.name, a1_0.price
    SQL> from articles a1_0
    SQL> where a1_0.price<=?
    SQL> order by a1_0.price
    SQL> -- parameter 1 = 150
[2, pump, 10.00, 10, 2]
[4, arrows - set of 6, 100.00, 12, 20]
[6, diver's oxygen tanks, 120.00, 10, 5]
--- search: maximum price 150 euros and name starting with [d]
    SQL> select a1_0.id, a1_0.currentStock, a1_0.minimumStock, a1_0.name, a1_0.price
    SQL> from articles a1_0
    SQL> where a1_0.price<=? and a1_0.name like ? escape ''
    SQL> order by a1_0.price
    SQL> -- parameter 1 = 150
    SQL> -- parameter 2 = d%
[6, diver's oxygen tanks, 120.00, 10, 5]
--- aggregates
    SQL> select count(a1_0.id)
    SQL> from articles a1_0
    SQL> select sum((a1_0.price*a1_0.currentStock))
    SQL> from articles a1_0
6 articles, value of the stock: 12300.00 euros

说明:

  • 第 26 行:会话返回一个 [HibernateCriteriaBuilder] ([criteriaBuilder],即 [getCriteriaBuilder] 方法),它是 Jakarta Persistence 的 [CriteriaBuilder] 的 Hibernate 增强版:它是查询所有元素(条件、表达式、排序)的工厂;
  • 第 30–34 行:第一个示例中的查询,用 HQL 表示。[createQuery(Article::class.java)] 创建一个返回商品的查询;[from(Article::class.java)] 声明被查询的实体并返回其根([Root<Article>]),它相当于 [from Article a] 中的别名 [a];[a.get<Int>("currentStock")] 指定一个属性。条件由 [cb.lt(x, y)] (“less than”,即 [x < y])构造,排序由 [cb.asc(...)] 构造。显式类型参数 [<Int>] (在 Java 中为 [a.<Integer>get(...)])指定属性的类型,而这无法从字符串 ["currentStock"] 中确定。编译器无法验证它是否正确:它只能相信我们;
  • 第 35 行:查询由会话执行,与 HQL 查询一样。生成的 SQL 与 HQL 查询的相同;
  • 第 18 行:Jakarta Persistence 接口 [Path] 的一个 扩展函数,它使用 属性引用 ([Article::price],类型为 [KProperty1<Article, BigDecimal>],第 7 章)而不是字符串来引用属性。它只是把属性名([property.name],这里是 ["price"])传给原始的 [get] 方法,但它提供了两项保证:编译器会验证该属性存在,并且返回路径的类型([Path<BigDecimal>])可由属性的类型推断出来,无需显式类型参数。这依赖于 JPA 属性名与 Kotlin 属性名相同这一事实,我们的实体正是如此;
  • 第 39–46 行:使用扩展函数向数据类 [StockValue] 进行投影:[p.get(Article::price)]。[cb.prod(x, y)] 是两个表达式的乘积;[as(BigDecimal::class.java)] 指定结果类型([as] 是 Kotlin 关键字:要调用同名的 Java 方法,需要用反引号括起来);[cb.construct(StockValue::class.java, ...)] 表示结果的每一行都必须传给数据类的构造函数;
  • 第 73–83 行:这是 Criteria API 最有用的地方。[search] 函数根据所提供的条件构造查询。它的条件是 可空 参数,带有默认值 ([maxPrice: BigDecimal? = null]),这使得第 51 行和第 53 行可以使用命名参数调用(在 Java 中,必须显式传入 [null])。条件列表由 [buildList] 构造:只有当对应的条件不是 [null] 时([maxPrice?.let { ... \}]),才会把每个条件加入其中,而 [where] 子句接收整个列表([where(conditions)],这是 Jakarta Persistence 3.2 引入的重载),各条件通过 [and] 组合。第一次调用生成带一个条件的查询;第二次调用生成带两个条件的查询。请注意,使用 Criteria API 时,Hibernate 把这些值([150]、[d%])作为参数放入 SQL 命令中:第 80 行的模板 ["$it%"] 构造的是参数的值([like] 的模式),而不是查询文本;
  • 第 57–64 行:聚合函数 [count] 和 [sum]。

11.7.2. 静态元模型

第一个示例中查询的弱点在于属性是用字符串指定的([a.get<Int>("currentStock")]):拼写错误要到运行时才会被发现,而且编译器不了解属性的类型。为了解决这个问题,Jakarta Persistence 提供了 静态元模型:对于每个实体 [Article],都有一个类 [Article_] ,其中每个属性对应一个字段,描述其名称和类型。在 Java 中,随后可以写成 ***[cb.lt(a.get(Article\_.currentStock), a.get(Article\_.minimumStock))]***,编译器会对其进行完整验证。这些类不是手写的:它们是在编译期间由 Hibernate 的注解处理器生成的。在使用 Criteria API 的 Java 项目中,这是推荐的做法。

在 Kotlin 中,事情没有这么简单。Hibernate 注解处理器是一个 Java 注解处理器:它由 [javac] 在 Java 源代码上执行,而我们的实体是由 Kotlin 编译器编译的。Kotlin 中用于这类代码生成的工具 是 KSP (Kotlin Symbol Processing),但 Hibernate 并未提供 KSP 处理器。剩下的是 kapt (“Kotlin annotation processing tool”),它在由 Kotlin 代码生成的“存根”上运行 Java 处理器;然而,kapt 在 JetBrains 处于维护模式(JetBrains 推荐 KSP),它会拖慢编译,而且 kapt + Hibernate Processor 的组合并不是 Hibernate 文档所记载的配置。因此,我们不使用它。Kotlin 的属性引用无需任何工具就能带来大部分好处:借助程序中的扩展函数,拼写错误会在编译时被检测到。下面是编译器对 [a.get(Article::stock)](编译到一个测试文件中)给出的信息:

1
2
3
Typo.kt:9:50: error: unresolved reference 'stock'.
fun condition(a: Path<Article>) = a.get(Article::stock)
                                                 ^^^^^

(编译器此前还会显示候选 [get] 方法的列表,其中没有一个合适。)不过,这种检查并不全面:不是持久化属性的 Kotlin 属性(例如计算属性)会被编译器接受,但在运行时被 Hibernate 拒绝。

对于固定的查询,HQL 比 Criteria API 更易读;对于根据具体情况构造的查询,Criteria API 更安全。两者可以结合使用:Hibernate 允许由 HQL 字符串([cb.createQuery(hql, Article::class.java)])创建 Criteria 查询,然后再用代码对其进行补充。

11.8. 关系

11.8.1. 商店模型

数据库中的表彼此关联。Hibernate 把这些关联表示为 关联:即引用另一个实体或实体集合的属性。[relations] 子项目使用一个 [hbshop] 数据库,它描述了一家拥有六个实体的小商店。由于它定义了实体,其 [build.gradle.kts] 应用了 [jpa] 和 [allopen] 插件,就像 [articles] 库中的那样;它直接依赖 [tools] 库(SQL 日志)、Hibernate 和 MySQL 驱动:

// 实体之间的关系:[hbshop] 数据库
plugins {
    kotlin("jvm")
    // 实体的无参构造函数(为 JPA 配置的 "no-arg" 插件)
    kotlin("plugin.jpa")
    // 实体和属性被设为 open(非 final):Hibernate 可以从中派生代理
    kotlin("plugin.allopen")
    application
}

repositories {
    mavenCentral()
}

dependencies {
    // 紧凑的 SQL 日志(以及 Logback)
    implementation(project(":tools"))
    // Hibernate 和 MySQL JDBC 驱动
    implementation("org.hibernate.orm:hibernate-core:7.4.5.Final")
    runtimeOnly("com.mysql:mysql-connector-j:9.7.0")
}

// 以这种方式标注的类由 [allopen] 插件打开
allOpen {
    annotation("jakarta.persistence.Entity")
    annotation("jakarta.persistence.MappedSuperclass")
    annotation("jakarta.persistence.Embeddable")
}

kotlin {
    jvmToolchain(25)
    compilerOptions {
        allWarningsAsErrors = true
        javaParameters = true
    }
}

application {
    // 由 [gradlew -q :relations:run] 运行的程序
    mainClass = "relations.MainKt"
}

// 在 Windows 上,由 Gradle(run、bootRun 等)启动的程序的屏幕输出以 UTF-8 编码,
// 否则带重音符号的字符在 IntelliJ IDEA 控制台或终端中会出现乱码
tasks.withType<JavaExec>().configureEach {
    jvmArgs("-Dstdout.encoding=UTF-8", "-Dstderr.encoding=UTF-8")
}

类别用于对商品进行分组:

package relations

import jakarta.persistence.CascadeType
import jakarta.persistence.Column
import jakarta.persistence.Entity
import jakarta.persistence.GeneratedValue
import jakarta.persistence.GenerationType
import jakarta.persistence.Id
import jakarta.persistence.OneToMany
import jakarta.persistence.Table

// 一个类别包含多个产品(一对多关系)
@Entity
@Table(name = "categories")
class Category(
    @Column(nullable = false, length = 30)
    var name: String,
) {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    var id: Int? = null
        protected set

    // 类别的产品:关系的反向端,由 Product.category 描述
    @OneToMany(mappedBy = "category", cascade = [CascadeType.PERSIST])
    val products: MutableList<Product> = mutableListOf()

    // 添加一个产品:关系的两端都会更新
    fun add(product: Product) {
        products += product
        product.category = this
    }
}

商品属于某个类别,并带有标签:

package relations

import jakarta.persistence.CascadeType
import jakarta.persistence.Column
import jakarta.persistence.Entity
import jakarta.persistence.FetchType
import jakarta.persistence.ForeignKey
import jakarta.persistence.GeneratedValue
import jakarta.persistence.GenerationType
import jakarta.persistence.Id
import jakarta.persistence.JoinColumn
import jakarta.persistence.JoinTable
import jakarta.persistence.ManyToMany
import jakarta.persistence.ManyToOne
import jakarta.persistence.Table
import java.math.BigDecimal

// 一个产品属于一个类别并带有多个标签
@Entity
@Table(name = "products")
class Product(
    @Column(nullable = false, length = 30)
    var name: String,
    @Column(nullable = false, precision = 10, scale = 2)
    var price: BigDecimal,
    vararg tags: Tag,
) {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    var id: Int? = null
        protected set

    // 多对一关系:[products] 表的外键 [category_id]
    // [lateinit]:类别在构造之后由 Category.add 填入
    @ManyToOne(fetch = FetchType.LAZY, optional = false)
    @JoinColumn(name = "category_id", foreignKey = ForeignKey(name = "fk_products_category"))
    lateinit var category: Category
        internal set

    // 多对多关系,存储在关联表中
    @ManyToMany(cascade = [CascadeType.PERSIST])
    @JoinTable(
        name = "products_tags",
        joinColumns = [JoinColumn(name = "product_id")],
        inverseJoinColumns = [JoinColumn(name = "tag_id")],
        foreignKey = ForeignKey(name = "fk_products_tags_product"),
        inverseForeignKey = ForeignKey(name = "fk_products_tags_tag"),
    )
    val tags: MutableSet<Tag> = mutableSetOf()

    init {
        // 只填写关系的拥有端:Hibernate 保存的就是它
        this.tags += tags
    }
}

一个标签可分配给多个商品:

package relations

import jakarta.persistence.Column
import jakarta.persistence.Entity
import jakarta.persistence.GeneratedValue
import jakarta.persistence.GenerationType
import jakarta.persistence.Id
import jakarta.persistence.ManyToMany
import jakarta.persistence.Table

// 一个标签(促销、新品……)由多个产品携带
@Entity
@Table(name = "tags")
class Tag(
    @Column(nullable = false, length = 20)
    var label: String,
) {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    var id: Int? = null
        protected set

    // 关系的反向端,由 Product.tags 描述
    @ManyToMany(mappedBy = "tags")
    val products: MutableSet<Product> = mutableSetOf()
}

客户下订单:

package relations

import jakarta.persistence.CascadeType
import jakarta.persistence.Column
import jakarta.persistence.Entity
import jakarta.persistence.GeneratedValue
import jakarta.persistence.GenerationType
import jakarta.persistence.Id
import jakarta.persistence.OneToMany
import jakarta.persistence.Table

// 一个客户下订单
@Entity
@Table(name = "clients")
class Client(
    @Column(nullable = false, length = 30)
    var name: String,
) {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    var id: Int? = null
        protected set

    @OneToMany(mappedBy = "client", cascade = [CascadeType.PERSIST])
    val orders: MutableList<CustomerOrder> = mutableListOf()

    // 添加一个订单:关系的两端都会更新
    fun add(order: CustomerOrder) {
        orders += order
        order.client = this
    }
}

订单属于某个客户,并包含订单行:

package relations

import jakarta.persistence.CascadeType
import jakarta.persistence.Entity
import jakarta.persistence.FetchType
import jakarta.persistence.GeneratedValue
import jakarta.persistence.GenerationType
import jakarta.persistence.Id
import jakarta.persistence.JoinColumn
import jakarta.persistence.ManyToOne
import jakarta.persistence.OneToMany
import jakarta.persistence.Table
import java.time.LocalDate

// 一个客户的订单,由订单行组成
@Entity
@Table(name = "orders")
class CustomerOrder(
    var date: LocalDate,
) {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    var id: Int? = null
        protected set

    @ManyToOne(fetch = FetchType.LAZY, optional = false)
    @JoinColumn(name = "client_id")
    lateinit var client: Client
        internal set

    @OneToMany(mappedBy = "order", cascade = [CascadeType.PERSIST])
    val lines: MutableList<OrderLine> = mutableListOf()

    // 添加一个订单行:关系的两端都会更新
    fun add(line: OrderLine) {
        lines += line
        line.order = this
    }
}

订单行有一个 ID、一个数量和两个多对一关联——一个指向其订单,一个指向其商品:

package relations

import jakarta.persistence.Entity
import jakarta.persistence.FetchType
import jakarta.persistence.GeneratedValue
import jakarta.persistence.GenerationType
import jakarta.persistence.Id
import jakarta.persistence.JoinColumn
import jakarta.persistence.ManyToOne
import jakarta.persistence.Table

// 一个订单行:某个产品的一个数量
@Entity
@Table(name = "order_lines")
class OrderLine(
    @ManyToOne(fetch = FetchType.LAZY, optional = false)
    @JoinColumn(name = "product_id")
    var product: Product,
    var quantity: Int,
) {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    var id: Int? = null
        protected set

    @ManyToOne(fetch = FetchType.LAZY, optional = false)
    @JoinColumn(name = "order_id")
    lateinit var order: CustomerOrder
        internal set
}

它包含三种类型的关联:

  • 一个 多对一 关系([@ManyToOne]):商品属于一个类别([Product] 的 [category] 属性)。在数据库中,它由一个 外键 表示,即表 [products] 中的列 [category_id] ,其中 [@JoinColumn] 指定列名和约束名([fk_products_category])。[optional = false] 使该关系成为必需的:该列将为 [NOT NULL]。请注意 Kotlin 中嵌套注解的语法:作为参数传给另一个注解的注解不带 [@]([foreignKey = ForeignKey(name = ...)]),而注解数组写在方括号中([joinColumns = [JoinColumn(name = "product_id")]]),例如数组 [cascade = [CascadeType.PERSIST]];
  • 反向的 一对多 关系([@OneToMany]):一个类别包含多个商品([Category] 的 [products] 属性)。它不会在数据库中创建任何东西:[mappedBy = "category"] 表示它由实体 [Product] 的 [category] 属性来描述。[Product.category] 被称为关系的 拥有方,而 [Category.products] 是它的 反向方:Hibernate 保存拥有方的值。不过,双方在内存中必须保持一致:这正是 [Category] 的 [add] 函数的作用,它把商品添加到列表中([products += product],即可变集合的 [+=] 运算符,第 5 章)并设置其类别;
  • 一个 多对多 关系([@ManyToMany]):一个商品有多个标签,一个标签关联多个商品。它存储在一张 关联表 [products_tags] 中,[@JoinTable] 为它指定表名、两个列名以及两个外键的名称([Product] 的 [tags] 属性)。反向方是 [Tag.products] ([mappedBy = "tags"])。对于多对多关系,首选集合([MutableSet])而不是列表([MutableList]):使用列表时,每次修改集合,Hibernate 都会删除并重新插入关联表中的所有行;
  • [fetch = FetchType.LAZY] 要求对商品的类别进行 懒加载:只有在使用时才会读取它。这是集合([@OneToMany]、[@ManyToMany])的默认行为,但对于指向单个实体的关系([@ManyToOne])则不是,标准默认会立即加载它们([EAGER]):按照 Hibernate 文档的建议,我们系统地为它们加上 [fetch = FetchType.LAZY];
  • [cascade = [CascadeType.PERSIST]] 传播 [persist] 操作:持久化一个类别会持久化它的商品,持久化一个商品会持久化它的标签。其他值([MERGE]、[REMOVE]、[ALL]……)传播其他操作。

转到 Kotlin 有几点需要说明:

  • 集合使用 Kotlin 的 可变 接口 [MutableList] 和 [MutableSet] 来声明,并分别由 [mutableListOf()] 和 [mutableSetOf()] 初始化。这一选择是强制性的:Hibernate 会用它自己的集合([PersistentBag] 或 [PersistentSet])替换它所读取实体的集合,这是一个可变的 [java.util.List] 或 [java.util.Set],并且可以按需加载。Kotlin 的只读 [List] 会被编译器接受,但它无法准确表示一个会被 Hibernate 和 [add] 函数修改的对象。属性是 [val]:我们修改集合的内容,而从不修改引用;
  • 指向单个实体的关系(必需的)声明为 [lateinit var category: Category] (在 [Product] 中;[CustomerOrder.client] 和 [OrderLine.order] 同理)。该类型不可为空,因为已登记的商品总有一个类别;但在创建时,它还没有类别:[Category.add] 会为它赋值。[lateinit] 恰好表达了这一点:该属性将在稍后初始化,在此之前读取它会抛出 [UninitializedPropertyAccessException],这比 [NullPointerException] 更具描述性。Java 课程此前依赖的是 [null] 。我们 本来也可以写成 [var category: Category? = null],代价是每次都必须使用 [?.] 或 [!!] ;
  • 放在这些属性下面的修饰符 [internal set] 把对商品类别(订单的客户、订单的订单行)的修改保留给模块——也就是 Gradle 子项目 [relations]:只有 [add] 函数使用它。在 Java 中,[setCategory] 方法只在包内可见;Kotlin 没有“包”可见性,[internal] 是最接近的等价物;
  • 商品的标签通过 [vararg] 参数传给其构造函数,该参数不是属性(前面没有 [val] 或 [var]):它只在 [init] 块中使用,该块把它们添加到集合中。在这个块中,[tags] 指参数,而 [this.tags] 指属性;[init] 块放在属性声明之后,因为初始化按其在文本中出现的顺序执行。运算符 [+=] 把数组的所有元素添加到可变集合中;
  • 由 [jpa] 插件添加的无参构造函数(Hibernate 用它来创建所读取的实体)不会执行属性初始化:因此,由 Hibernate 读取的商品的 [tags] 集合不是由 [mutableSetOf()] 创建的。这不是问题,因为 Hibernate 自己会用其懒加载集合来填充它所读取实体的所有关联;
  • 实体仍然是普通类,而不是数据类。关系为此提供了又一个理由:为数据类生成的 [toString]、[equals]和 [hashCode] 函数都使用其主构造函数的属性;如果它们包含关联,就会遍历懒加载集合(触发查询,或在会话之外引发 [LazyInitializationException] ),而且两个相互引用的实体会无限地互相调用([StackOverflowError]);
  • 最后,[allopen] 插件在这里至关重要:对于指向单个实体的懒加载关系,Hibernate 会在属性中放入一个代理——即在运行时生成的实体子类的对象——这要求类及其访问器是非 final 的。我们将在程序中看到这个代理的实际运作。

[Shop] 对象为 [hbshop] 数据库配置 Hibernate,并在其中创建初始数据集:

package relations

import org.hibernate.SessionFactory
import org.hibernate.cfg.AvailableSettings
import org.hibernate.jpa.HibernatePersistenceConfiguration
import tools.SqlLog
import java.math.BigDecimal
import java.time.LocalDate

// [hbshop] 数据库:Hibernate 配置和第一批数据
object Shop {

    // [hbshop] 数据库及其六个实体的 SessionFactory
    fun createSessionFactory(): SessionFactory =
        HibernatePersistenceConfiguration("shop")
            .managedClasses(
                Category::class.java, Product::class.java, Tag::class.java,
                Client::class.java, CustomerOrder::class.java, OrderLine::class.java,
            )
            .jdbcUrl("jdbc:mysql://localhost:3306/hbshop?createDatabaseIfNotExist=true")
            .jdbcCredentials("root", "")
            .property(AvailableSettings.FORMAT_SQL, true)
            .createEntityManagerFactory()

    // (重新)创建表和第一批数据,不记录 SQL 日志
    fun initialize(sessionFactory: SessionFactory) = SqlLog.withoutLog {
        sessionFactory.schemaManager.drop(false)
        sessionFactory.schemaManager.create(false)
        sessionFactory.inTransaction { session ->
            // 两个标签
            val promo = Tag("promo")
            val novelty = Tag("new")
            // 三个类别及其产品:一个对象图
            val cycles = Category("cycles")
            cycles.add(Product("bike", BigDecimal(500), promo))
            val pump = Product("pump", BigDecimal(10))
            cycles.add(pump)
            val archery = Category("archery")
            val bow = Product("bow", BigDecimal(600), novelty)
            archery.add(bow)
            archery.add(Product("arrows - set of 6", BigDecimal(100), promo, novelty))
            val diving = Category("diving")
            // 持久化传播到产品和标签(级联)
            session.persist(cycles)
            session.persist(archery)
            session.persist(diving)
            // 一个客户及其含两个订单行的订单
            val order = CustomerOrder(LocalDate.of(2026, 9, 28))
            order.add(OrderLine(pump, 2))
            order.add(OrderLine(bow, 1))
            val martin = Client("Martin")
            martin.add(order)
            session.persist(martin)
        }
    }
}
  • 第 11 行:与 [BaseArticles] 一样,[object] 取代了 Java 工具类;
  • 第 16–18 行:六个实体,由 [managedClasses] 声明;
  • 第 26 行:该函数是一个表达式:即 [SqlLog.withoutLog] 的结果,向它传入的是要在不记录(SQL)日志的情况下执行的处理;
  • 第 31–42 行:一个 对象图:三个类别、它们的商品以及商品的标签;
  • 第 44–46 行:只需持久化各个类别即可:得益于级联,Hibernate 会遍历关联,并按正确的顺序(先持久化类别,再持久化引用它们的商品)持久化它所到达的所有实体,同时填充外键和关联表;
  • 第 48–53 行:一个客户、其订单及两个订单行,在一次操作中完成持久化。

Hibernate 创建的表如下:

> mysql -uroot hbshop -e "SHOW TABLES; SHOW CREATE TABLE products\G SHOW CREATE TABLE products_tags\G"
Tables_in_hbshop
categories
clients
order_lines
orders
products
products_tags
tags
*************************** 1. row ***************************
       Table: products
Create Table: CREATE TABLE `products` (
  `id` int NOT NULL AUTO_INCREMENT,
  `name` varchar(30) NOT NULL,
  `price` decimal(10,2) NOT NULL,
  `category_id` int NOT NULL,
  PRIMARY KEY (`id`),
  KEY `fk_products_category` (`category_id`),
  CONSTRAINT `fk_products_category` FOREIGN KEY (`category_id`) REFERENCES `categories` (`id`)
) ENGINE=InnoDB AUTO_INCREMENT=5 DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci
*************************** 1. row ***************************
       Table: products_tags
Create Table: CREATE TABLE `products_tags` (
  `product_id` int NOT NULL,
  `tag_id` int NOT NULL,
  PRIMARY KEY (`product_id`,`tag_id`),
  KEY `fk_products_tags_tag` (`tag_id`),
  CONSTRAINT `fk_products_tags_product` FOREIGN KEY (`product_id`) REFERENCES `products` (`id`),
  CONSTRAINT `fk_products_tags_tag` FOREIGN KEY (`tag_id`) REFERENCES `tags` (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci
  • 表的列表:每个实体一张表,外加关联表 [products_tags];
  • 表 [products]:其外键 [category_id] 引用表 [categories]。它是 [NOT NULL] ([optional = false])。MySQL 会在每个外键上创建索引([KEY] 行)。与其他 ORM 工具不同,Hibernate 不要求数据库中的级联删除([ON DELETE CASCADE]):可以使用 [@OnDelete(action = OnDeleteAction.CASCADE)] 注解来实现;
  • 关联表有两列——分别是指向两张被关联表的外键——它们共同构成其主键。

该模式与 Java 课程中使用的模式完全相同:用 Kotlin 编写的注解是一样的。

11.8.2. 程序

package relations

import org.hibernate.LazyInitializationException
import org.hibernate.Session
import java.math.BigDecimal
import java.time.LocalDate

// 实体之间的关系:懒加载、join fetch、实体图、连接

// 投影查询的结果
data class ProductCategory(val product: String, val category: String)

data class OrderAmount(val id: Int, val client: String, val amount: BigDecimal)

data class CategoryStatistics(val category: String, val count: Long, val averagePrice: Double)

fun main() {
    Shop.createSessionFactory().use { sessionFactory ->
        // 1 - 创建表和第一批数据,不记录日志
        Shop.initialize(sessionFactory)

        // 2 - 一个客户、其订单及订单行,一次性添加
        println("--- addition of a client, an order and its two lines")
        sessionFactory.inTransaction { session ->
            val bike = session.product("bike")
            val arrows = session.product("arrows - set of 6")
            val order = CustomerOrder(LocalDate.of(2026, 10, 1))
            order.add(OrderLine(bike, 1))
            order.add(OrderLine(arrows, 3))
            val client = Client("Dupont")
            client.add(order)
            session.persist(client)
            println("client no. ${client.id}, order no. ${order.id}")
        }

        // 3 - 懒加载:关系按需读取
        println("--- lazy loading")
        sessionFactory.inSession { session ->
            val orders = session
                .createSelectionQuery("from CustomerOrder order by id", CustomerOrder::class.java)
                .resultList
            for (order in orders) {
                // 客户和订单行在这里首次使用时才读取
                println("order no. ${order.id} : client=${order.client.name}, " +
                        "${order.lines.size} line(s)")
            }
            // [client] 属性包含一个代理:Client 子类的一个对象
            println("class of the client: ${orders[0].client.javaClass.name}")
        }

        // 4 - 未加载的关系在会话关闭后就无法再访问
        println("--- after the session is closed")
        val detachedOrder = sessionFactory.fromSession { it.find(CustomerOrder::class.java, 1) }
        try {
            println("${detachedOrder.lines.size} line(s)")
        } catch (e: LazyInitializationException) {
            println("${e.javaClass.simpleName} : ${e.message}")
        }

        // 5 - join fetch:订单、其客户、其订单行及其产品在一次查询中读取
        println("--- join fetch")
        sessionFactory.inSession { session ->
            val orders = session.createSelectionQuery(
                """
                from CustomerOrder c
                join fetch c.client
                join fetch c.lines l
                join fetch l.product
                order by c.id""", CustomerOrder::class.java
            ).resultList
            for (order in orders) {
                println("order no. ${order.id} of ${order.date} for ${order.client.name}")
                for (line in order.lines) {
                    val product = line.product
                    println("  %d x %s at %.2f euros".format(line.quantity, product.name, product.price))
                }
            }
        }

        // 6 - 实体图:描述在查询之外,说明必须随实体一起加载什么
        println("--- entity graph")
        val category = sessionFactory.fromSession { session ->
            val graph = session.createEntityGraph(Category::class.java)
            graph.addAttributeNodes(Category::products.name)
            session.find(graph, 2)
        }
        // 会话已关闭,但产品已被加载
        println("${category.name} : ${category.products.joinToString(", ") { it.name }}")

        // 7 - 查询中的多对多关系
        println("--- the products on promotion")
        sessionFactory.inSession { session ->
            session.createSelectionQuery(
                """
                select p.name, p.category.name from Product p join p.tags e
                where e.label = :label order by p.name""", ProductCategory::class.java
            )
                .setParameter("label", "promo")
                .resultList
                .forEach { (product, category) -> println("$product ($category)") }
        }

        // 8 - 跨关系的计算,由 DBMS 完成
        println("--- amount of the orders")
        sessionFactory.inSession { session ->
            session.createSelectionQuery(
                """
                select c.id, c.client.name, sum(l.quantity * l.product.price)
                from CustomerOrder c join c.lines l
                group by c.id, c.client.name order by c.id""", OrderAmount::class.java
            )
                .resultList
                .forEach { (id, client, amount) ->
                    println("order no. %d (%s) : %.2f euros".format(id, client, amount))
                }
        }

        // 9 - 分组:每个类别的产品数量和平均价格
        println("--- products per category")
        sessionFactory.inSession { session ->
            session.createSelectionQuery(
                """
                select p.category.name, count(*), avg(p.price) from Product p
                group by p.category.name order by p.category.name""", CategoryStatistics::class.java
            )
                .resultList
                .forEach { (category, count, averagePrice) ->
                    println("%s : %d product(s), average price %.2f euros".format(category, count, averagePrice))
                }
        }
    }
}

// 具有给定名称的产品:会话的一个扩展函数
fun Session.product(name: String): Product =
    createSelectionQuery("from Product where name = :name", Product::class.java)
        .setParameter("name", name)
        .singleResult

结果:

> gradlew -q :relations:run
--- addition of a client, an order and its two lines
    SQL> -- start of transaction
    SQL> select p1_0.id, p1_0.category_id, p1_0.name, p1_0.price
    SQL> from products p1_0
    SQL> where p1_0.name=?
    SQL> -- parameter 1 = bike
    SQL> select p1_0.id, p1_0.category_id, p1_0.name, p1_0.price
    SQL> from products p1_0
    SQL> where p1_0.name=?
    SQL> -- parameter 1 = arrows - set of 6
    SQL> insert into clients (name)
    SQL> values (?)
    SQL> -- parameter 1 = Dupont
    SQL> insert into orders (client_id, date)
    SQL> values (?, ?)
    SQL> -- parameter 1 = 2
    SQL> -- parameter 2 = 2026-10-01
    SQL> insert into order_lines (order_id, product_id, quantity)
    SQL> values (?, ?, ?)
    SQL> -- parameter 1 = 2
    SQL> -- parameter 2 = 1
    SQL> -- parameter 3 = 1
    SQL> insert into order_lines (order_id, product_id, quantity)
    SQL> values (?, ?, ?)
    SQL> -- parameter 1 = 2
    SQL> -- parameter 2 = 4
    SQL> -- parameter 3 = 3
client no. 2, order no. 2
    SQL> -- transaction committed (COMMIT)
--- lazy loading
    SQL> select co1_0.id, co1_0.client_id, co1_0.date
    SQL> from orders co1_0
    SQL> order by co1_0.id
    SQL> select c1_0.id, c1_0.name
    SQL> from clients c1_0
    SQL> where c1_0.id=?
    SQL> -- parameter 1 = 1
    SQL> select l1_0.order_id, l1_0.id, l1_0.product_id, l1_0.quantity
    SQL> from order_lines l1_0
    SQL> where l1_0.order_id=?
    SQL> -- parameter 1 = 1
order no. 1 : client=Martin, 2 line(s)
    SQL> select c1_0.id, c1_0.name
    SQL> from clients c1_0
    SQL> where c1_0.id=?
    SQL> -- parameter 1 = 2
    SQL> select l1_0.order_id, l1_0.id, l1_0.product_id, l1_0.quantity
    SQL> from order_lines l1_0
    SQL> where l1_0.order_id=?
    SQL> -- parameter 1 = 2
order no. 2 : client=Dupont, 2 line(s)
class of the client: relations.Client$HibernateProxy
--- after the session is closed
    SQL> select co1_0.id, co1_0.client_id, co1_0.date
    SQL> from orders co1_0
    SQL> where co1_0.id=?
    SQL> -- parameter 1 = 1
LazyInitializationException : Cannot lazily initialize collection of role 'relations.CustomerOrder.lines' with key '1' (no session)
--- join fetch
    SQL> select
    SQL>     co1_0.id,
    SQL>     co1_0.client_id,
    SQL>     c1_0.id,
    SQL>     c1_0.name,
    SQL>     co1_0.date,
    SQL>     l1_0.order_id,
    SQL>     l1_0.id,
    SQL>     l1_0.product_id,
    SQL>     p1_0.id,
    SQL>     p1_0.category_id,
    SQL>     p1_0.name,
    SQL>     p1_0.price,
    SQL>     l1_0.quantity
    SQL> from orders co1_0
    SQL> join clients c1_0 on c1_0.id=co1_0.client_id
    SQL> join order_lines l1_0 on co1_0.id=l1_0.order_id
    SQL> join products p1_0 on p1_0.id=l1_0.product_id
    SQL> order by co1_0.id
order no. 1 of 2026-09-28 for Martin
  2 x pump at 10.00 euros
  1 x bow at 600.00 euros
order no. 2 of 2026-10-01 for Dupont
  1 x bike at 500.00 euros
  3 x arrows - set of 6 at 100.00 euros
--- entity graph
    SQL> select c1_0.id, c1_0.name, p1_0.category_id, p1_0.id, p1_0.name, p1_0.price
    SQL> from categories c1_0
    SQL> left join products p1_0 on c1_0.id=p1_0.category_id
    SQL> where c1_0.id=?
    SQL> -- parameter 1 = 2
archery : bow, arrows - set of 6
--- the products on promotion
    SQL> select p1_0.name, c1_0.name
    SQL> from products p1_0
    SQL> join products_tags t1_0 on p1_0.id=t1_0.product_id
    SQL> join tags t1_1 on t1_1.id=t1_0.tag_id
    SQL> join categories c1_0 on c1_0.id=p1_0.category_id
    SQL> where t1_1.label=?
    SQL> order by p1_0.name
    SQL> -- parameter 1 = promo
arrows - set of 6 (archery)
bike (cycles)
--- amount of the orders
    SQL> select co1_0.id, c1_0.name, sum((l1_0.quantity*p1_0.price))
    SQL> from orders co1_0
    SQL> join order_lines l1_0 on co1_0.id=l1_0.order_id
    SQL> join products p1_0 on p1_0.id=l1_0.product_id
    SQL> join clients c1_0 on c1_0.id=co1_0.client_id
    SQL> group by co1_0.id, c1_0.name
    SQL> order by co1_0.id
order no. 1 (Martin) : 620.00 euros
order no. 2 (Dupont) : 800.00 euros
--- products per category
    SQL> select c1_0.name, count(*), avg(p1_0.price)
    SQL> from products p1_0
    SQL> join categories c1_0 on c1_0.id=p1_0.category_id
    SQL> group by c1_0.name
    SQL> order by c1_0.name
archery : 2 product(s), average price 350.00 euros
cycles : 2 product(s), average price 255.00 euros

说明:

  • 第 11–15 行:用于接收投影结果的数据类。它们的类型与 DBMS 返回的类型相对应:[Long] 对应 [count],[Double] 对应 [avg];
  • 第 135–138 行:具有给定名称的商品,由 Hibernate 接口 扩展函数 [Session] 读取:在其内部,[createSelectionQuery] 是在会话本身([this],隐式)上调用的。它像会话方法一样被调用:[session.product("bike")] (第 25 行),而 Java 代码之前定义的是静态方法 [product(session, "bike")];
  • 第 24–33 行:一个客户、其订单及两个订单行通过一次 [persist] 调用被持久化。SQL 显示了插入的顺序:先是客户,然后是订单——其外键 [client_id] 接收客户生成的键(2)——最后是订单行,其外键 [order_id] 接收订单的键。[inTransaction] 在 Hibernate 期望 Java 函数式接口([Consumer<Session>])的地方接收了一个 Kotlin lambda:这就是第 7 章中的 SAM 转换;
  • 第 39–45 行:懒加载。该查询只读取订单:每个订单的客户和订单行只有在程序使用它们时才会通过额外的查询读取(第一个订单两次,第二个订单两次)。对于客户,Hibernate 在 [client] 属性中放入了一个代理——即由 Hibernate(使用 Byte Buddy)生成的 [Client] 子类的对象——它只包含标识符,并在第一次调用访问器时读取客户([order.client.name],即 [getName()])。第 48 行展示了这一点:该对象的类是 [relations.Client$HibernateProxy]。这就是实体不能是 final 类、其访问器也不能是 final 方法的原因:在 Kotlin 中,类和成员默认是 final 的,是 [allopen] 插件使它们成为非 final 的。对于订单行,列表是一个 Hibernate 集合,在第一次使用时才加载([size]);
  • 第 53–57 行:订单由一个立即关闭的会话读取([fromSession],它返回 lambda 的结果)。这些订单行没有被加载,而会话一旦关闭,就再也无法加载它们:访问该集合会触发 [LazyInitializationException],这是使用 Hibernate 的应用程序中最常见的异常之一。对 Kotlin 编译器而言,属性的 [MutableList<OrderLine>] 类型没有任何地方提示这一风险:类型安全在按需加载开始的地方就终止了。必须在会话打开期间加载将要用到的内容;
  • 第 63–69 行:通过查询预加载。[join fetch] 指示 Hibernate 在加载订单的同时加载其客户、订单行以及每个订单行的商品:只需一条带连接的查询。输出显示了两个订单及其订单行。与订单行的连接为每个订单行产生一行 SQL 结果;Hibernate 为每个 ID 只得到一个订单:返回的列表确实包含两个订单。跨越多行的查询文本是一个原始字符串;
  • 第 82–88 行:“实体图”(Jakarta Persistence)在任何查询之外描述随实体一起加载的关联:这里是类别中的商品,由属性引用 [Category::products.name] 而不是字符串 ["products"] 标识。[session.find(graph, 2)] (Jakarta Persistence 3.2)通过单条查询(外连接,[left join])读取类别 2 及其商品。会话关闭后,这些商品仍然可以访问。若要在会话打开期间稍后加载某个关联,请使用 [Hibernate.initialize(category.products)]。请注意调用的是 [addAttributeNodes] (复数)而不是 [addAttributeNode]:后者是泛型的,返回一个 *[AttributeNode<Y>]*,而当结果未被使用时,Kotlin 无法推断类型 *[Y]* (“cannot infer type for type parameter 'Y'”);
  • 第 95–100 行:在查询中使用关联:[join p.tags e] 遍历多对多关系(两次连接,分别连接关联表和标签表),而 [p.category.name] 被翻译成与类别表的隐式连接。标签文本通过命名参数传递(Java 课程把它写成查询中的字面值);每个结果被解包到 lambda 的参数中:[{ (product, category) -> ... \}];
  • 第 108–114 行:涉及两个关系的计算——每个订单的金额——完全由 DBMS 完成:连接、[sum] 和 [group by];
  • 第 123–128 行:一次分组。[group by p.category.name] 按类别名称对商品分组;对于每个分组,商品数量([count],类型为 [Long])和平均价格([avg],类型为 [Double])由 DBMS 计算。没有商品的类别 [diving] 不会出现:与类别表的连接是内连接([join])。

11.8.3. N+1 查询问题

示例中的懒加载说明了一个影响所有 ORM 使用者的问题,称为“N+1 查询”问题:一次查询读取 N 个订单,然后每个订单再用一次查询读取其客户(还有一次读取其订单行)。对于一千个订单,这会导致一千零一次到服务器的往返,而本来一次就够了。这个问题尤其隐蔽,因为在代码中看不出来:[order.client.name] 看起来不像一次查询,而 Kotlin 的属性语法把它隐藏得比 Java 调用 [getClient().getName()] 还要好。解决方案就是示例中展示的那些:[join fetch]、实体图,或者更好的做法——投影到只取回必要数据的数据类。Hibernate 还提供批量加载([@BatchSize(size = 20)] 应用于集合,或应用于被引用的实体类,这里是 [Client]),例如,它可以通过一次查询取回二十个订单的客户。SQL 日志有助于发现该问题:同一条查询被大量重复执行。

11.9. 数据库模式的变更

11.9.1. 问题

到目前为止,表都是由 Hibernate 先删除再创建的。这对于正在运行的应用程序是不可能的:其数据库中包含在模型演进(新增列、新增表)时必须保留的数据。必须能够以安全且可重现的方式,把数据库从一个模式版本迁移到下一个版本,无论是在开发人员的机器上还是在生产服务器上。这称为模式 迁移。

Hibernate 不支持模式迁移:它可以创建模式、验证模式,并对其进行有限的更新。JVM 世界(无论是 Java 还是 Kotlin)的标准做法是,把迁移委托给 带版本的 SQL 脚本,由专用工具来应用——最常见的是 Flyway 或 Liquibase——并让 Hibernate 验证最终的模式与实体相符。

11.9.2. 由 Hibernate 管理模式

[hibernate.hbm2ddl.auto] 属性(或配置中的 [schemaToolingAction] 方法,下面的程序使用的就是它)指定 Hibernate 在创建 [SessionFactory] 时应如何处理模式:

值
常量 [Action]
效果
[none]
[NONE]
无(默认值)
[create-only]
[CREATE_ONLY]
创建表
[create]
[CREATE]
先删除再创建表
[create-drop]
[CREATE_DROP]
与 [create] 相同,并在关闭 [SessionFactory] 时删除表:用于测试
[drop]
[DROP]
删除表
[validate]
[VALIDATE]
检查实体的表和列是否存在且类型兼容;否则抛出异常
[update]
[UPDATE]
创建缺失的表和列

Jakarta Persistence 定义了一个相关属性 [jakarta.persistence.schema-generation.database.action],其值为 [none]、[create]、[drop-and-create]、和 [drop]。同样的操作也可以通过编程方式使用,正如我们对 [SessionFactory] 的 [SchemaManager] 所做的那样([create]、[drop]、[validate]、[truncate])。

[update] 选项很诱人:Hibernate 把实体与数据库模式进行比较,并添加缺少的部分。但它有一些局限,使其不适用于生产应用:

  • 它只做添加:从不删除已不再需要的列或表,不修改现有列的类型或长度,也无法重命名(重命名属性会创建一个新的空列,而旧列及其数据仍然保留);
  • 它无法转换数据(填充新的必填列、把一列拆分为两列);
  • 它的行为取决于它遇到的数据库状态:无法事先知道将执行哪些命令、以什么顺序执行,而且不会留下任何记录。

因此,我们把 [create]、[create-drop]和 [update] 留给开发和测试使用,而在生产环境中使用 [validate] (或 [none]),由脚本管理模式。

11.9.3. 带版本的 SQL 脚本

基于脚本的迁移,其原理很简单:

  • 每次模式变更都由一个按顺序编号的 SQL 脚本描述:[V1__create_clients.sql]、[V2__add_phone.sql]……脚本一旦应用到某个数据库,就再也不会被修改:任何修正都要写成新的脚本;
  • 数据库中包含一张历史表,列出已应用到该数据库的版本;
  • 应用程序启动时(或在部署期间),工具会把可用脚本与历史记录进行比较,并按顺序应用尚未应用的脚本。

这些脚本是应用程序源代码的一部分:它们与其余代码一起存储和管理(例如放在 Git 仓库中)。为了理解其工作原理,[clients] 子项目仿照 Flyway 实现了一个小型的带版本脚本运行器;随后我们再介绍 Flyway 本身。

11.9.4. [clients] 子项目

[clients] 子项目使用 [hbclients] 数据库。它有两个程序:默认运行的 [clients.MainKt],以及按需通过 [clients.GenerateScriptKt] 指定的程序,其方式与前几章一样,通过 [main] 属性指定。它的 [build.gradle.kts] 与 [relations] 子项目的相同,只有一处例外:

1
2
3
4
5
application {
    // 由 [gradlew -q :clients:run] 运行的程序:默认为 clients.MainKt,
    // 或由 [main] 属性给出的程序:gradlew -q :clients:run -Pmain=clients.GenerateScriptKt
    mainClass = providers.gradleProperty("main").orElse("clients.MainKt")
}

实体是一个客户:

package clients

import jakarta.persistence.Column
import jakarta.persistence.Entity
import jakarta.persistence.GeneratedValue
import jakarta.persistence.GenerationType
import jakarta.persistence.Id
import jakarta.persistence.Table

// 一个客户
@Entity
@Table(name = "clients")
class Client(
    @Column(nullable = false, length = 50)
    var name: String,
    @Column(nullable = false, length = 100)
    var email: String,
    // 第 2 版:电话,可选(类型 String? 以及一个接受 NULL 的列)
    @Column(length = 20)
    var phone: String? = null,
) {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    var id: Int? = null
        protected set

    override fun toString() = "[$id, $name, $email, ${phone ?: "no phone"}]"
}

在应用程序的第一个版本中,客户没有电话号码:第 18–20 行尚不存在。我们将在第二个版本中添加它们。电话号码是可选的,Kotlin 用可空类型 [String?] 和默认值 [null] 来表达(因此可以创建不带电话号码的客户:[Client("Durand", "durand@example.com")])。不过,Hibernate 并不识别 Kotlin 类型:使列成为可选的,是因为 ***[nullable = false] 没有出现在 *[@Column] 中(反过来,不可空的 Kotlin [String] 只有在显式要求时才会产生 [NOT NULL] 列,如 [name] 和 [email] 的情形)。[toString] 函数(第 27 行)使用 Elvis 运算符来显示没有电话号码的情况。

脚本位于子项目的 [src/main/resources/db/migration] 文件夹中,Gradle 会把它复制到类路径(复制到 [build/resources/main] 文件夹)。这些是 Java 课程中的脚本:SQL 脚本不依赖于应用程序的编程语言。第一个脚本创建表:

1
2
3
4
5
6
7
-- version 1: the clients table
create table clients (
    id integer not null auto_increment,
    name varchar(50) not null,
    email varchar(100) not null,
    primary key (id)
) engine=InnoDB;

第二个脚本添加电话号码列:

1
2
3
-- version 2: the (optional) phone of the clients
alter table clients
    add column phone varchar(20);

[Migrations] 类使用 JDBC(第 10 章)应用这些脚本,独立于 Hibernate:

package clients

import java.nio.file.Path
import java.sql.Connection
import java.sql.DriverManager
import java.sql.SQLException
import kotlin.io.path.listDirectoryEntries
import kotlin.io.path.name
import kotlin.io.path.readLines

// 一个仿照 Flyway 的小型带版本 SQL 脚本运行器:脚本
// [db/migration/V<version>__<description>.sql] 只应用一次,按版本顺序,
// 数据库的 [migration_history] 表记录已应用的脚本
class Migrations(
    private val url: String,
    private val user: String,
    private val password: String,
) {
    // 一个迁移脚本
    data class Script(val version: Int, val description: String, val path: Path) {
        override fun toString() = "V$version ($description)"
    }

    private companion object {
        // 脚本的名称:V1__create_clients.sql
        val NAME = Regex("""V(\d+)__(\w+)\.sql""")

        // 历史表
        const val CREATE_HISTORY = """
            create table if not exists migration_history (
                version integer not null primary key,
                description varchar(100) not null,
                applied_on datetime not null default current_timestamp
            ) engine=InnoDB"""
    }

    // 到数据库的连接
    private fun connection(): Connection = DriverManager.getConnection(url, user, password)

    // 类路径中 [db/migration] 文件夹的脚本,按版本顺序
    fun scripts(): List<Script> {
        val folder = Migrations::class.java.getResource("/db/migration") ?: return emptyList()
        return Path.of(folder.toURI()).listDirectoryEntries()
            .mapNotNull { file ->
                // 名称不遵循约定的文件被忽略(null)
                NAME.matchEntire(file.name)?.destructured?.let { (version, description) ->
                    Script(version.toInt(), description.replace('_', ' '), file)
                }
            }
            .sortedBy { it.version }
    }

    // 已应用到数据库的版本(如有需要则创建历史表)
    fun appliedVersions(): Set<Int> = connection().use { cnx ->
        cnx.createStatement().use { statement ->
            statement.execute(CREATE_HISTORY)
            statement.executeQuery("select version from migration_history").use { rows ->
                sortedSetOf<Int>().apply {
                    while (rows.next()) add(rows.getInt(1))
                }
            }
        }
    }

    // 尚待应用的脚本
    fun pending(): List<Script> {
        val applied = appliedVersions()
        return scripts().filter { it.version !in applied }
    }

    // 应用待处理的脚本,直到版本 [target](含);返回已应用的脚本
    fun migrate(target: Int = Int.MAX_VALUE): List<Script> =
        pending().takeWhile { it.version <= target }.onEach { applyScript(it) }

    // 在事务中应用一个脚本并把它的版本添加到历史中
    private fun applyScript(script: Script) {
        // 脚本的语句,以分号分隔,不含注释行
        val statements = script.path.readLines()
            .filterNot { it.trim().startsWith("--") }
            .joinToString("\n")
            .split(";")
            .filter { it.isNotBlank() }
        connection().use { cnx ->
            cnx.autoCommit = false
            try {
                cnx.createStatement().use { statement -> statements.forEach { statement.execute(it) } }
                cnx.prepareStatement("insert into migration_history(version, description) values (?, ?)")
                    .use { history ->
                        history.setInt(1, script.version)
                        history.setString(2, script.description)
                        history.executeUpdate()
                    }
                cnx.commit()
            } catch (e: SQLException) {
                // 注意:在 MySQL 中,修改模式的语句无法回滚
                cnx.rollback()
                throw e
            }
        }
    }
}
  • 第 14–17 行:数据库由主构造函数的私有属性描述;
  • 第 20–21 行:脚本由嵌套数据类 [Migrations.Script] 描述:包括其版本、描述和路径;其 [toString] 方法被重写以用于显示;
  • 第 24–34 行:类常量,位于私有伴生对象中。第 26 行:脚本的名称遵循 Flyway 约定:[V]——版本号、两个下划线和一段描述。正则表达式写成原始字符串,其中反斜杠无需加倍(["""V(\d+)__(\w+)\.sql"""];在 Java 中为 ["V(\\d+)__(\\w+)\\.sql"])。历史表(每个已应用的版本一行,包含其描述和应用日期)由一条写成原始字符串的命令创建,这是一个常量 [const val];
  • 第 41–50 行:脚本列表。[getResource("/db/migration")] 返回类路径中该目录的 URL,如果目录不存在则返回 [null] :此时 Elvis 运算符会立即返回一个空列表([?: return emptyList()])。目录由 [listDirectoryEntries] 扩展函数(来自 [kotlin.io.path] ,第 5 章)列出。每个文件由 [matchEntire] 用正则表达式检查,如果名称不匹配,它返回 [null] :[mapNotNull] 会过滤掉这些文件,并通过解构([destructured],第 5 章)取得表达式的各个分组。这段代码假定该目录是真实的目录(当程序由 Gradle 从 [build/resources/main] 目录运行时就是如此);Flyway 也可以从 [.jar] 归档文件中读取脚本。脚本按版本号排序([sortedBy]):按字母顺序排序会把 [V10] 排在 [V2] 之前;
  • 第 54–59 行:已经应用的版本,从历史表中取得,该表按需创建([create table if not exists])。三个 JDBC 资源(连接、语句、结果)由三层嵌套的 [use] 资源 关闭。该函数返回一个有序集合([sortedSetOf],即 Java 的 [TreeSet]),由 [apply] 填充;
  • 第 66–68 行:其余待应用的脚本:[!in] 运算符检查某个版本是否不在集合中;
  • 第 72–73 行:应用待处理的脚本,直到给定版本为止(默认应用全部:[target: Int = Int.MAX_VALUE])。[takeWhile] 在脚本版本不超过目标版本时保留这些脚本;[onEach] 应用其中的每一个并返回列表本身:该函数可以写成单个表达式,而 Java 则需要用 [break] 写循环;
  • 第 76–97 行:应用一个脚本:其命令(注释行由 [filterNot] 去除,文本按分号拆分),然后在事务中把其版本添加到历史表([cnx.autoCommit = false],即对应于 [setAutoCommit] 的 Kotlin 属性)。有一点需要注意,第 95 行的注释已经指出:在 MySQL 下,修改模式的命令([CREATE TABLE]、[ALTER TABLE])会隐式提交当前事务,且无法回滚。如果脚本执行到一半出错,数据库可能停留在中间状态。因此建议使用简短的脚本,每个脚本只执行一个操作。

请注意,该类中没有任何函数声明它可能抛出的异常:Java 版本必须在大多数方法上指定 [throws SQLException, IOException, URISyntaxException] ,调用这些方法的 [main] 方法上也要如此。Kotlin 没有受检异常(第 3 章):[SQLException] 只会向上传播,直到有人想要处理它。

主程序应用迁移,然后要求 Hibernate 验证模式:

package clients

import jakarta.persistence.PersistenceException
import org.hibernate.cfg.AvailableSettings
import org.hibernate.jpa.HibernatePersistenceConfiguration
import org.hibernate.tool.schema.Action

// clients 数据库;如果不存在,MySQL 会创建它
const val URL = "jdbc:mysql://localhost:3306/hbclients?createDatabaseIfNotExist=true"

fun main(args: Array<String>) {
    // 目标版本:默认是最后一个,或作为参数传入的版本
    val target = args.firstOrNull()?.toInt() ?: Int.MAX_VALUE

    // 迁移的状态
    val migrations = Migrations(URL, "root", "")
    println("applied versions: ${migrations.appliedVersions()}")
    println("pending migrations: ${migrations.pending()}")

    // 应用待处理的迁移
    for (script in migrations.migrate(target)) {
        println("migration applied: $script")
    }

    // Hibernate 检查数据库模式是否与实体匹配(validate)
    try {
        HibernatePersistenceConfiguration("clients")
            .managedClass(Client::class.java)
            .jdbcUrl(URL)
            .jdbcCredentials("root", "")
            .property(AvailableSettings.FORMAT_SQL, true)
            .schemaToolingAction(Action.VALIDATE)
            .createEntityManagerFactory()
            .use { sessionFactory ->
                println("the database schema matches the entities")
                // 新列可以使用
                sessionFactory.inTransaction { session ->
                    session.persist(Client("Dupont", "dupont@example.com", "01 23 45 67 89"))
                }
                sessionFactory.inSession { session ->
                    session.createSelectionQuery("from Client", Client::class.java)
                        .resultList
                        .forEach(::println)
                }
            }
    } catch (e: PersistenceException) {
        // 验证错误是异常的原因
        val cause = e.cause ?: e
        println("${cause.javaClass.simpleName} : ${cause.message}")
    }
}
  • 第 9 行:数据库的 URL,是 [clients] 包中的顶层常量,第二个程序也会使用它;
  • 第 13 行:可以通过参数指定应用迁移所到达的版本;默认应用全部迁移。[args.firstOrNull()?.toInt() ?: Int.MAX_VALUE] 结合了安全调用和 Elvis 运算符;
  • 第 16–22 行:迁移的状态,随后是迁移的应用;
  • 第 27–34 行:[SessionFactory] 使用操作 [VALIDATE] 创建:Hibernate 验证数据库模式是否与实体 [Client] 相符。如果不相符,[SessionFactory] 的创建会失败并抛出 [PersistenceException],其原因是验证错误(第 46–49 行)。[e.cause ?: e] 捕获该原因,若没有原因则捕获异常本身;
  • 第 37–43 行:使用新增的列。

11.9.5. 用 Hibernate 生成脚本

SQL 脚本是手写的。不过,Hibernate 可以帮助编写它们:它可以生成(但不执行)创建模式的脚本,或者通过把实体与现有数据库进行比较,生成更新模式的脚本。这正是程序 [GenerateScript.kt] 所做的:

package clients

import org.hibernate.cfg.AvailableSettings
import org.hibernate.jpa.HibernatePersistenceConfiguration
import java.io.StringWriter

// 由 Hibernate 生成创建(create)或更新(update)数据库模式的 SQL 脚本
fun main(args: Array<String>) {
    // 操作:create(默认)或 update
    val action = args.firstOrNull() ?: "create"
    val script = StringWriter()
    // 一个只写脚本而不执行的 SessionFactory;它只为此而创建:
    // 立即关闭
    HibernatePersistenceConfiguration("clients")
        .managedClass(Client::class.java)
        .jdbcUrl(URL)
        .jdbcCredentials("root", "")
        .property(AvailableSettings.JAKARTA_HBM2DDL_SCRIPTS_ACTION, action)
        .property(AvailableSettings.JAKARTA_HBM2DDL_SCRIPTS_CREATE_TARGET, script)
        .property(AvailableSettings.HBM2DDL_DELIMITER, ";")
        .property(AvailableSettings.FORMAT_SQL, true)
        .createEntityManagerFactory()
        .close()
    // 脚本,去掉各行 4 个空格的缩进
    script.toString().trim().lines()
        .map { it.removePrefix("    ").trimEnd() }
        .forEach(::println)
}
  • 第 10 行:作为参数传入的操作:[create] 或 [update];
  • 第 14–23 行:[SessionFactory] 只是为了生成脚本而创建:它在创建后立即关闭,甚至没有存储在变量中(Java 课程把它声明在带资源的 [try] 语句中,使用 Java 22 的匿名变量 [_] );
  • 第 18–21 行:脚本生成属性,我们已在子项目 [model] 中遇到过。这一次,Hibernate 会连接到数据库:对于 [update] 操作,它需要了解数据库的模式;
  • 第 25–27 行:脚本,其各行开头的 4 个空格缩进由 [removePrefix] 去除,该函数只在前缀存在时才移除它。

请注意,子项目中的两个程序各有一个顶层 [main] 函数,位于同一个包中:这对 [main] 函数是允许的,因为每个都被编译成各自的文件类([clients.MainKt]、[clients.GenerateScriptKt])。

根据实体的当前版本生成的创建脚本,用于一次性创建新数据库(例如用于测试):

1
2
3
4
5
6
7
8
> gradlew -q :clients:run -Pmain=clients.GenerateScriptKt
create table clients (
    id integer not null auto_increment,
    phone varchar(20),
    name varchar(50) not null,
    email varchar(100) not null,
    primary key (id)
) engine=InnoDB;

对于实体的第一个版本(没有电话号码),它会按相同的列顺序生成脚本 [V1__create_clients.sql]。

11.9.6. 应用迁移

假设数据库尚不存在。我们只应用第一个迁移,把版本 1 作为参数传入(任务 [run] 的 [--args] 选项):

1
2
3
4
5
> gradlew -q :clients:run --args="1"
applied versions: []
pending migrations: [V1 (create clients), V2 (add phone)]
migration applied: V1 (create clients)
SchemaManagementException : Schema validation: missing column [phone] in table [clients]
  • 没有已应用的版本;有两个脚本待处理(Kotlin 列表的显示方式与 Java 列表相同,放在方括号中)。历史表由函数 [appliedVersions] 创建,数据库 [hbclients] 由 MySQL([createDatabaseIfNotExist=true])创建;
  • 脚本 [V1] 已被应用;
  • Hibernate 检测到实体的 [phone] 列在表中不存在:这是正常的,因为数据库处于版本 1,而实体处于版本 2。对于版本 1 的实体,验证会成功。

应用程序在演进:我们要把电话号码添加到实体中。为了编写版本 2 的脚本,我们让 Hibernate 把实体与仍处于版本 1 的数据库进行比较:

1
2
3
> gradlew -q :clients:run -Pmain=clients.GenerateScriptKt --args="update"
alter table clients
   add column phone varchar(20);

除格式之外,这与脚本 [V2__add_phone.sql] 相同。现在我们应用所有待处理的迁移:

> gradlew -q :clients:run
applied versions: [1]
pending migrations: [V2 (add phone)]
migration applied: V2 (add phone)
the database schema matches the entities
    SQL> -- start of transaction
    SQL> insert into clients (email, name, phone)
    SQL> values (?, ?, ?)
    SQL> -- parameter 1 = dupont@example.com
    SQL> -- parameter 2 = Dupont
    SQL> -- parameter 3 = 01 23 45 67 89
    SQL> -- transaction committed (COMMIT)
    SQL> select c1_0.id, c1_0.email, c1_0.name, c1_0.phone
    SQL> from clients c1_0
[1, Dupont, dupont@example.com, 01 23 45 67 89]
  • 版本 1 已应用,版本 2 待处理,随后被应用;
  • 验证成功;
  • 新列已可使用:客户连同其电话号码一起被保存,然后被检索出来。

历史表现在包含两个版本:

1
2
3
4
5
6
7
> mysql -uroot -t hbclients -e "SELECT * FROM migration_history"
+---------+----------------+---------------------+
| version | description    | applied_on          |
+---------+----------------+---------------------+
|       1 | create clients | 2026-10-04 10:55:57 |
|       2 | add phone      | 2026-10-04 10:56:18 |
+---------+----------------+---------------------+

再次运行程序不会应用任何变更:历史中出现了两个版本(不过,它确实会添加第二个名为 Dupont 的客户,这里没有显示):

1
2
3
4
> gradlew -q :clients:run
applied versions: [1, 2]
pending migrations: []
the database schema matches the entities

11.9.7. Flyway

Flyway 是 JVM 上使用最广泛的迁移工具(如果类路径中存在它,Spring Boot 会在应用程序启动时自动运行它)。它的工作原理与我们的执行器完全相同,但功能更全面:默认会在类路径的 [V<version>__<description>.sql] 文件夹 [db/migration] 中搜索脚本,使用历史表 [flyway_schema_history],并按版本顺序应用待处理的脚本。特别是,它为每个脚本添加了校验和,可以检测对已应用脚本的更改;还有“可重复”脚本([R__description.sql],每次变更时重新应用,例如用于视图);用应用程序语言(Java 或 Kotlin 类)编写的迁移;防止应用程序的两个实例同时迁移数据库的锁,以及 Gradle 插件(任务 [flywayMigrate]、[flywayInfo])。

要在 [clients] 子项目中使用它,只需在 [org.flywaydb:flyway-core] 和 [org.flywaydb:flyway-mysql] 依赖(取其最新版本)添加到 [build.gradle.kts] 中,保持两个脚本不变——因为它们已经遵循其约定——并用一行代码取代对 [Migrations] 类的使用:[Flyway.configure().dataSource(URL, "root", "").load().migrate()]。

Liquibase是另一个常用工具,它在 XML、YAML 或 SQL 文件(“changelog”)中描述模式变更,并可生成特定于每种 DBMS 的 SQL。在这两种情况下,Hibernate 都配置为 [validate] 或 [none],不再修改模式。

11.10. Hibernate 与虚拟线程

数据库查询是一种 I/O 操作:当服务器处理请求时,等待的线程什么也不做。第 8 章和第 9 章介绍了在这些等待期间避免浪费线程的两种方式:JDK 虚拟线程 和 Kotlin 协程。Hibernate 的 API 与它所使用的 JDBC 一样,是 阻塞式的:[getResultList] (Kotlin 中的 [resultList] 属性)在读完各行之前不会交出控制权。有了虚拟线程,这不再是缺点:在 I/O 上阻塞的虚拟线程会释放正在执行它的系统线程,而且可以创建成千上万个虚拟线程。因此,我们编写普通的阻塞代码,由虚拟线程执行。使用协程时,我们同样把这些阻塞代码交给专为 I/O 设计的调度器 [Dispatchers.IO] (第 9 章),通过 [withContext] 来完成:等待结果的协程被挂起,而不阻塞其线程。

两种情况下都必须遵守一条规则:会话不是线程安全的。它绝不能在多个线程或多个协程之间共享:每个线程、每个任务和每个协程都用 [SessionFactory] 打开自己的会话,而 SessionFactory 本身是共享的。对于协程,这条规则需要特别注意:协程在挂起之后可能在与其启动时不同的线程上恢复执行;因此,在挂起调用之前打开、在其之后使用的会话会切换线程。最简单的做法是在 [withContext] 块内打开和关闭会话,该块不包含任何挂起点。Hibernate 并不总能检测到对同一会话的并发使用;由此产生的错误是不可预测的。

[async] 子项目贯彻了这一规则。除了 [articles] 库之外,它还依赖 kotlinx-coroutines:

// Hibernate、虚拟线程和协程
plugins {
    kotlin("jvm")
    // 没有 [jpa] 或 [allopen] 插件:该模块不定义任何实体(Article 在 [articles] 中编译)
    application
}

repositories {
    mavenCentral()
}

dependencies {
    // [Article] 实体和 [hbarticles] 数据库(包含 Hibernate、MySQL 和 SQL 日志)
    implementation(project(":articles"))
    // 协程(第 9 章)
    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.11.0")
}

kotlin {
    jvmToolchain(25)
    compilerOptions {
        allWarningsAsErrors = true
        javaParameters = true
    }
}

application {
    // 由 [gradlew -q :async:run] 运行的程序
    mainClass = "async.MainKt"
}

// 在 Windows 上,由 Gradle(run、bootRun 等)启动的程序的屏幕输出以 UTF-8 编码,
// 否则带重音符号的字符在 IntelliJ IDEA 控制台或终端中会出现乱码
tasks.withType<JavaExec>().configureEach {
    jvmArgs("-Dstdout.encoding=UTF-8", "-Dstderr.encoding=UTF-8")
}
  • 第 14 行:[Article] 实体和 [hbarticles] 数据库,与前面的示例相同;
  • 第 16 行:协程库(第 9 章);
  • 第 32–35 行:由 Gradle 启动的程序以 UTF-8 输出,以便带重音符号的字符在 Windows 上正确显示(第 2 章)。

程序:

package async

import articles.Article
import articles.BaseArticles
import jakarta.persistence.QueryTimeoutException
import java.math.BigDecimal
import java.util.concurrent.CompletableFuture
import java.util.concurrent.Executors
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.async
import kotlinx.coroutines.runBlocking
import kotlinx.coroutines.withContext
import org.hibernate.SessionFactory

// Hibernate(一个阻塞 API)搭配虚拟线程,然后搭配协程
fun main() {
    BaseArticles.createSessionFactory().use { sessionFactory ->
        // [articles] 表被重新创建,含六件商品
        BaseArticles.initialize(sessionFactory)

        // 1 - 两个查询由两个虚拟线程同时执行,每个都使用自己的会话
        println("--- two queries in parallel")
        Executors.newVirtualThreadPerTaskExecutor().use { executor ->
            val lowPrices = executor.submit<List<Article>> {
                sessionFactory.fromSession { s ->
                    s.createSelectionQuery("from Article where price < 200 order by price", Article::class.java)
                        .resultList
                }
            }
            val hql = "select count(*) from Article where currentStock < minimumStock"
            val outOfStock = executor.submit<Long> {
                sessionFactory.fromSession { s ->
                    s.createSelectionQuery(hql, Long::class.java).singleResult
                }
            }
            // get() 等待每个任务结束
            lowPrices.get().forEach { println(it) }
            println("${outOfStock.get()} article(s) out of stock")
        }

        // 2 - 由虚拟线程执行的事务,随后处理其结果
        println("--- CompletableFuture")
        Executors.newVirtualThreadPerTaskExecutor().use { executor ->
            val processing = CompletableFuture
                .supplyAsync({
                    sessionFactory.fromTransaction { session ->
                        session.createSelectionQuery("from Article where name = 'bow'", Article::class.java)
                            .singleResult
                            .apply { price = BigDecimal.valueOf(550) }
                    }
                }, executor)
                .thenAccept { bow -> println("new price of the bow: ${bow.price}") }
            processing.join()
        }

        // 3 - 协程:每个协程执行一个打开自己会话的挂起函数
        println("--- coroutines")
        runBlocking {
            // runBlocking 的两个子协程,同时执行
            val cheap = async {
                countArticles(sessionFactory, "select count(*) from Article where price < 200")
            }
            val expensive = async {
                countArticles(sessionFactory, "select count(*) from Article where price >= 200")
            }
            // await() 挂起主协程,直到每个子协程的结果
            println("${cheap.await()} article(s) under 200 euros")
            println("${expensive.await()} article(s) at 200 euros or more")
        }

        // 4 - 流:实体在读取时即被处理
        println("--- getResultStream")
        sessionFactory.inSession { session ->
            session.createSelectionQuery("from Article where price >= 300", Article::class.java)
                .resultStream
                .use { articles -> articles.forEach { println("read: ${it.name}") } }
        }

        // 5 - 过长的查询在设定的超时(以秒为单位)后被中断
        println("--- timeout exceeded")
        try {
            sessionFactory.inSession { session ->
                session.createNativeQuery("select sleep(5)", Int::class.java)
                    .setTimeout(1)
                    .singleResult
            }
        } catch (e: QueryTimeoutException) {
            println("${e::class.simpleName} : ${e.message}")
        }
    }
}

// 在协程专属会话中执行的计数查询;阻塞的工作
// 交给 [IO] 调度器:调用的协程被挂起,它的线程不被阻塞
suspend fun countArticles(sessionFactory: SessionFactory, hql: String): Long =
    withContext(Dispatchers.IO) {
        sessionFactory.fromSession { session ->
            session.createSelectionQuery(hql, Long::class.java).singleResult
        }
    }

结果:

> gradlew -q :async:run
--- two queries in parallel
    SQL> select count(*)
    SQL> from articles a1_0
    SQL> where a1_0.currentStock<a1_0.minimumStock
    SQL> select a1_0.id, a1_0.currentStock, a1_0.minimumStock, a1_0.name, a1_0.price
    SQL> from articles a1_0
    SQL> where a1_0.price<200
    SQL> order by a1_0.price
[2, pump, 10.00, 10, 2]
[4, arrows - set of 6, 100.00, 12, 20]
[6, diver's oxygen tanks, 120.00, 10, 5]
1 article(s) out of stock
--- CompletableFuture
    SQL> -- start of transaction
    SQL> select a1_0.id, a1_0.currentStock, a1_0.minimumStock, a1_0.name, a1_0.price
    SQL> from articles a1_0
    SQL> where a1_0.name='bow'
    SQL> update articles
    SQL> set currentStock=?, minimumStock=?, name=?, price=?
    SQL> where id=?
    SQL> -- parameter 1 = 4
    SQL> -- parameter 2 = 1
    SQL> -- parameter 3 = bow
    SQL> -- parameter 4 = 550
    SQL> -- parameter 5 = 3
    SQL> -- transaction committed (COMMIT)
new price of the bow: 550
--- coroutines
    SQL> select count(*)
    SQL> from articles a1_0
    SQL> where a1_0.price<200
    SQL> select count(*)
    SQL> from articles a1_0
    SQL> where a1_0.price>=200
3 article(s) under 200 euros
3 article(s) at 200 euros or more
--- getResultStream
    SQL> select a1_0.id, a1_0.currentStock, a1_0.minimumStock, a1_0.name, a1_0.price
    SQL> from articles a1_0
    SQL> where a1_0.price>=300
read: bike
read: bow
read: diving suit
--- timeout exceeded
    SQL> select sleep(5)
    SQL> -- failure: Statement cancelled due to timeout or client request
QueryTimeoutException : JDBC exception executing SQL [Statement cancelled due to timeout or client request] [select sleep(5)]

说明:

  • 第 23 行:一个为每个任务创建一个虚拟线程的执行器(第 8 章)。[ExecutorService] 是 [AutoCloseable]:[use] 函数在块的末尾关闭它,而关闭时会等待所有任务完成;
  • 第 24–33 行:提交给执行器的两个任务。每个任务打开自己的会话([fromSession])并执行一个查询;两个查询同时运行,使用连接池中的两个连接。因此,它们在日志中的顺序(结果的第 3–9 行)每次执行时可能不同。结果类型在 [submit] 中指定([submit<List<Article>>]):否则,lambda 可能被解释为 [Runnable](它不返回任何内容),而不是 [Callable];
  • 第 33 行:计数查询结果的类型。[Long::class.java] 在这里指 Java 基本类型 [long];Hibernate 接受它,并把值作为 [java.lang.Long] 返回,Kotlin 把它当作 [Long];
  • 第 36–38 行:[get()] 等待每个任务完成并返回其结果(第 10–13 行);
  • 第 44–53 行:一个 [CompletableFuture] (第 9 章),其第一步——一个完整的事务——由虚拟线程执行([supplyAsync(..., executor)]),第二步显示其结果。[apply] 函数修改读取到的记录并返回它:这是 lambda 的值,也就是事务的结果。事务返回的记录是分离的(其会话已关闭):我们可以读取它的属性,但不能加载它的关联;
  • 第 58–68 行:使用协程的同样思路。[runBlocking] 创建一个主协程;[async] 启动两个子协程,它们调用挂起函数 [countArticles]。两个请求同时运行(第 30–35 行),而 [await] 会挂起主协程,直到每个协程返回(第 36–37 行);
  • 第 95–96 行:挂起函数把阻塞的工作委托给 [Dispatchers.IO] 调度器,其线程专为等待 I/O 操作而设计。会话由 [fromSession] 在 [withContext] 块内打开和关闭:它只被一个协程使用,并且在单个线程上。从挂起代码中调用 Hibernate 时应当采用这种做法。也可以使用基于虚拟线程构建的调度器([Executors.newVirtualThreadPerTaskExecutor().asCoroutineDispatcher()],第 9 章);
  • 第 73–76 行:属性 [resultStream] (方法 [getResultStream])返回一个 Java 流:实体在被读取时就被处理,而不形成列表(第 42–44 行)。流是 [AutoCloseable]:[use] 会关闭它,从而释放 JDBC 游标。也可以把它转换为 Kotlin 序列([asSequence()],第 5 章)。这对处理大量行很有用。使用 MySQL 时请注意,默认情况下驱动程序会先读取结果的所有行,然后才返回第一行;若要真正渐进地读取,必须指示它使用游标(URL 的参数 [useCursorFetch=true] ,以及由 [setFetchSize] 设置的批大小);
  • 第 83–87 行:由 [setTimeout] 设置的以秒为单位的最长执行时间。该查询(一个原生 SQL 查询,我们稍后讨论)需要五秒;一秒后,JDBC 驱动程序中断它,Hibernate 抛出 [QueryTimeoutException] (第 46–48 行)。

最后一个请求的持续时间值得说明一下。在第 9 章中,我们取消了协程([job.cancel()]、[withTimeout])和任务([Future.cancel])。这些取消对这里的请求不会产生任何效果:取消协程是 协作式的,而阻塞在 JDBC 驱动程序中的协程不会检查自己是否已被取消;至于中断阻塞在驱动程序中的线程,它不会中断服务器上正在进行的请求。[withTimeout(1000) { countArticles(...) }] 确实会抛出 [TimeoutCancellationException]……但要等到请求完成之后,即五秒后:[countArticles] 的 [withContext] 块在完成其阻塞操作之前不会交出控制权。因此,要限制请求的持续时间,必须通过 [setTimeout] 来处理 JDBC 驱动程序。

对于需要真正非阻塞 API 的应用程序,有 Hibernate Reactive,它是 Hibernate 的一个变体,依赖响应式驱动程序(来自 Vert.x 的驱动程序)而不是 JDBC,其方法返回 [CompletionStage] 或 Mutiny 库中的对象;[CompletionStage] 在协程中通过 kotlinx-coroutines 的 [await] 扩展函数来等待。虚拟线程和 [Dispatchers.IO] 调度器在大多数情况下消除了这种复杂性:本课程采用的正是这种方式。

11.11. 事务与并发

11.11.1. 事务

第 10 章介绍了事务:一组要么全部成功、要么全部失败的操作。在 Hibernate 中:

  • 每个写操作都在事务中执行,事务由 [session.beginTransaction()] 开启,并由 [commit] 或 [rollback] 结束。[SessionFactory] 的 [inTransaction] 和 [fromTransaction] 方法替我们处理这些事情:如果 lambda 正常结束,它们就提交事务;如果抛出异常,就回滚事务,然后重新抛出该异常;
  • 事务期间发送的所有命令(通过 [INSERT] 立即执行的命令、通过 [flush] 显式同步的命令,以及通过 [commit] 同步的命令)要么一起提交,要么一起回滚;
  • 来自 DBMS 的错误会作为 Hibernate 异常传播,该异常派生自 [JDBCException],并封装了驱动程序的 [SQLException]:违反约束(主键、唯一性、外键、[NOT NULL])时为 [ConstraintViolationException] ,SQL 语句有错误时为 [SQLGrammarException] ,等等。无论在 Java 还是 Kotlin 中,这些都是非受检异常(提醒一下,Kotlin 没有受检异常:第 3 章);我们只捕获自己知道如何处理的异常。

子项目 [transactions] 演示了处理事务的两种方式:

package transactions

import articles.Article
import articles.BaseArticles
import java.math.BigDecimal
import org.hibernate.SessionFactory
import org.hibernate.exception.ConstraintViolationException

// 管理事务的两种方式:inTransaction,以及由代码管理的事务
fun main() {
    BaseArticles.createSessionFactory().use { sessionFactory ->
        // [articles] 表被重新创建,含六件商品
        BaseArticles.initialize(sessionFactory)

        // 1 - inTransaction:全部成功则提交,发生异常则回滚
        println("--- two additions, the second of which violates the uniqueness of the name")
        try {
            sessionFactory.inTransaction { session ->
                session.persist(Article("racket", BigDecimal.valueOf(80), 5, 2))
                session.persist(Article("bike", BigDecimal.valueOf(450), 3, 1))
            }
        } catch (e: ConstraintViolationException) {
            println("${e::class.simpleName} : constraint [${e.constraintName}] violated")
        }
        display(sessionFactory, "racket")

        // 2 - 由代码管理的事务:多次写入,一起提交或回滚
        println("--- transaction rolled back")
        sessionFactory.openSession().use { session ->
            val transaction = session.beginTransaction()
            try {
                // 出售两辆自行车:UPDATE 由 flush 发送
                val bike = session
                    .createSelectionQuery("from Article where name = 'bike'", Article::class.java)
                    .singleResult
                bike.currentStock -= 2
                session.flush()
                // 添加一件名称已存在的商品:错误
                session.persist(Article("pump", BigDecimal.valueOf(12), 5, 1))
                // 整体提交(这里不会执行到)
                transaction.commit()
            } catch (e: ConstraintViolationException) {
                println("${e::class.simpleName} : ${e.sqlException.message}")
                // 回滚事务的所有操作
                transaction.rollback()
            }
        }
        // 自行车的出售已被回滚
        display(sessionFactory, "bike")
    }
}

// 显示从数据库读取的商品,使用新的会话
fun display(sessionFactory: SessionFactory, name: String) {
    val article = sessionFactory.fromSession { session ->
        session.createSelectionQuery("from Article where name = :name", Article::class.java)
            .setParameter("name", name)
            .singleResultOrNull
    }
    println("article [$name] in the database: ${article ?: "missing"}")
}

结果:

> gradlew -q :transactions:run
--- two additions, the second of which violates the uniqueness of the name
    SQL> -- start of transaction
    SQL> insert into articles (currentStock, minimumStock, name, price)
    SQL> values (?, ?, ?, ?)
    SQL> -- parameter 1 = 5
    SQL> -- parameter 2 = 2
    SQL> -- parameter 3 = racket
    SQL> -- parameter 4 = 80
    SQL> insert into articles (currentStock, minimumStock, name, price)
    SQL> values (?, ?, ?, ?)
    SQL> -- parameter 1 = 3
    SQL> -- parameter 2 = 1
    SQL> -- parameter 3 = bike
    SQL> -- parameter 4 = 450
    SQL> -- failure: Duplicate entry 'bike' for key 'articles.uk_articles_name'
    SQL> -- transaction rolled back (ROLLBACK)
ConstraintViolationException : constraint [articles.uk_articles_name] violated
    SQL> select a1_0.id, a1_0.currentStock, a1_0.minimumStock, a1_0.name, a1_0.price
    SQL> from articles a1_0
    SQL> where a1_0.name=?
    SQL> -- parameter 1 = racket
article [racket] in the database: missing
--- transaction rolled back
    SQL> -- start of transaction
    SQL> select a1_0.id, a1_0.currentStock, a1_0.minimumStock, a1_0.name, a1_0.price
    SQL> from articles a1_0
    SQL> where a1_0.name='bike'
    SQL> update articles
    SQL> set currentStock=?, minimumStock=?, name=?, price=?
    SQL> where id=?
    SQL> -- parameter 1 = 8
    SQL> -- parameter 2 = 5
    SQL> -- parameter 3 = bike
    SQL> -- parameter 4 = 500.00
    SQL> -- parameter 5 = 1
    SQL> insert into articles (currentStock, minimumStock, name, price)
    SQL> values (?, ?, ?, ?)
    SQL> -- parameter 1 = 5
    SQL> -- parameter 2 = 1
    SQL> -- parameter 3 = pump
    SQL> -- parameter 4 = 12
    SQL> -- failure: Duplicate entry 'pump' for key 'articles.uk_articles_name'
ConstraintViolationException : Duplicate entry 'pump' for key 'articles.uk_articles_name'
    SQL> -- transaction rolled back (ROLLBACK)
    SQL> select a1_0.id, a1_0.currentStock, a1_0.minimumStock, a1_0.name, a1_0.price
    SQL> from articles a1_0
    SQL> where a1_0.name=?
    SQL> -- parameter 1 = bike
article [bike] in the database: [1, bike, 500.00, 10, 5]

说明:

  • 第 18–20 行:向由 [inTransaction] 管理的事务中添加两个商品;第二个商品与现有商品同名。两个 [INSERT] 操作都被立即执行(第 4–15 行);第二个操作违反了 [name] 列上的唯一性约束:MySQL 拒绝了它(第 16 行),[persist] 抛出 [ConstraintViolationException],[inTransaction] 回滚事务(第 17 行)并重新抛出该异常;
  • 第 22–23 行:捕获异常;[constraintName] 属性(即 [getConstraintName] 方法)返回被违反约束的名称(第 18 行)。这表明为约束命名是有价值的;
  • 第 25 行:已成功插入的球拍不在数据库中(第 23 行):回滚事务把它删除了;
  • 第 29–45 行:由代码管理的事务,位于由 [openSession] 打开、由 [use] 关闭的会话中([Session] 是 [AutoCloseable])。卖出两辆自行车([bike.currentStock -= 2]:运算符 [-=] 应用于 [var] 属性,就像应用于变量一样),并通过显式的 [flush] 把更改发送给 DBMS(第 29–36 行);然后添加一个名称已存在的商品:插入失败(第 43 行);
  • 第 41 行:永远不会执行到提交;
  • 第 42–45 行:在 [catch] 中,事务被回滚(结果的第 45 行)。[sqlException] 属性返回来自 JDBC 驱动程序的原始异常,其消息是 MySQL 的消息(第 44 行);
  • 第 49 行:自行车的销售虽然已通过 [flush] 发送给 DBMS,但已被取消:自行车库存仍为 10(第 50 行);
  • 第 54–60 行:一个用新会话重新读取记录的函数,以便查看数据库的实际状态,而不是当前工作会话中的实体。如果查询没有找到任何内容,属性 [singleResultOrNull] 会设为 [null] ,Elvis 运算符([?:])随后显示“missing”。

发生异常之后,不应再使用该会话:其持久化上下文中可能包含与数据库状态不一致的实体。我们回滚事务,关闭会话,并在必要时用新会话重新开始。这正是 [inTransaction] 所做的,也是我们的代码在退出关闭会话的 [use] 块时所做的。

事务隔离级别是 JDBC 连接的隔离级别:[REPEATABLE_READ],即 MySQL 的默认值,如第一个示例所示。可以在配置中使用 [jdbcTransactionIsolation] 方法为整个 [SessionFactory] 更改它。

11.11.2. 乐观并发

两个用户读取同一个商品,其库存为 10。第一个用户卖出一件,并把库存更新为 9。第二个用户在此次更新之前读取了库存值,他卖出三件,并把库存更新为 7:第一个用户的销售就丢失了。这就是 丢失更新 问题。

一种解决方案是在每个用户的整个操作期间锁定该行(“悲观”并发):这会阻塞其他用户,有时会阻塞很长时间。在 Hibernate 中,通常首选 乐观 并发:不锁定任何内容,但在保存时进行检查,以确保该行自读取以来没有被修改过。标准的做法是给实体添加一个 版本号——一个用 [@Version] 注解的属性。每次修改该行时,Hibernate 都会递增这个数字,并通过 [UPDATE] 和 [DELETE] 命令,在 [WHERE] 子句中加入条件“版本仍然是读取时的值”。如果事务没有修改任何行,就意味着另一个用户已经访问过这些数据:Hibernate 会抛出 [OptimisticLockException]。

子项目 [concurrency] 使用它自己的数据库 [hbconcurrency] 和它自己的实体 [Article],后者被精简到只剩要点:

// 一件其修改受版本号控制的商品
@Entity
@Table(name = "articles")
class Article(
    @Column(nullable = false, length = 30)
    var name: String,
    var currentStock: Int,
) {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    var id: Int? = null
        protected set

    // 版本号:每次修改该行时由 Hibernate 递增
    @Version
    var version: Int = 0
        protected set
}
  • 第 15–17 行:版本号,类型为 [Int] (也可以使用 [Long],或 [Instant] 形式的日期)。应用程序自己从不修改它:其修饰符是受保护的([protected set]),就像标识符的一样;直接访问该字段的 Hibernate 不受此影响。初始值 [0] 是应用程序创建的商品的初始值;对于从数据库读取的商品,由 [jpa] 插件添加的无参构造函数不执行这一初始化(如我们所见),但 Hibernate 会立即把读取到的值赋给该属性。

由于实体定义在子项目本身中,其构建文件应用了 [jpa] 和 [allopen] 插件,并直接依赖 Hibernate 和 [tools] 库:

// 乐观并发:带版本号的实体,位于它自己的 [hbconcurrency] 数据库中
plugins {
    kotlin("jvm")
    // 该模块定义了自己的实体:[jpa] 和 [allopen] 插件
    kotlin("plugin.jpa")
    kotlin("plugin.allopen")
    application
}

repositories {
    mavenCentral()
}

dependencies {
    // 紧凑的 SQL 日志(以及 Logback)
    implementation(project(":tools"))
    // Hibernate 和 MySQL JDBC 驱动
    implementation("org.hibernate.orm:hibernate-core:7.4.5.Final")
    runtimeOnly("com.mysql:mysql-connector-j:9.7.0")
}

// 以这种方式标注的类由 [allopen] 插件打开
allOpen {
    annotation("jakarta.persistence.Entity")
    annotation("jakarta.persistence.MappedSuperclass")
    annotation("jakarta.persistence.Embeddable")
}

kotlin {
    jvmToolchain(25)
    compilerOptions {
        allWarningsAsErrors = true
        javaParameters = true
    }
}

application {
    // 由 [gradlew -q :concurrency:run] 运行的程序
    mainClass = "concurrency.MainKt"
}

// 在 Windows 上,由 Gradle(run、bootRun 等)启动的程序的屏幕输出以 UTF-8 编码,
// 否则带重音符号的字符在 IntelliJ IDEA 控制台或终端中会出现乱码
tasks.withType<JavaExec>().configureEach {
    jvmArgs("-Dstdout.encoding=UTF-8", "-Dstderr.encoding=UTF-8")
}
  • 第 5–6 行:两个实体插件,由 [allOpen] 块配置(第 23–26 行);
  • 第 16–19 行:精简的 SQL 日志、Hibernate 以及 MySQL 的 JDBC 驱动程序;
  • 第 42–45 行:由 Gradle 启动的程序以 UTF-8 输出,以便带重音符号的字符在 Windows 上正确显示(第 2 章)。

该程序用两个会话模拟两个用户:

package concurrency

import jakarta.persistence.OptimisticLockException
import org.hibernate.cfg.AvailableSettings
import org.hibernate.jpa.HibernatePersistenceConfiguration
import tools.SqlLog

// 乐观并发:两个用户修改同一件商品
fun main() {
    HibernatePersistenceConfiguration("concurrency")
        .managedClass(Article::class.java)
        .jdbcUrl("jdbc:mysql://localhost:3306/hbconcurrency?createDatabaseIfNotExist=true")
        .jdbcCredentials("root", "")
        .property(AvailableSettings.FORMAT_SQL, true)
        .createEntityManagerFactory()
        .use { sessionFactory ->
            // [articles] 表被重新创建,只含一件商品,不记录日志
            SqlLog.withoutLog {
                sessionFactory.schemaManager.drop(false)
                sessionFactory.schemaManager.create(false)
                sessionFactory.inTransaction { session -> session.persist(Article("bike", 10)) }
            }

            // 两个用户,两个会话:各自读取同一件商品
            sessionFactory.openSession().use { session1 ->
                sessionFactory.openSession().use { session2 ->
                    println("--- the two users read the bike")
                    val bike1 = session1.find(Article::class.java, 1)
                    val bike2 = session2.find(Article::class.java, 1)

                    // 用户 1 卖出 1 辆自行车
                    println("--- user 1 sells 1 bike")
                    val transaction1 = session1.beginTransaction()
                    bike1.currentStock -= 1
                    transaction1.commit()
                    println("stock saved by user 1: ${bike1.state()}")

                    // 用户 2 根据过时的数据卖出 3 辆自行车(库存 = 10,版本 0)
                    println("--- user 2 sells 3 bikes")
                    val transaction2 = session2.beginTransaction()
                    bike2.currentStock -= 3
                    try {
                        session2.flush()
                        transaction2.commit()
                    } catch (e: OptimisticLockException) {
                        println("${e::class.simpleName} : ${e.message}")
                        transaction2.rollback()
                    }
                }
            }

            // 解决办法:用户 2 用新的会话重新读取该商品,然后重新开始
            println("--- user 2 reads the bike again and starts over")
            sessionFactory.inTransaction { session ->
                val bike = session.find(Article::class.java, 1)
                println("stock read again: ${bike.state()}")
                bike.currentStock -= 3
                session.flush()
                println("stock saved by user 2: ${bike.state()}")
            }
        }
}

// 用于显示的商品状态:一个扩展函数
fun Article.state() = "$currentStock (version $version)"

结果:

> gradlew -q :concurrency:run
--- the two users read the bike
    SQL> select a1_0.id, a1_0.currentStock, a1_0.name, a1_0.version
    SQL> from articles a1_0
    SQL> where a1_0.id=?
    SQL> -- parameter 1 = 1
    SQL> select a1_0.id, a1_0.currentStock, a1_0.name, a1_0.version
    SQL> from articles a1_0
    SQL> where a1_0.id=?
    SQL> -- parameter 1 = 1
--- user 1 sells 1 bike
    SQL> -- start of transaction
    SQL> update articles
    SQL> set currentStock=?, name=?, version=?
    SQL> where id=? and version=?
    SQL> -- parameter 1 = 9
    SQL> -- parameter 2 = bike
    SQL> -- parameter 3 = 1
    SQL> -- parameter 4 = 1
    SQL> -- parameter 5 = 0
    SQL> -- transaction committed (COMMIT)
stock saved by user 1: 9 (version 1)
--- user 2 sells 3 bikes
    SQL> -- start of transaction
    SQL> update articles
    SQL> set currentStock=?, name=?, version=?
    SQL> where id=? and version=?
    SQL> -- parameter 1 = 7
    SQL> -- parameter 2 = bike
    SQL> -- parameter 3 = 1
    SQL> -- parameter 4 = 1
    SQL> -- parameter 5 = 0
OptimisticLockException : Unexpected row count (expected row count 1 but was 0) [update articles set currentStock=?,name=?,version=? where id=? and version=?] for entity [concurrency.Article with id '1']
    SQL> -- transaction rolled back (ROLLBACK)
--- user 2 reads the bike again and starts over
    SQL> -- start of transaction
    SQL> select a1_0.id, a1_0.currentStock, a1_0.name, a1_0.version
    SQL> from articles a1_0
    SQL> where a1_0.id=?
    SQL> -- parameter 1 = 1
stock read again: 9 (version 1)
    SQL> update articles
    SQL> set currentStock=?, name=?, version=?
    SQL> where id=? and version=?
    SQL> -- parameter 1 = 6
    SQL> -- parameter 2 = bike
    SQL> -- parameter 3 = 2
    SQL> -- parameter 4 = 1
    SQL> -- parameter 5 = 1
stock saved by user 2: 6 (version 2)
    SQL> -- transaction committed (COMMIT)

说明:

  • 第 10–15 行:针对 [hbconcurrency] 数据库及其唯一实体的 Hibernate 配置;
  • 第 18–21 行:重新创建表,其中只有一个商品,即自行车,版本为 0。[withoutLog] 函数来自库 [tools] ,以 lambda 的形式接收要执行的操作,由于它是唯一的参数,因此写在括号之外(第 7 章);
  • 第 28–29 行:每个用户在自己的会话中读取自行车;这两个会话由两个嵌套的 [use] 函数打开,并按与打开相反的顺序关闭。[version] 列与其他列一起被读取(第 3–10 行);
  • 第 33–35 行:来自第一个用户的 [UPDATE] 命令(第 13–20 行)写入新版本(1),并包含条件 [version=?] ,其值为所读取的版本(0)。该行被修改;实体的 [version] 属性被设为 1(第 22 行);
  • 第 41–44 行:第二个用户的请求包含相同的条件,其版本是他读取到的 0,而数据库中该行的版本现在是 1。没有行被修改,Hibernate 抛出 [OptimisticLockException] (第 33 行)。我们在 [flush] 之前显式同步会话,在 [commit] 之前触发这个异常的原始形式;如果它是在 [commit] 期间抛出的,它会被封装在 [RollbackException] 中;
  • 第 54–59 行:解决办法取决于应用程序:中止、通知用户,或者像这里一样,用新会话重新读取该商品(收到异常的会话不得再使用),然后重复该操作。补货后的库存是版本 1 中的 9(第 41 行),卖出三辆自行车后,库存为版本 2 中的 6(第 50 行);
  • 第 65 行:一个扩展函数(第 4 章),用于格式化商品的状态以便显示。它定义在程序内部,不修改实体。

两种变体:

  • 没有版本列时,Hibernate 可以自行检查各列的旧值:在实体上使用注解 [@OptimisticLocking(type = OptimisticLockType.DIRTY)] 和 [@DynamicUpdate] 后,[UPDATE] 的 [WHERE] 子句会包含从每个被修改的列读取到的值([where id=? and currentStock=?])。这对无法修改的现有数据库很有用;
  • 当冲突频繁时,悲观并发仍然是可行的:[session.find(Article::class.java, 1, LockModeType.PESSIMISTIC_WRITE)] 用 [select ... for update] 命令读取该行,该命令会锁定它直到事务结束。

11.12. 原生 SQL

Hibernate 根据 HQL 或 Criteria API 生成 SQL,但仍然可以自己编写查询的 SQL,以使用 DBMS 特有的功能或优化复杂的查询:这称为 原生 查询。[rawsql] 子项目列出了可用的方法:

package rawsql

import articles.Article
import articles.BaseArticles
import java.math.BigDecimal
import java.sql.Connection

// 原生 SQL 查询:手工编写,原样传递给 DBMS
fun main() {
    BaseArticles.createSessionFactory().use { sessionFactory ->
        // [articles] 表被重新创建,含六件商品
        BaseArticles.initialize(sessionFactory)
        sessionFactory.openSession().use { session ->
            // 1 - 手工编写的返回实体的 SQL 查询
            println("--- createNativeQuery: entities")
            val minPrice = BigDecimal.valueOf(200)
            val expensive = session
                .createNativeQuery(
                    """
                    select * from articles
                    where price > :minPrice order by name""".trimIndent(), Article::class.java
                )
                .setParameter("minPrice", minPrice)
                .resultList
            expensive.forEach { println(it) }

            // 2 - 作为参数传入的值:不可能发生 SQL 注入
            println("--- SQL injection attempt with a parameter")
            val name = "x' or '1'='1"
            var nb = session
                .createNativeQuery("select count(*) from articles where name = :name", Long::class.java)
                .setParameter("name", name)
                .singleResult
            println("$nb article(s) found")
            // 用字符串模板构建的同一个查询:绝不要这样做
            println("--- the same attempt with a string template")
            val sql = "select count(*) from articles where name = '$name'"
            nb = session.createNativeQuery(sql, Long::class.java).singleResult
            println("$nb article(s) found")

            // 3 - 不是实体的结果
            println("--- createNativeQuery: values")
            val names = session
                .createNativeQuery(
                    "select name from articles where currentStock < minimumStock", String::class.java
                )
                .resultList
            println("out of stock: ${names.joinToString(", ")}")
            val value = session
                .createNativeQuery("select sum(price * currentStock) from articles", BigDecimal::class.java)
                .singleResult
            println("value of the stock: %.2f euros".format(value))

            // 4 - update 语句
            println("--- createNativeMutationQuery")
            val nbRows = session.fromTransaction { _ ->
                session
                    .createNativeMutationQuery(
                        """
                        update articles set price = price * :coefficient
                        where name = :name""".trimIndent()
                    )
                    .setParameter("coefficient", BigDecimal("0.9"))
                    .setParameter("name", "bow")
                    .executeUpdate()
            }
            println("$nbRows row(s) modified")

            // 5 - 会话的 JDBC 连接,用于普通的 JDBC 代码
            println("--- doWork: the JDBC connection")
            session.doWork { connection: Connection ->
                val query = "select name, price from articles where name = 'bow'"
                connection.createStatement().use { statement ->
                    statement.executeQuery(query).use { rows ->
                        while (rows.next()) {
                            val price = rows.getBigDecimal("price")
                            println("${rows.getString("name")} : %.2f euros".format(price))
                        }
                    }
                }
            }
        }
    }
}

结果:

> gradlew -q :rawsql:run
--- createNativeQuery: entities
    SQL> select *
    SQL> from articles
    SQL> where price > ?
    SQL> order by name
    SQL> -- parameter 1 = 200
[1, bike, 500.00, 10, 5]
[3, bow, 600.00, 4, 1]
[5, diving suit, 300.00, 8, 2]
--- SQL injection attempt with a parameter
    SQL> select count(*)
    SQL> from articles
    SQL> where name = ?
    SQL> -- parameter 1 = x' or '1'='1
0 article(s) found
--- the same attempt with a string template
    SQL> select count(*)
    SQL> from articles
    SQL> where name = 'x' or '1'='1'
6 article(s) found
--- createNativeQuery: values
    SQL> select name
    SQL> from articles
    SQL> where currentStock < minimumStock
out of stock: arrows - set of 6
    SQL> select sum(price * currentStock)
    SQL> from articles
value of the stock: 12300.00 euros
--- createNativeMutationQuery
    SQL> -- start of transaction
    SQL> update articles
    SQL> set price = price * ?
    SQL> where name = ?
    SQL> -- parameter 1 = 0.9
    SQL> -- parameter 2 = bow
    SQL> -- transaction committed (COMMIT)
1 row(s) modified
--- doWork: the JDBC connection
bow : 540.00 euros

说明:

  • 第 17–24 行:[createNativeQuery] 执行一个返回实体表中各行的查询(SQL),第二个参数([Article::class.java])指示 Hibernate 把它们具体化为由会话管理的实体。结果中的列名必须与模型中的列名一致:这里适合使用 [select *] 。查询写成原始字符串(["""]),其中的公共缩进由 [trimIndent] 去除(第 5 章)。它被原样传给 DBMS(第 3–6 行),只是名为 [:minPrice] 的参数变成了 JDBC 参数([?]);
  • 第 29–34 行:一次 SQL 注入尝试。[name] 的值作为参数传递:它被原样与 [name] 列比较,没有任何商品匹配(第 16 行);
  • 第 37–38 行:使用 字符串模板 (['$name'])构造的同一个查询。模板在 Kotlin 中如此方便,以至于很容易用它来构建查询:这是一个严重的错误。[name] 的值变成了 SQL 代码,条件恒为真(第 20 行),查询返回六个商品(第 21 行):这是一次成功的 SQL 注入。与第 10 章一样,原生查询只能包含常量文本,值要作为参数传递;
  • 第 43–52 行:返回单个值的查询([String]、[BigDecimal]):此时 [createNativeQuery] 的第二个参数是值的类型。对于多列,可以指定一个数据类(其构造函数按顺序接收各列),或者使用 [Array<Any>::class.java];
  • 第 56–65 行:[createNativeMutationQuery] 准备一条更新语句,由 [executeUpdate] 执行,它返回被修改的行数。它在事务中运行:会话的 [fromTransaction] 方法开启事务、提交事务,并返回 lambda 的结果。lambda 接收事务作为参数;由于它没有使用该参数,因此该参数命名为 [_];
  • 第 71–77 行:[doWork] 提供对会话的 JDBC 连接([java.sql.Connection])的访问,用于标准 JDBC 代码(第 10 章):调用存储过程、使用驱动程序的某项功能……其中包含函数 [use],它关闭语句([Statement])和 [ResultSet]。弓的价格确实已降低了 10%(第 40 行)。

关于第 71 行的说明:这里显式指定了 lambda 参数的类型([connection: Connection]),这在 Kotlin 中不是标准做法。如果不指定,编译器会拒绝该程序:

error: type annotation class 'org.checkerframework.checker.nullness.qual.UnknownKeyFor' of the inferred type is inaccessible. Check the module classpath for missing or conflicting dependencies.

lambda 所实现的 Hibernate 接口 [Work]在其参数类型上带有来自 Checker Framework 库的 类型注解 ;Hibernate 开发人员用这些注解来验证其代码中 [null] 的使用。这个库不属于 Hibernate 的依赖项;因此,编译器不认识它的注解,并拒绝推断带有这些注解的类型。通过自己指定参数的类型,我们避开了推断,也就避开了错误。从 Kotlin 使用 Java 库时有时会出现这类问题:Java 代码本身会忽略这些注解。

原生查询无法在不同 DBMS 之间移植,Hibernate 也无法在执行之前对其进行验证:它只用于 HQL 不够用的情形。事实上,HQL 涵盖了 SQL 的很大一部分(各种连接、子查询、窗口函数、[union]……),并且允许调用它不认识的 DBMS 函数。

11.13. 批量更新、只读模式和批处理

跟踪变更是有代价的:要提高 100 个商品的价格,必须读取全部 100 个商品,逐一修改,而会话同步时会发送 100 条 [UPDATE] 命令。Hibernate 提供了几种高效处理大量行的方式。[bulkupdate] 子项目介绍了它们:

package bulkupdate

import articles.Article
import articles.BaseArticles
import java.math.BigDecimal

// 批量处理:HQL 的 update/delete 语句、只读、无状态会话和批处理
fun main() {
    BaseArticles.createSessionFactory().use { sessionFactory ->
        // [articles] 表被重新创建,含六件商品
        BaseArticles.initialize(sessionFactory)
        sessionFactory.openSession().use { session ->
            var transaction = session.beginTransaction()

            // 1 - HQL update:单条 UPDATE 语句,不把任何实体加载到内存
            println("--- restocking the articles that are out of stock")
            var nbRows = session
                .createMutationQuery(
                    """
                    update Article set currentStock = minimumStock * 2
                    where currentStock < minimumStock""".trimIndent()
                )
                .executeUpdate()
            println("$nbRows article(s) modified")

            println("--- 10 % increase of the prices below 150 euros")
            nbRows = session
                .createMutationQuery("update Article set price = price * 1.1 where price < 150")
                .executeUpdate()
            println("$nbRows article(s) modified")

            // 2 - HQL delete:单条 DELETE 语句
            println("--- deletion of the articles over 550 euros")
            nbRows = session
                .createMutationQuery("delete from Article where price > 550")
                .executeUpdate()
            println("$nbRows article(s) deleted")
            transaction.commit()

            // 3 - 只读:读取的实体不被跟踪
            println("--- read-only")
            transaction = session.beginTransaction()
            val articles = session
                .createSelectionQuery("from Article order by id", Article::class.java)
                .setReadOnly(true)
                .resultList
            articles.forEach { println(it) }
            // 对只读实体的修改被忽略
            articles.first().price = BigDecimal.ZERO
            println("session modified: ${session.isDirty}")
            transaction.commit()

            // 4 - HQL update 语句不会修改会话已经加载的实体
            println("--- HQL update and loaded entities")
            transaction = session.beginTransaction()
            val pump = session.find(Article::class.java, 2)
            session.createMutationQuery("update Article set price = 9.5 where id = :id")
                .setParameter("id", pump.id)
                .executeUpdate()
            println("price in memory: ${pump.price}")
            session.refresh(pump)
            println("price after refresh: ${pump.price}")
            transaction.commit()
        }

        // 5 - 无状态会话(StatelessSession)和分批发送的语句
        println("--- StatelessSession and batches of 3 statements")
        sessionFactory.inStatelessTransaction { session ->
            session.jdbcBatchSize = 3
            val articles = session
                .createSelectionQuery("from Article order by id", Article::class.java)
                .resultList
            for (article in articles) {
                article.currentStock += 1
                // 每次修改都需要显式请求:实体不被跟踪
                session.update(article)
            }
        }
    }
}

结果(重复的结尾部分已省略):

> gradlew -q :bulkupdate:run
    SQL> -- start of transaction
--- restocking the articles that are out of stock
    SQL> update articles a1_0
    SQL> set currentStock=(a1_0.minimumStock*2)
    SQL> where a1_0.currentStock<a1_0.minimumStock
1 article(s) modified
--- 10 % increase of the prices below 150 euros
    SQL> update articles a1_0
    SQL> set price=(a1_0.price*1.1)
    SQL> where a1_0.price<150
3 article(s) modified
--- deletion of the articles over 550 euros
    SQL> delete a1_0
    SQL> from articles a1_0
    SQL> where a1_0.price>550
1 article(s) deleted
    SQL> -- transaction committed (COMMIT)
--- read-only
    SQL> -- start of transaction
    SQL> select a1_0.id, a1_0.currentStock, a1_0.minimumStock, a1_0.name, a1_0.price
    SQL> from articles a1_0
    SQL> order by a1_0.id
[1, bike, 500.00, 10, 5]
[2, pump, 11.00, 10, 2]
[4, arrows - set of 6, 110.00, 40, 20]
[5, diving suit, 300.00, 8, 2]
[6, diver's oxygen tanks, 132.00, 10, 5]
session modified: false
    SQL> -- transaction committed (COMMIT)
--- HQL update and loaded entities
    SQL> -- start of transaction
    SQL> update articles a1_0
    SQL> set price=9.5
    SQL> where a1_0.id=?
    SQL> -- parameter 1 = 2
price in memory: 11.00
    SQL> select a1_0.id, a1_0.currentStock, a1_0.minimumStock, a1_0.name, a1_0.price
    SQL> from articles a1_0
    SQL> where a1_0.id=?
    SQL> -- parameter 1 = 2
price after refresh: 9.50
    SQL> -- transaction committed (COMMIT)
--- StatelessSession and batches of 3 statements
    SQL> -- start of transaction
    SQL> select a1_0.id, a1_0.currentStock, a1_0.minimumStock, a1_0.name, a1_0.price
    SQL> from articles a1_0
    SQL> order by a1_0.id
    SQL> update articles
    SQL> set currentStock=?, minimumStock=?, name=?, price=?
    SQL> where id=?
    SQL> -- parameter 1 = 11
    SQL> -- parameter 2 = 5
    SQL> -- parameter 3 = bike
    SQL> -- parameter 4 = 500.00
    SQL> -- parameter 5 = 1
...
    SQL> -- execution of a batch of 3 statement(s)
    SQL> update articles
    SQL> set currentStock=?, minimumStock=?, name=?, price=?
    SQL> where id=?
...
    SQL> -- execution of a batch of 2 statement(s)
    SQL> -- transaction committed (COMMIT)

说明:

  • 第 17–23 行:一条以 HQL 编写的 [update] 命令,由 [createMutationQuery] 准备,并由 [executeUpdate] 执行。它变成一条单独的 SQL [UPDATE] 语句(第 4–6 行),由 DBMS 对所有受影响的行执行,而不会把任何实体加载到内存中。新值可以取决于该行本身([minimumStock * 2])。这样的命令在事务中执行(第 2 行和第 18 行);
  • 第 27–29 行:对低价商品涨价 10%。HQL 查询的常量([1.1]、[150])被直接写入 SQL 命令的文本中(第 10–11 行);
  • 第 34–36 行:一条 [delete] HQL 语句删除了弓,这是唯一价格超过 550 欧元的商品(第 14–16 行);
  • 第 43–50 行:一次 只读 操作([setReadOnly(true)])。被读取的实体由会话管理,但会话不会保留它们的原始状态,也不会监视它们:对于只读取而不修改的数据(显示、计算),这样更快,也更节省内存。代价是,对此类实体的任何修改都会被忽略(第 49 行):会话没有需要同步的内容([session.isDirty] 等于 [false],第 29 行),[commit] 也不会发送任何命令。还可以把整个会话设为只读([session.isDefaultReadOnly = true]);
  • 第 56–62 行:一个陷阱。像 [update] HQL 这样的命令直接作用于数据库:它不会修改会话已加载的实体。由会话管理的气泵保留其旧价格(第 37 行),直到用 [session.refresh(pump)] 重新读取它(第 38–42 行);
  • 第 68–76 行:一个 无状态会话 ([StatelessSession]),这里通过 [inStatelessTransaction] 连同事务一起打开。它没有持久化上下文:没有一级缓存、没有变更跟踪、没有懒加载,也没有级联。每个操作都要显式请求([insert]、[update]、[delete]、[get])并按原样执行。这是用于批量处理的工具:导入大文件、重新计算表中的所有行;
  • 第 69 行:SQL 命令将以每批三条(见第 10 章)的方式发送给 DBMS:JDBC 驱动程序在与服务器的一次交互中传输三条命令。在 Kotlin 中,[getJdbcBatchSize]/[setJdbcBatchSize] 这一对方法被当作属性使用。日志显示前三条 [UPDATE] 记录,随后是该批的执行(第 58 行),最后是由两条命令组成的最后一批(第 63 行)。应用程序通过 [hibernate.jdbc.batch_size] 属性为其所有会话设置批大小(通常在 10 到 50 之间)。请注意,向主键由 [IDENTITY] 生成的表中插入数据时,无法分组成批。

对于使用常规会话的批量处理,必须防止其持久化上下文不断累积实体:定期同步并清空会话,例如每五十条记录一次([session.flush(); session.clear()])。在 Kotlin 中,用于序列和集合的 [chunked] 函数(第 5 章)可以方便地把数据拆分成这种大小的块。

11.14. Hibernate 与依赖注入:Spring

11.14.1. 容器中的 [SessionFactory]

前面的示例都是自己创建会话。在分层应用程序(第 6 章)以及所有 Spring 应用程序中,[SessionFactory] 是依赖注入容器中的一个对象,就像使用它的各层一样。为此,Spring Framework 在其 [spring-orm] 库中提供了:

  • [LocalSessionFactoryBean] 类,它根据数据源([DataSource],第 10 章)和实体列表构造 [SessionFactory];
  • [HibernateTransactionManager] 类,一个事务管理器,它为每个事务打开一个 Hibernate 会话,把它与当前线程关联,并在事务结束时关闭它;
  • [@Transactional] 注解(库 [spring-tx]):应用于方法,或应用于类(作用于其所有公共方法)时,它指示 Spring 在事务中执行该方法,方法正常结束则提交事务,抛出未捕获的异常则回滚。这称为 声明式 事务。关于 Kotlin 有一点说明:默认情况下,对于 Java 所定义的 受检 异常(例如 [IOException]),Spring 不会回滚事务。Kotlin 不区分这些异常与其他异常,但 Spring 会区分:在事务方法中抛出 [IOException] 的 Kotlin 函数,其事务会被提交!因此我们写成 [@Transactional(rollbackFor = [Exception::class])] ,以确保在所有情况下都回滚事务。

在事务方法内部,***[sessionFactory.currentSession]***(*[getCurrentSession] 方法)返回当前事务的会话。[dao] 层于是可以是一个单例,它接收(线程安全的)[SessionFactory] ,并在每个方法中向它请求当前会话:“每个工作单元一个会话,绝不在线程之间共享”这条规则就毫不费力地得到了落实。不过,使用协程时要小心:当前会话与 线程 关联,而在事务中途切换线程的挂起函数会丢失其会话。因此,我们保留阻塞式的事务方法,并在 [withContext(Dispatchers.IO)] 块中从协程调用它们,如示例 [async]* 所示。

11.14.2. [injection] 子项目

[injection] 子项目除 [articles] 库之外,还依赖 Spring 和 HikariCP:

// Hibernate 与依赖注入:Spring ORM 和声明式事务
plugins {
    kotlin("jvm")
    // 使 Spring 注解的类成为 open(@Configuration、@Transactional……)
    kotlin("plugin.spring")
    application
}

repositories {
    mavenCentral()
}

dependencies {
    // [Article] 实体和 [hbarticles] 数据库(包含 Hibernate、MySQL 和 SQL 日志)
    implementation(project(":articles"))
    // Spring:容器、声明式事务、Hibernate 集成
    implementation("org.springframework:spring-context:7.0.9")
    implementation("org.springframework:spring-orm:7.0.9")
    // HikariCP 连接池
    implementation("com.zaxxer:HikariCP:7.0.2")
}

kotlin {
    jvmToolchain(25)
    compilerOptions {
        allWarningsAsErrors = true
        javaParameters = true
    }
}

application {
    // 由 [gradlew -q :injection:run] 运行的程序
    mainClass = "injection.MainKt"
}

// 在 Windows 上,由 Gradle(run、bootRun 等)启动的程序的屏幕输出以 UTF-8 编码,
// 否则带重音符号的字符在 IntelliJ IDEA 控制台或终端中会出现乱码
tasks.withType<JavaExec>().configureEach {
    jvmArgs("-Dstdout.encoding=UTF-8", "-Dstderr.encoding=UTF-8")
}
  • 第 5 行:为 Spring 配置的 [all-open] 插件(第 6 章)。它使带有 [@Configuration] 注解的类,以及带有 [@Transactional] 和其他一些注解([@Component]、[@Service]、[@Async]……)的类及其方法成为 open 的。我们将看到为什么这至关重要;
  • 第 15 行:[Article] 实体和 [hbarticles] 数据库(包括 Hibernate、MySQL 和 SQL 日志);
  • 第 17–18 行:Spring 容器与 Hibernate 的集成;[spring-orm] 包含事务库 [spring-tx];
  • 第 19 行:HikariCP 连接池(第 10 章);
  • 第 36–39 行:由 Gradle 启动的程序以 UTF-8 输出,以便带重音符号的字符在 Windows 上正确显示(第 2 章)。

Spring 配置用 Kotlin 编写,使用第 6 章中的注解 [@Configuration] 和 [@Bean] :

package injection

import articles.Article
import articles.BaseArticles
import com.zaxxer.hikari.HikariDataSource
import java.util.Properties
import javax.sql.DataSource
import org.hibernate.SessionFactory
import org.hibernate.cfg.AvailableSettings
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration
import org.springframework.orm.jpa.hibernate.HibernateTransactionManager
import org.springframework.orm.jpa.hibernate.LocalSessionFactoryBean
import org.springframework.transaction.annotation.EnableTransactionManagement

// Spring 配置:连接池、SessionFactory、事务管理器、[dao] 层
@Configuration
@EnableTransactionManagement
class Config {

    // HikariCP 连接池(第 10 章)
    @Bean(destroyMethod = "close")
    fun dataSource() = HikariDataSource().apply {
        jdbcUrl = BaseArticles.URL
        username = BaseArticles.USER
        password = BaseArticles.PASSWORD
    }

    // SessionFactory,由 Spring 使用连接池构建
    @Bean
    fun sessionFactory(dataSource: DataSource) = LocalSessionFactoryBean().apply {
        setDataSource(dataSource)
        setAnnotatedClasses(Article::class.java)
        hibernateProperties = Properties().apply { put(AvailableSettings.FORMAT_SQL, "true") }
    }

    // 事务管理器:每个事务一个 Hibernate 会话
    @Bean
    fun transactionManager(sessionFactory: SessionFactory) = HibernateTransactionManager(sessionFactory)

    // [dao] 层:一个接收 SessionFactory 的单例
    @Bean
    fun articlesDao(sessionFactory: SessionFactory) = ArticlesDao(sessionFactory)
}
  • 第 18 行:启用 [@Transactional] 注解:Spring 会把每个带有此注解的方法的对象替换为一个代理,由该代理在调用前后开启并提交事务;
  • 第 22–26 行:第 10 章中的 HikariCP 连接池,在 [apply] 块中配置:修改器 [setJdbcUrl]、[setUsername] 和 [setPassword] 被当作属性使用。属性 [destroyMethod] 指定容器关闭时要调用的方法。该函数推断出的返回类型是 [HikariDataSource]:Spring 就以这个类型注册该 bean;
  • 第 31–34 行:[SessionFactory]。*[LocalSessionFactoryBean] 是 *[SessionFactory]* 的工厂:Spring 把它生产的对象注册到容器中,请求这个 bean 所得到的就是一个 *[SessionFactory] 。它接收连接池(取代 Hibernate 内置的连接池)、实体和 Hibernate 属性。我们写 [setDataSource(dataSource)] 而不是 [dataSource = dataSource],后者会把参数赋值给它自己(并且会被拒绝,因为参数是只读的);
  • 第 39 行:事务管理器;
  • 第 43 行:[dao] 层,它接收 [SessionFactory]。

[dao] 层:

package injection

import articles.Article
import org.hibernate.Session
import org.hibernate.SessionFactory
import org.springframework.transaction.annotation.Transactional

// [dao] 层:每个公共方法都在 Spring 打开的事务中运行
@Transactional
class ArticlesDao(
    // SessionFactory,由所有线程共享
    private val sessionFactory: SessionFactory
) {

    // 在同一个事务中,两次请求当前会话会返回同一个会话吗?
    fun sameSession() = sessionFactory.currentSession === sessionFactory.currentSession

    // 事务的会话
    fun session(): Session = sessionFactory.currentSession

    // 需要补货的商品;一个只读事务
    @Transactional(readOnly = true)
    fun articlesOutOfStock(): List<String> {
        val hql = "select name from Article where currentStock < minimumStock"
        return sessionFactory.currentSession.createSelectionQuery(hql, String::class.java).resultList
    }

    // 具有给定名称的商品
    @Transactional(readOnly = true)
    fun article(name: String): Article =
        sessionFactory.currentSession
            .createSelectionQuery("from Article where name = :name", Article::class.java)
            .setParameter("name", name)
            .singleResult

    // 出售某件商品的一定数量:异常会回滚事务
    fun sell(name: String, quantity: Int) {
        val article = article(name)
        article.currentStock -= quantity
        // 如果条件为 false,check 会抛出 IllegalStateException
        check(article.currentStock >= 0) { "insufficient stock for the article [$name]" }
    }
}
  • 第 9 行:该类的所有公共方法都是事务性的;
  • 第 12 行:[SessionFactory],由主构造函数接收;
  • 第 16 行:在同一个事务中,对当前会话的两次请求返回的是同一个会话吗?[===] 运算符比较引用(第 3 章);
  • 第 19 行:事务的会话,返回给调用者(用于后面的实验:在真实的应用程序中不会这样做);
  • 第 22–25 行:一个只读事务([readOnly = true]):Spring 把会话设为只读,并且不对其进行同步;
  • 第 37–41 行:卖出一定数量的某个商品。如果库存变为负数,Kotlin 函数 [check] (第 3 章)会抛出 [IllegalStateException],这是一个未处理的异常:Spring 回滚事务。对 [article] 方法的调用(第 38 行)是对象内部的调用,不经过代理:它在 [sell] 事务中执行。

Spring 为 [ArticlesDao] 类创建的代理是它的一个 子类 ,由 CGLIB 库在运行时生成,它重新定义每个公共方法,以便用事务把它包装起来。如果没有 [plugin.spring] 插件,Kotlin 类就会是 final 的,Spring 也就无法从它派生。如果在没有该插件的情况下编译子项目(手动声明 [Config] 类及其 [open] 函数,以绕过我们在第 6 章中已经遇到的第一个错误),容器会拒绝启动:

1
2
3
Exception in thread "main" org.springframework.beans.factory.BeanCreationException: Error creating bean with name 'articlesDao' defined in injection.Config: Could not generate CGLIB subclass of class injection.ArticlesDao: Common causes of this problem include using a final class or a non-visible class
Caused by: org.springframework.aop.framework.AopConfigException: Could not generate CGLIB subclass of class injection.ArticlesDao: Common causes of this problem include using a final class or a non-visible class
Caused by: java.lang.IllegalArgumentException: Cannot subclass final class injection.ArticlesDao

对于手动把类设为 open([open class ArticlesDao])却不把它的方法设为 open 的人,还有一个更隐蔽的陷阱:此时代理会被创建,但它无法重写仍是 final 的方法。直接调用这些方法时,会在代理对象上执行 [ArticlesDao]……类的代码,而代理对象的字段尚未初始化(Spring 创建它时不会调用该类的构造函数)。以这种方式编译子项目所得到的结果令人困惑:

--- sessions and transactions
Exception in thread "main" java.lang.NullPointerException: Cannot invoke "org.hibernate.SessionFactory.getCurrentSession()" because "this.sessionFactory" is null

不可为空类型的属性 [sessionFactory] 竟被设为 [null]!该插件可以避免这两个错误:有了它,类及其所有方法都是 open 的。

主程序:

package injection

import articles.BaseArticles
import org.hibernate.HibernateException
import org.hibernate.SessionFactory
import org.springframework.beans.factory.getBean
import org.springframework.context.annotation.AnnotationConfigApplicationContext

// Spring 容器中的 Hibernate:当前会话和声明式事务
fun main() {
    // 由 [Config] 类配置的 Spring 容器
    AnnotationConfigApplicationContext(Config::class.java).use { context ->
        // [articles] 表被重新创建,含六件商品
        val sessionFactory = context.getBean<SessionFactory>()
        BaseArticles.initialize(sessionFactory)
        val dao = context.getBean<ArticlesDao>()

        // 1 - 在一个事务期间,当前会话始终是同一个
        println("--- sessions and transactions")
        println("one transaction: same session = ${dao.sameSession()}")
        // 2 - 两个事务:两个会话,在各自事务结束时关闭
        val session1 = dao.session()
        val session2 = dao.session()
        println("two transactions: same session = ${session1 === session2}, " +
                "first session open = ${session1.isOpen}")
        // 3 - 在事务之外,没有当前会话
        try {
            sessionFactory.currentSession
        } catch (e: HibernateException) {
            println("${e::class.simpleName} : ${e.message}")
        }

        // 4 - [dao] 层的事务性方法
        println("--- articles out of stock")
        println("out of stock: ${dao.articlesOutOfStock()}")
        println("--- sale of 2 bikes")
        dao.sell("bike", 2)
        println("--- sale of 50 pumps")
        try {
            dao.sell("pump", 50)
        } catch (e: IllegalStateException) {
            println("${e::class.simpleName} : ${e.message}")
        }
        println("--- state of the database")
        println(dao.article("bike"))
        println(dao.article("pump"))
    }
}

结果:

> gradlew -q :injection:run
--- sessions and transactions
    SQL> -- start of transaction
    SQL> -- transaction committed (COMMIT)
one transaction: same session = true
    SQL> -- start of transaction
    SQL> -- transaction committed (COMMIT)
    SQL> -- start of transaction
    SQL> -- transaction committed (COMMIT)
two transactions: same session = false, first session open = false
HibernateException : Could not obtain transaction-synchronized Session for current thread
--- articles out of stock
    SQL> -- start of transaction
    SQL> select a1_0.name
    SQL> from articles a1_0
    SQL> where a1_0.currentStock<a1_0.minimumStock
    SQL> -- transaction committed (COMMIT)
out of stock: [arrows - set of 6]
--- sale of 2 bikes
    SQL> -- start of transaction
    SQL> select a1_0.id, a1_0.currentStock, a1_0.minimumStock, a1_0.name, a1_0.price
    SQL> from articles a1_0
    SQL> where a1_0.name=?
    SQL> -- parameter 1 = bike
    SQL> update articles
    SQL> set currentStock=?, minimumStock=?, name=?, price=?
    SQL> where id=?
    SQL> -- parameter 1 = 8
    SQL> -- parameter 2 = 5
    SQL> -- parameter 3 = bike
    SQL> -- parameter 4 = 500.00
    SQL> -- parameter 5 = 1
    SQL> -- transaction committed (COMMIT)
--- sale of 50 pumps
    SQL> -- start of transaction
    SQL> select a1_0.id, a1_0.currentStock, a1_0.minimumStock, a1_0.name, a1_0.price
    SQL> from articles a1_0
    SQL> where a1_0.name=?
    SQL> -- parameter 1 = pump
    SQL> -- transaction rolled back (ROLLBACK)
IllegalStateException : insufficient stock for the article [pump]
--- state of the database
    SQL> -- start of transaction
    SQL> select a1_0.id, a1_0.currentStock, a1_0.minimumStock, a1_0.name, a1_0.price
    SQL> from articles a1_0
    SQL> where a1_0.name=?
    SQL> -- parameter 1 = bike
    SQL> -- transaction committed (COMMIT)
[1, bike, 500.00, 8, 5]
    SQL> -- start of transaction
    SQL> select a1_0.id, a1_0.currentStock, a1_0.minimumStock, a1_0.name, a1_0.price
    SQL> from articles a1_0
    SQL> where a1_0.name=?
    SQL> -- parameter 1 = pump
    SQL> -- transaction committed (COMMIT)
[2, pump, 10.00, 10, 2]

说明:

  • 第 12 行:Spring 容器,由 [Config] 类配置。它在 [use] 块的末尾关闭,该块会关闭 [SessionFactory] 和连接池;
  • 第 14 行:由 Spring 构造的 [SessionFactory] ,通过 Spring 的 [getBean<T>()] 扩展函数获得(第 6 章);它用于重新创建商品表;
  • 第 20 行:一个事务(第 3–4 行):在同一个事务中,当前会话保持不变(第 5 行);
  • 第 22–25 行:两次调用,两个事务(第 6–9 行),两个不同的会话;第一个会话已关闭,因为它的事务已经完成(第 10 行)。属性 [isOpen] 就是会话的方法 [isOpen()];
  • 第 28–29 行:在事务之外,没有当前会话:[getCurrentSession] 抛出 [HibernateException] (第 11 行)。这是遗漏了注解 [@Transactional] 的方法所犯的典型错误;
  • 第 35 行:一个只读事务(第 13–17 行);
  • 第 37 行:卖出两辆自行车。事务被提交,会话同步发送 [UPDATE] (第 20–33 行);
  • 第 40–41 行:卖出五十个气泵会触发异常:Spring 回滚事务(第 40 行),而且 [UPDATE] 从未被发送,因为会话没有被同步;
  • 第 45–46 行:数据库状态:自行车库存变成了 8,而气泵库存仍为 10(第 49 行和第 56 行)。

在 Spring Boot 应用程序中,所有这些都是自动发生的:Spring Boot 根据 [application.properties] 文件创建连接池、工厂(其 Jakarta Persistence 形式,即 [EntityManagerFactory])和事务管理器。Spring Data JPA 经常用在 Hibernate 之上;它根据一个简单的接口生成 [dao] 层:[interface ArticleRepository : JpaRepository<Article, Int>] 提供 [findAll]、[findById]、[save]、[delete]……,而声明的方法 [fun findByPriceLessThan(price: BigDecimal): List<Article>] 会被自动翻译成查询。Spring Data 为 Kotlin 增加了一些扩展函数,例如 [findByIdOrNull],它返回 [Article?] 而不是 [Optional<Article>]。

11.15. 示例应用程序 - 版本 7

11.15.1. 架构

税款计算应用程序的版本 6(第 10 章)使用 JDBC 从 MySQL 数据库读取税率档。版本 7 使用 Hibernate 完成同样的工作。与版本 6 一样,只有 [dao] 层发生变化:得益于组合式架构,版本 5(第 6 章)中的 [business] 层和 [ui] 层原样复用。

Image

版本 7 由第 11 章结构中的两个子项目组成,存放在 [TaxV7] 文件夹中:

11-hibernate/
  settings.gradle.kts                   the subprojects and the included build (chapter 6)
  TaxV7/
    tax-dao-hibernate/                  library: the Hibernate [dao] layer
      build.gradle.kts
      src/main/kotlin/tax/dao/
        Bracket.kt                      the entity
        HibernateTax.kt                 the implementation of ITaxDao
        CreateDatabase.kt               the creation of the [hbtaxes] database
      src/main/resources/
        logback.xml
    tax-ui-hibernate/                   executable: integration of the layers
      build.gradle.kts
      src/main/kotlin/tax/ui/
        MainHibernate.kt
      tax-hibernate.properties
      tax-hibernate-error.properties

[TaxV7] 文件夹没有构建文件:就像第 6 章中的 [TaxV5] 文件夹一样,它只是子项目的集合。版本 5 的模块([tax-dao], [tax-business], [tax-ui],版本 5.0)由第 6 章的构建提供,通过文件 [settings.gradle.kts] 中的 [includeBuild("../06-architectures")] 这一行引入:Gradle 会把每个 [examples.tax:tax-xxx:5.0] 依赖替换为该构建中对应的子项目,并在需要时编译它。无需事先安装任何东西,这与 Maven 不同,在 Maven 中必须先在版本 5 的文件夹中输入 [mvn install] 。

11.15.2. [dao] 层

[tax-dao-hibernate] 子项目依赖版本 5 的 [dao] 层,该层包含应用程序的实体([TaxBracket]、[TaxException])和 [ITaxDao] 接口:

// TaxV7:tax-dao-hibernate 子项目,一个库(用 Hibernate 编写的 [dao] 层)
plugins {
    kotlin("jvm")
    // [Bracket] 实体:[jpa] 和 [allopen] 插件
    kotlin("plugin.jpa")
    kotlin("plugin.allopen")
    // 库插件:它添加 [api] 配置
    `java-library`
    // [gradlew -q :TaxV7:tax-dao-hibernate:run] 创建 [hbtaxes] 数据库
    application
}

// 库的坐标:examples.tax:tax-dao-hibernate:7.0
group = "examples.tax"
version = "7.0"

repositories {
    mavenCentral()
}

dependencies {
    // 第 5 版(第 6 章)的 [dao] 层:实体、ITaxDao 接口、HardwiredTax
    api("examples.tax:tax-dao:5.0")
    // Hibernate、MySQL JDBC 驱动和 Logback
    implementation("org.hibernate.orm:hibernate-core:7.4.5.Final")
    runtimeOnly("com.mysql:mysql-connector-j:9.7.0")
    runtimeOnly("ch.qos.logback:logback-classic:1.5.38")
}

// 以这种方式标注的类由 [allopen] 插件打开
allOpen {
    annotation("jakarta.persistence.Entity")
    annotation("jakarta.persistence.MappedSuperclass")
    annotation("jakarta.persistence.Embeddable")
}

kotlin {
    jvmToolchain(25)
    compilerOptions {
        allWarningsAsErrors = true
        javaParameters = true
    }
}

application {
    // 创建 [hbtaxes] 数据库
    mainClass = "tax.dao.CreateDatabaseKt"
}

// 在 Windows 上,由 Gradle(run、bootRun 等)启动的程序的屏幕输出以 UTF-8 编码,
// 否则带重音符号的字符在 IntelliJ IDEA 控制台或终端中会出现乱码
tasks.withType<JavaExec>().configureEach {
    jvmArgs("-Dstdout.encoding=UTF-8", "-Dstderr.encoding=UTF-8")
}
  • 第 5–6 行:实体插件:该子项目定义了实体 [Bracket];
  • 第 8 行:该子项目是一个库,通过配置 [api] 公开其部分依赖项;
  • 第 10 行:[application] 插件,用于创建数据库(第 47 行);
  • 第 23 行:版本 5 的 [dao] 层。这是对 [api] 的依赖:类 [HibernateTax] 实现了该库中的接口 [ITaxDao] ,因此其使用者也必须能看到它;
  • 第 25–27 行:Hibernate、MySQL 的 JDBC 驱动程序和 Logback。Hibernate 是 [implementation] 类型的依赖:它在库内部使用,但不出现在其公共接口中;
  • 第 31–34 行:[allopen] 插件的标准配置;
  • 第 50–53 行:由 Gradle 启动的程序以 UTF-8 输出,以便带重音符号的字符在 Windows 上正确显示(第 2 章)。

版本 5 中的数据类 [TaxBracket] 不能作为 Hibernate 实体:它是数据类(我们已经看到为什么这对实体不是个好主意),它是不可变的,而且没有标识符。我们不修改它,因为它是各层之间契约的一部分,被所有版本共享。我们创建一个专属于 [dao] 层的实体,其作用是表示表中的一行:

// 存储在数据库中的税率档:一个 Hibernate 实体
@Entity
@Table(name = "brackets")
class Bracket(
    @Column(name = "limits", nullable = false, precision = 10, scale = 2)
    private var limit: BigDecimal,

    @Column(name = "coeffr", nullable = false, precision = 6, scale = 4)
    private var coeffR: BigDecimal,

    @Column(name = "coeffn", nullable = false, precision = 10, scale = 2)
    private var coeffN: BigDecimal,
) {
    // 主键,TaxBracket 类中不存在它
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private var id: Int? = null
}
  • 第 3 行:表 [brackets];
  • 第 6–12 行:三个列,在主构造函数中声明,具有合适的 [decimal] 类型:上限和系数 [coeffN] 是带两位小数的金额,而 [coeffR] 是带四位小数的比率。列名使用小写。这些属性是私有的:该实体只用于填充表([CreateDatabase])和编写查询;应用程序的其余部分永远看不到它。直接访问字段的 Hibernate 并不要求它们是公共的;
  • 第 15–17 行:主键,同时也用于对税率档排序。

类 [HibernateTax] 实现了接口 [ITaxDao]:

package tax.dao

import tax.entities.TaxException
import tax.entities.TaxBracket
import jakarta.persistence.PersistenceException
import org.hibernate.jpa.HibernatePersistenceConfiguration

// 一个用 Hibernate 从数据库读取税率档的 [dao] 层
class HibernateTax(url: String, user: String, password: String) : ITaxDao {

    companion object {
        // 特定于此实现的错误码
        const val ACCESS_ERROR = 1
        const val EMPTY_TABLE = 2
    }

    // 税率档,在构造时一次性读取
    override val taxBrackets: List<TaxBracket> = try {
        // 一个短命的 SessionFactory,只存活到读完表为止
        HibernatePersistenceConfiguration("tax")
            .managedClass(Bracket::class.java)
            .jdbcUrl(url)
            .jdbcCredentials(user, password)
            .createEntityManagerFactory()
            .use { sessionFactory ->
                // 表的行被投影到应用程序的 TaxBracket 类
                val hql = "select b.limit, b.coeffR, b.coeffN from Bracket b order by b.id"
                sessionFactory.fromSession { session ->
                    session.createSelectionQuery(hql, TaxBracket::class.java).resultList
                }
            }
    } catch (e: PersistenceException) {
        // Hibernate 或 DBMS 错误:它被包装在 TaxException 中
        throw TaxException("Error while reading the tax brackets from the database",
            e, ACCESS_ERROR)
    }

    init {
        // [business] 层至少需要一个税率档
        if (taxBrackets.isEmpty()) {
            throw TaxException("The tax brackets table is empty", code = EMPTY_TABLE)
        }
    }
}
  • 第 11–14 行:该实现的错误代码,与 [FileTax] 和 [JsonTax] 中的一样;
  • 第 9 行:[dao] 层接收数据库的 URL,以及用户名和密码。它们只是构造函数的参数([val] 没有写:它们不会成为属性,因为只在构造时使用)。它在构造期间一次性读取税率档:它将是一个单例;
  • 第 18 行:属性 [taxBrackets] (接口 [ITaxDao] 的属性)由 [try] 表达式(第 3 章)初始化:其值就是 [try] 块的值;如果发生错误,[catch] 会抛出异常;
  • 第 20–25 行:一个短暂存在的 [SessionFactory]——存活时间刚好够读取该表——由 [use] 立即关闭。由于该层只访问一次数据库,因此无需保留它;而每次调用都访问数据库的 [dao] 层则应当接收一个一次性创建好的 [SessionFactory] ,如前面的示例所示;
  • 第 27–29 行:按主键顺序读取表。该查询是向数据类 [TaxBracket] 的投影:Hibernate 只向 DBMS 请求这三个相关的列,并通过用这三个值调用 *[TaxBracket] 的构造函数直接创建应用程序对象,而不经过 *[Bracket] 实体。[fromSession],然后 [use] 所返回的值就是读取到的列表:这就是该属性的值;
  • 第 32–35 行:来自 Hibernate 或 DBMS 的错误(数据库无法访问、表缺失等)表现为 [PersistenceException] (Jakarta Persistence 异常的基类,Hibernate 的异常都派生自它)。与其他实现一样,它被封装在 *[TaxException] 中。异常最早可能在创建 *[SessionFactory]*(第 24 行)时发生,该操作会连接服务器:它同样包含在 ***[try]** 块内;
  • 第 38–41 行:空表同样是一个错误:[business] 层要求至少有一行。[init] 块在属性初始化之后执行,而该属性在类中位于它之前。错误代码通过命名参数传递([code = EMPTY_TABLE]),因为该异常没有原因(第 6 章)。

11.15.3. 数据库

数据库 [hbtaxes] 由程序 [CreateDatabase.kt] 创建。为避免重写税率档,它复用版本 5 中类 [HardwiredTax] 的税率档:

package tax.dao

import org.hibernate.jpa.HibernatePersistenceConfiguration
import org.hibernate.tool.schema.Action

// 创建 [hbtaxes] 数据库:[brackets] 表,填入 HardwiredTax 的税率档
fun main() {
    HibernatePersistenceConfiguration("tax")
        .managedClass(Bracket::class.java)
        .jdbcUrl("jdbc:mysql://localhost:3306/hbtaxes?createDatabaseIfNotExist=true")
        .jdbcCredentials("root", "")
        // 显示 SQL 语句,不格式化
        .showSql(true, false, false)
        // 创建 SessionFactory 时,表先被删除再重新创建
        .schemaToolingAction(Action.CREATE)
        .createEntityManagerFactory()
        .use { sessionFactory ->
            // 税率表的各档,即第 5 版的那些,由 DBMS 从 1 开始编号
            sessionFactory.inTransaction { session ->
                for ((limit, coeffR, coeffN) in HardwiredTax().taxBrackets) {
                    session.persist(Bracket(limit, coeffR, coeffN))
                }
            }
        }
}
  • 第 10 行:数据库 [hbtaxes],如果不存在则由 MySQL 创建;
  • 第 13 行:显示 SQL 语句,不做格式化;
  • 第 15 行:创建 [SessionFactory] 时,表会先被删除再重新创建;
  • 第 19–21 行:每个税率档对应一个 [Bracket] 实体,针对 [HardwiredTax] 类的各档,在一个事务中持久化。[for] 循环 把每个 [TaxBracket] 分解为三个组成部分([(limit, coeffR, coeffN)]),使用的是 [component1]、[component2] 和 [component3],这些函数是为数据类生成的(第 4 章)。

子项目还包含一个名为 [logback.xml] 的文件,由 [CreateDatabase.kt] 和应用程序使用,它只放行下列错误:

<?xml version="1.0" encoding="UTF-8"?>
<!-- Logback 配置:只显示 Hibernate 错误 -->
<configuration>
    <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
        <encoder>
            <pattern>%-5level %logger{0} - %msg%n</pattern>
        </encoder>
    </appender>
    <!-- DBMS 错误通过异常传给应用程序:它们不被记录日志 -->
    <logger name="org.hibernate.orm.jdbc.error" level="OFF"/>
    <root level="ERROR">
        <appender-ref ref="CONSOLE"/>
    </root>
</configuration>
  • 第 10 行:来自 DBMS 的错误,Hibernate 在抛出异常之前会记录它们,这里不显示:应用程序自己会报告它们;
  • 第 11 行:其他日志只记录错误。

执行:

> gradlew -q :TaxV7:tax-dao-hibernate:run
Hibernate: drop table if exists brackets
Hibernate: create table brackets (coeffn decimal(10,2) not null, coeffr decimal(6,4) not null, id integer not null auto_increment, limits decimal(10,2) not null, primary key (id)) engine=InnoDB
Hibernate: insert into brackets (coeffn,coeffr,limits) values (?,?,?)
Hibernate: insert into brackets (coeffn,coeffr,limits) values (?,?,?)
Hibernate: insert into brackets (coeffn,coeffr,limits) values (?,?,?)
Hibernate: insert into brackets (coeffn,coeffr,limits) values (?,?,?)
Hibernate: insert into brackets (coeffn,coeffr,limits) values (?,?,?)
Hibernate: insert into brackets (coeffn,coeffr,limits) values (?,?,?)
Hibernate: insert into brackets (coeffn,coeffr,limits) values (?,?,?)

我们检查表的内容:

> mysql -uroot -t hbtaxes -e "SELECT id, limits, coeffr, coeffn FROM brackets"
+----+----------+--------+---------+
| id | limits   | coeffr | coeffn  |
+----+----------+--------+---------+
|  1 |  4962.00 | 0.0000 |    0.00 |
|  2 |  8382.00 | 0.0680 |  291.09 |
|  3 | 14753.00 | 0.1910 | 1322.92 |
|  4 | 23888.00 | 0.2830 | 2668.39 |
|  5 | 38868.00 | 0.3740 | 4846.98 |
|  6 | 47932.00 | 0.4260 | 6883.66 |
|  7 |     0.00 | 0.4810 | 9505.54 |
+----+----------+--------+---------+

可以看到各税率档,最后一档的上限为零([business] 层不使用它,该层在没有其他档适用时选择最后一档)。

在你自己的系统上创建数据库:

  • 运行 MySQL(在 Laragon 中;见附录;用户 [root] ,无密码);
  • 进入 [11-hibernate] 文件夹并输入命令 [gradlew -q :TaxV7:tax-dao-hibernate:run](或者在 IntelliJ IDEA 中运行 [CreateDatabase.kt] ,点击其函数 [main] 前面的绿色三角形)。Gradle 会同时编译相邻文件夹 [06-architectures] 中的版本 5 模块。

随后会创建数据库 [hbtaxes] ,并填充其表 [brackets] 。如果命令失败,请确认 MySQL 正在运行,并且 [CreateDatabase.kt] 中的 URL 与你的服务器相符(端口 3306,用户名 [root],密码为空)。或者,如果你愿意,也可以按第 10 章所述,使用 SQL 脚本创建表及其行。

11.15.4. 整合各层

[tax-ui-hibernate] 子项目组合了以下各层:

// TaxV7:tax-ui-hibernate 子项目,各层的集成
plugins {
    kotlin("jvm")
    application
}

group = "examples.tax"
version = "7.0"

repositories {
    mavenCentral()
}

dependencies {
    // 第 5 版的 [business] 层和 [ui] 层,保持不变(复合构建)
    implementation("examples.tax:tax-business:5.0")
    implementation("examples.tax:tax-ui:5.0")
    // 新的 [dao] 层,它引入 Hibernate、JDBC 驱动和 Logback
    implementation(project(":TaxV7:tax-dao-hibernate"))
    // Spring 依赖注入容器
    implementation("org.springframework:spring-context:7.0.9")
}

kotlin {
    jvmToolchain(25)
    compilerOptions {
        allWarningsAsErrors = true
        javaParameters = true
    }
}

application {
    // 主程序:gradlew -q :TaxV7:tax-ui-hibernate:run [--args="file.properties"]
    mainClass = "tax.ui.MainHibernateKt"
}

tasks.named<JavaExec>("run") {
    // 程序读取键盘
    standardInput = System.`in`
}

// 在 Windows 上,由 Gradle(run、bootRun 等)启动的程序的屏幕输出以 UTF-8 编码,
// 否则带重音符号的字符在 IntelliJ IDEA 控制台或终端中会出现乱码
tasks.withType<JavaExec>().configureEach {
    jvmArgs("-Dstdout.encoding=UTF-8", "-Dstderr.encoding=UTF-8")
}
  • 第 16–17 行:版本 5 的 [business] 层和 [ui] 层。[tax-ui] 子项目包含版本 5 的主程序;这里把它用作库,具体来说是使用它的 [Dialog] 对象;
  • 第 19 行:新的 [dao] 层,其中包含 Hibernate、JDBC 驱动程序和 Logback;
  • 第 21 行:Spring 容器;
  • 第 34 行:主类;
  • 第 37–39 行:程序从键盘读取输入(第 6 章);
  • 第 42–45 行:由 Gradle 启动的程序以 UTF-8 输出,以便带重音符号的字符在 Windows 上正确显示(第 2 章)。

位于子项目文件夹中的配置文件 [tax-hibernate.properties] 指定数据库:

1
2
3
4
# [Tax] 应用程序第 7 版的配置:税率档数据库
jdbc.url=jdbc:mysql://localhost:3306/hbtaxes
jdbc.user=root
jdbc.password=

文件 [tax-hibernate-error.properties] 引用一个名为 [hbtaxesmissing] 的数据库,该数据库并不存在:

1
2
3
4
# 一个不存在的数据库
jdbc.url=jdbc:mysql://localhost:3306/hbtaxesmissing
jdbc.user=root
jdbc.password=

主程序就是版本 5 的主程序,其中只有 [dao] 层的组合发生了变化:

package tax.ui

import tax.dao.HibernateTax
import tax.dao.ITaxDao
import tax.entities.TaxException
import tax.business.ITaxBusiness
import tax.business.TaxBusiness
import java.util.Properties
import kotlin.io.path.Path
import kotlin.io.path.bufferedReader
import kotlin.system.exitProcess
import org.springframework.beans.factory.getBean
import org.springframework.context.support.GenericApplicationContext
import org.springframework.context.support.registerBean

// 第 7 版:[dao] 层用 Hibernate 从数据库读取税率档
fun main(args: Array<String>) {
    // 配置文件:默认为 tax-hibernate.properties,或作为参数传入的文件
    val configFile = args.firstOrNull() ?: "tax-hibernate.properties"

    // 各层的集成
    val business: ITaxBusiness = try {
        // 在当前文件夹中读取配置
        val config = Properties()
        Path(configFile).bufferedReader().use { config.load(it) }
        val url = config.getProperty("jdbc.url")
            ?: throw TaxException("Database URL [jdbc.url] missing from the file $configFile")
        val user = config.getProperty("jdbc.user", "root")
        val password = config.getProperty("jdbc.password", "")

        // Spring 容器:各层在其中注册
        val context = GenericApplicationContext()
        // [dao] 层:HibernateTax,使用配置中的数据库
        context.registerBean<ITaxDao> { HibernateTax(url, user, password) }
        // 第 5 版的 [business] 层:容器会把 [dao] 层传给它
        context.registerBean<TaxBusiness>()

        // 启动容器:它先创建 [dao] 层,再创建 [business] 层
        context.refresh()
        context.getBean<ITaxBusiness>()
    } catch (e: Exception) {
        // 显示错误并结束程序
        Dialog.displayError(e)
        exitProcess(1)
    }

    // 与用户的对话,即第 5 版的对话
    Dialog.run(business)
}
  • 该文件不叫 [Main.kt]:否则它会被编译成名为 [tax.ui.MainKt] 的类,而这个类已经存在于我们所依赖的版本 5 的 [tax-ui] 模块中。文件 [MainHibernate.kt] 会生成名为 [tax.ui.MainHibernateKt] 的类;
  • 第 26–29 行:必需的数据库 URL、用户名和密码,从配置中读取。对于缺失的键,[getProperty] 返回 [null] :Elvis 运算符([?:])随后计算为 [TaxException]([throw] 是 Kotlin 的表达式);
  • 第 34 行:[dao] 层是一个 [HibernateTax],由一个 lambda 创建,该 lambda 向它传入数据库的参数;
  • 第 36 行:版本 5 中的 [business] 层:容器会把 [dao] 层传给它的构造函数;
  • 第 48 行:版本 5 的对话。

11.15.5. 执行

为获得这些结果而重定向给程序的用户输入,放在各个问题之后:

1
2
3
4
5
6
7
8
> gradlew -q :TaxV7:tax-ui-hibernate:run
Tax calculation parameters in the format: Married (y/n) NbChildren Salary, or nothing to stop: y 2 60000
Tax=4282 euros
Tax calculation parameters in the format: Married (y/n) NbChildren Salary, or nothing to stop: y 3 60000
Tax=2959 euros
Tax calculation parameters in the format: Married (y/n) NbChildren Salary, or nothing to stop: n 0 60000
Tax=11519 euros
Tax calculation parameters in the format: Married (y/n) NbChildren Salary, or nothing to stop:

沿用先前版本的对照值:一对已婚夫妇有两个孩子、合计收入 60,000 欧元,税款为 4,282 欧元;有三个孩子时为 2,959 欧元;单身且无孩子的人为 11,519 欧元。

使用配置文件 [tax-hibernate-error.properties],它引用一个不存在的数据库:

> gradlew -q :TaxV7:tax-ui-hibernate:run --args="tax-hibernate-error.properties"
Exception chain:
----------------------------------------
org.springframework.beans.factory.BeanCreationException: Error creating bean with name 'tax.dao.ITaxDao': Instantiation of supplied bean failed
----------------------------------------
tax.entities.TaxException: Error while reading the tax brackets from the database
----------------------------------------
org.hibernate.service.spi.ServiceException: Unable to create requested service [org.hibernate.engine.jdbc.env.spi.JdbcEnvironment] due to: Error calling Driver.connect() [Unknown database 'hbtaxesmissing']
----------------------------------------
org.hibernate.exception.SQLGrammarException: Error calling Driver.connect() [Unknown database 'hbtaxesmissing']
----------------------------------------
java.sql.SQLSyntaxErrorException: Unknown database 'hbtaxesmissing'
----------------------------------------
  • 第 12 行:原始异常,由 JDBC 驱动程序抛出;
  • 第 8 行和第 10 行:封装它的 Hibernate 异常:错误发生在创建 [SessionFactory] 期间,当时 Hibernate 连接服务器以确定其版本;
  • 第 6 行:[dao] 层把该错误包装在一个 [TaxException] 中;
  • 第 4 行:正在创建 [dao] 层的 Spring 容器本身又把该异常封装在一个 [BeanCreationException] 中,由主程序显示出来。

更换 DBMS 相当于更改数据库的 URL 和对 JDBC 驱动程序的依赖:Hibernate 会根据所遇到的 DBMS 自动选择 SQL 方言,而用 HQL 编写的 [HibernateTax] 类的代码保持不变。只需重新执行数据库的创建——它取决于列类型——程序 [CreateDatabase.kt] 除了修改自己的 URL 之外无需任何改动就能完成这项工作。

11.16. 结论:JDBC、JdbcClient、jOOQ、Exposed 还是 Hibernate?

我们现在有两种访问数据库的方式:JDBC(第 10 章)和 Hibernate(本章)。还有一些被广泛使用的折中方案:

  • JdbcClient,来自 Spring Framework([spring-jdbc] 库),为 JDBC 增加了一个灵活的 API,它执行手写的 SQL 查询,并自动把结果行转换为对象:[jdbcClient.sql("select * from articles where price > :price").param("price", 200).query(Article::class.java).list()]。SQL 由你来写;Spring 负责处理参数,并把各列复制到对象中(包括数据类,其构造函数接收各列)。这是一种“微型 ORM”;
  • jOOQ 根据数据库模式生成类,使你能够在 Java 或 Kotlin 中编写由编译器验证的 SQL:[dsl.selectFrom(ARTICLES).where(ARTICLES.PRICE.gt(price)).fetch()]。你保留对 SQL 的完全控制,同时享有类型检查带来的安全性;
  • Exposed来自 JetBrains,是用 Kotlin 编写、为 Kotlin 而生的数据库访问库。表在其中使用 Kotlin 对象来描述([object Articles : Table("articles")],其列形如 [val price = decimal("price", 10, 2)]),无需代码生成,而查询则用专门的语言(“DSL”)编写,它类似于 SQL,并由编译器验证:[Articles.selectAll().where { Articles.price greater minPrice }]。Exposed 还提供第二种 API,即轻量级的 ORM(与表关联的实体类),并依赖 JDBC,或可选地依赖可在协程中使用的非阻塞驱动程序(R2DBC)。它充分利用了我们学过的有关 Kotlin 的一切:扩展函数、带接收者的 lambda、中缀函数([greater]),以及用于可选列的可空类型。
 
优点
缺点
JDBC
完全控制 SQL;性能好;无依赖
大量重复代码(参数、读取列),在 Kotlin 中通过 [use] 和扩展函数得以简化;SQL 写在字符串中,编译器不检查
JdbcClient
SQL 手写,无需复制粘贴的代码;性能与 JDBC 相近
不跟踪变更,也不生成 [INSERT]/[UPDATE];SQL 未经验证
jOOQ
SQL 由编译器验证;支持 DBMS 的全部功能
每次模式变更都要重新生成代码;不跟踪变更;某些商业版 DBMS 需要付费许可
Exposed
专为 Kotlin 设计;查询由编译器验证,无需代码生成;轻量
仅限 Kotlin;不如 Hibernate 普及,文档较少;模式需要在代码中手动描述
Hibernate
面向对象的模型;变更跟踪;关系;HQL 和 Criteria API;Jakarta Persistence 标准;与 DBMS 无关
多出一层需要理解(会话、状态、懒加载);需要监控生成的 SQL 代码;不太适合复杂的批量处理;需要针对 Kotlin 做一些调整([jpa] 和 [allopen] 插件,实体不能用数据类)

可以给出以下指导原则:

  • Hibernate (通常通过 Spring Data JPA)适用于大多数业务应用程序:由相互关联的实体构成的模型、读取和更新实体的操作,以及随应用程序演进的模式。无论在 Kotlin 还是 Java 中,它都是 Spring Boot 应用程序的默认选择;
  • JDBC、JdbcClient、jOOQ 或 Exposed 适用于需要精确控制所执行 SQL 的情形:复杂的统计查询、存储过程、处理海量数据,或者现有数据库的模式不太适合面向对象模型。对于完全用 Kotlin 编写的应用程序,尤其是在 Spring 之外(例如使用 JetBrains 的 Ktor Web 框架),Exposed 是自然的选择;
  • 这些方法可以组合使用:应用程序可以把 Hibernate 用于其大部分操作,而对少数关键查询,则通过 [JdbcClient] 或 JDBC([doWork])使用手写的 SQL 代码,即原生查询的形式。

无论如何,ORM 都不能免除理解 SQL 和 DBMS 工作方式的必要:我们在本章中一直显示的已执行 SQL 命令的日志,是验证 Hibernate 实际在做什么的首要工具。

要了解更多信息,Hibernate 的文档很全面,其入门指南是最好的起点:Hibernate ORM - documentation。Jakarta Persistence 规范由 Eclipse Foundation 发布:Jakarta Persistence。Spring 关于在 Kotlin 中使用 JPA 的指南总结了本章涉及的概念(插件、实体、可空性):Building web applications with Spring Boot and Kotlin。Exposed 在其 GitHub 页面上有介绍,该页面链接到其文档:JetBrains Exposed。