Kotlin-jpa コンパイラプラグイン
kotlin-jpa コンパイラプラグインは、Java Persistence API (JPA) 向けに Kotlin プロジェクトを設定します。 JPA には、Kotlin のデフォルトの挙動と競合する2つの要件があります。
- 引数なしコンストラクタ: JPA はリフレクションを介してエンティティをインスタンス化します(このプロセスは_ハイドレーション (hydration)_ と呼ばれます)。これには引数なしコンストラクタが必要ですが、Kotlin クラスはデフォルトでは引数なしコンストラクタを宣言しません。
- 非 final (non-final) クラス: JPA プロバイダは、遅延ロード(lazy loading、例えば
@ManyToOneや@OneToOneの関連付けなど)をサポートするためにエンティティのプロキシサブクラスを作成します。Kotlin のクラスとそのメンバはデフォルトでfinalであるため、これが妨げられます。エンティティがopenでない場合、遅延ロードは機能しません。
kotlin-jpa プラグインはこの両方に対応します。これは、以下を適用する事前構成済みのラッパーです。
- JPA アノテーションが付与されたクラスに対して引数なしコンストラクタを生成する
no-argプラグイン - JPA アノテーションが付与されたクラスとそのメンバを
openにするall-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 以降で使用) の2つのパッケージ名前空間に存在します。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 はエンティティをハイドレーションする際にフィールドを設定するため、マッピングされたプロパティはミュータブル(可変)である必要があります。生成される識別子は null 許容かつミュータブルにする:
@GeneratedValueが付いた識別子は、エンティティが永続化されるまでnullになるため、var id: Long? = nullのように宣言します。Kotlin ではプリミティブ型に
lateinitを使用できません。equals()とhashCode()は識別子と型のみに基づくようにする: すべてのプロパティには基づかせないでください。これにより、エンティティのライフサイクル全体を通じてそれらが安定した状態に保たれ、遅延フィールドのロードを回避できます。
これらの落とし穴に関する詳細な解説については、ブログ記事「How to avoid common pitfalls with JPA and 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ファイルで、kotlin-maven-pluginの設定にno-arg:annotationおよびall-open:annotationオプションを追加します。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 を参照してください。
次のステップ
- エンティティマッピングに関する一般的な問題を回避する方法についてのブログ記事「How to avoid common pitfalls with JPA and Kotlin」をお読みください。
- クラスを
openにする必要がある Spring アプリケーションの場合は、kotlin-springプラグイン を使用してください。このプラグインは、all-openプラグインを@Component、@Transactional、@Configurationなどの Spring アノテーションで構成します。 - Spring Boot と Kotlin を使ってみる チュートリアルを使用して、最初の Spring Boot アプリケーションを作成しましょう。
