Kotlin-jpa 编译器插件
kotlin-jpa 编译器插件用于为 Java 持久化 API(Java Persistence API,JPA)配置 Kotlin 项目。 JPA 有两项与 Kotlin 默认特性相冲突的要求:
- 无参构造函数。 JPA 通过反射实例化实体(这一过程称为 hydration),这需要一个无参构造函数。而 Kotlin 类默认不声明无参构造函数。
- 非 final 类。 JPA 提供程序会为实体创建代理子类以支持延迟加载(例如,针对
@ManyToOne和@OneToOne关联)。Kotlin 类及其成员默认均为final,这会阻止该特性的工作。如果实体不是open的,延迟加载将无法正常运行。
kotlin-jpa 插件同时解决了这两个问题。它是一个预配置的包装器,应用了以下插件:
no-arg插件:为带有 JPA 注解的类生成无参构造函数。all-open插件:将带有 JPA 注解的类及其成员设为open。
生成的构造函数会被标记为 HIDDEN 级别的 @Deprecated 注解,因此你可以从 Java 中调用它,但不能在 Kotlin 中直接调用。JPA 则可以通过反射调用它。
如果你使用 start.spring.io 并添加 JPA 依赖项来生成项目模板,kotlin-jpa 插件将默认启用。
支持的 JPA 注解
JPA 注解存在于两个包命名空间中:较旧的 javax.persistence(Java EE)以及较新的 jakarta.persistence(自 Jakarta EE 9 起引入,由 Spring Boot 3.x 及更高版本使用)。kotlin-jpa 插件可识别这两个命名空间,并自动为底层的 no-arg 和 all-open 插件指定以下注解:
javax.persistence.Entity和jakarta.persistence.Entityjavax.persistence.Embeddable和jakarta.persistence.Embeddablejavax.persistence.MappedSuperclass和jakarta.persistence.MappedSuperclass
请使用与你的框架版本相匹配的命名空间注解。你无需针对其中任何一个命名空间专门配置该插件:两者均默认启用。
应用插件
Gradle
在 build.gradle(.kts) 文件的 plugins {} 代码块中添加 kotlin-jpa 插件:
plugins {
kotlin("jvm") version "2.4.21" // 要使用的 Kotlin 版本
kotlin("plugin.jpa") version "2.4.21" // Kotlin JPA 插件
}plugins {
id "org.jetbrains.kotlin.jvm" version "2.4.21"
id "org.jetbrains.kotlin.plugin.jpa" version "2.4.21"
}Maven
在 Maven 中,对 kotlin-jpa 插件的支持由 kotlin-maven-noarg 插件提供。请将其添加到你的 pom.xml 文件中:
<properties>
<kotlin.version>2.4.21</kotlin.version>
</properties>
<plugin>
<groupId>org.jetbrains.kotlin</groupId>
<artifactId>kotlin-maven-plugin</artifactId>
<version>${kotlin.version}</version>
<configuration>
<compilerPlugins>
<plugin>jpa</plugin>
</compilerPlugins>
</configuration>
<dependencies>
<dependency>
<groupId>org.jetbrains.kotlin</groupId>
<artifactId>kotlin-maven-noarg</artifactId>
<version>${kotlin.version}</version>
</dependency>
</dependencies>
</plugin>自 Kotlin 2.3.20 起,kotlin-maven-noarg 隐式包含了 kotlin-maven-allopen,因此你无需再显式添加 all-open 依赖项。
使用 kotlin-jpa 插件
应用该插件后,带有常用 JPA 注解的类在编译期将自动变为 open,并生成一个无参构造函数。你可以直接将实体编写为常规类,而无需手动添加 open 关键字或手动声明无参构造函数。
以下示例使用 jakarta.persistence 命名空间。如果你的框架仍在使用 Java EE,请改为从 javax.persistence 导入相同的注解,该插件对两者均提供支持:
import jakarta.persistence.Entity
import jakarta.persistence.GeneratedValue
import jakarta.persistence.Id
@Entity
class Message(
var text: String,
) {
// kotlin-jpa 插件会将此类设为 open 并生成一个
// 供 JPA 反射实例化使用的无参构造函数
@Id
@GeneratedValue
var id: Long? = null
}JPA 实体的最佳实践
虽然应用该插件可以使实体变为 open 并为其提供无参构造函数,但 Kotlin 的部分惯用语法仍可能与 JPA 提供程序管理实体的方式发生冲突。请遵循以下准则以避免常见问题:
使用常规类,而不是
data class。 数据类偏好不可变的val属性,并且会基于所有属性派生equals()、hashCode()和toString()。对于实体而言,这会破坏代理机制,且toString()或equals()可能会在延迟关联上触发额外的查询。建议将实体建模为常规类(插件会将其设为open),并将数据类仅用于 DTO 和查询结果。将映射属性声明为
var。 JPA 在对实体进行组装(hydrate)时会设置字段,因此映射属性必须是可变的。使生成的标识符可空且可变。 带有
@GeneratedValue的标识符在实体被持久化之前为null,因此应声明为var id: Long? = null。在 Kotlin 中不能对基本数据类型使用
lateinit。仅基于标识符和类型实现
equals()和hashCode(),而不是基于所有属性。这可确保它们在实体的整个生命周期中保持稳定,并避免加载延迟加载字段。
有关这些陷阱的详细讨论,请参阅博客文章如何避免 JPA 与 Kotlin 的常见陷阱。
涵盖未带有 JPA 注解的类
kotlin-jpa 插件仅配置了受支持的 JPA 注解。若要为未带有 JPA 注解的类型生成无参构造函数或将它们设为 open,你可以声明自己的注解,并将其注册到底层的 no-arg 和 all-open 插件中:
声明你自己的注解:
kotlinpackage com.example annotation class OpenNoArgAnnotation在构建文件中,向底层插件注册该注解:
在
build.gradle.kts文件中,在通过kotlin-jpa插件提供的noArg {}和allOpen {}代码块中注册该注解:kotlinplugins { kotlin("jvm") version "2.4.21" kotlin("plugin.jpa") version "2.4.21" } noArg { annotation("com.example.OpenNoArgAnnotation") } allOpen { annotation("com.example.OpenNoArgAnnotation") }在
build.gradle文件中,在通过kotlin-jpa插件提供的noArg {}和allOpen {}代码块中注册该注解:groovyplugins { id "org.jetbrains.kotlin.jvm" version "2.4.21" id "org.jetbrains.kotlin.plugin.jpa" version "2.4.21" } noArg { annotation("com.example.OpenNoArgAnnotation") } allOpen { annotation("com.example.OpenNoArgAnnotation") }在
pom.xml文件中,将no-arg:annotation和all-open:annotation选项添加到kotlin-maven-plugin的配置中:xml<properties> <kotlin.version>2.4.21</kotlin.version> </properties> <plugin> <groupId>org.jetbrains.kotlin</groupId> <artifactId>kotlin-maven-plugin</artifactId> <version>${kotlin.version}</version> <configuration> <compilerPlugins> <plugin>jpa</plugin> </compilerPlugins> <pluginOptions> <!-- 若有多个注解,请添加多行 --> <option>no-arg:annotation=com.example.OpenNoArgAnnotation</option> <option>all-open:annotation=com.example.OpenNoArgAnnotation</option> </pluginOptions> </configuration> <dependencies> <dependency> <groupId>org.jetbrains.kotlin</groupId> <artifactId>kotlin-maven-noarg</artifactId> <version>${kotlin.version}</version> </dependency> </dependencies> </plugin>标记未带有 JPA 注解的类:
kotlinpackage com.example import jakarta.persistence.Entity import jakarta.persistence.GeneratedValue import jakarta.persistence.Id // 由 kotlin-jpa 插件自动支持 @Entity class Message( var text: String, ) { @Id @GeneratedValue var id: Long? = null } // 自定义注解将此类设为 open // 并生成无参构造函数 @OpenNoArgAnnotation class MessageMetadata( var author: String, )
有关更多详细信息,请参阅 no-arg 和 all-open。
后续步骤
- 阅读关于如何避免常见实体映射问题的博客文章。
- 对于需要将类设为
open的 Spring 应用程序,请使用kotlin-spring插件,该插件会为all-open插件配置诸如@Component、@Transactional和@Configuration等 Spring 注解。 - 参考 Spring Boot 与 Kotlin 入门教程创建你的第一个 Spring Boot 应用程序。
