【Kotlin】Kotlin Annotation Processing 入門：`kapt` を完全理解する（Room / Hilt / Glide 対応）

はじめに

Kotlin 開発をしていると、Gradle によく出てくるこの一行：

kapt("androidx.room:room-compiler:2.6.1")

「kapt って何？」「annotationProcessor と何が違うの？」
という疑問を持ったことはありませんか？

この記事では、Kotlin の アノテーション処理機構 kapt（Kotlin Annotation Processing Tool） を、
図解で整理していきます。

---

1. kapt とは？

kapt は Kotlin Annotation Processing Tool の略で、
Kotlin コードでも Java 用のアノテーションプロセッサ（annotationProcessor）を使えるようにするための仕組み です。

背景

• Java では annotationProcessor により、Dagger や Room などがコード生成を行っていました。
• しかし Kotlin は Java コンパイラではなく Kotlin コンパイラで処理されるため、
  Java のアノテーションプロセッサがそのまま動きません。

そこで登場するのが kapt。
Kotlin のソースから中間的に 「Java風の stub（仮クラス）」 を生成し、
Java のアノテーションプロセッサに渡してコード生成を可能にします。

---

2. kapt の動作イメージ

Kotlin → kapt（Stub生成）→ Javaプロセッサ → 生成コード → Kotlinコンパイル
という流れです。

---

3. build.gradle.kts の設定例

plugins {
    kotlin("kapt")
    id("com.google.dagger.hilt.android") version "2.51"
}

dependencies {
    // --- Hilt ---
    implementation("com.google.dagger:hilt-android:2.51")
    kapt("com.google.dagger:hilt-android-compiler:2.51")

    // --- Room ---
    implementation("androidx.room:room-runtime:2.6.1")
    kapt("androidx.room:room-compiler:2.6.1")

    // --- Glide ---
    implementation("com.github.bumptech.glide:glide:4.16.0")
    kapt("com.github.bumptech.glide:compiler:4.16.0")
}

annotationProcessor(...) の代わりに kapt(...) を使うのがポイント！

---

4. kapt の設定オプション

kapt {
    correctErrorTypes = true      // Hiltなどで推奨。誤認識エラーを防ぐ
    useBuildCache = true          // 生成コードをキャッシュしてビルド高速化
    mapDiagnosticLocations = true // エラーメッセージの位置を正確にマッピング
}

---

5. 代表的なライブラリと kapt

ライブラリ	kapt 対応プロセッサ	用途
Room	androidx.room:room-compiler	DAO・Entityの実装生成
Hilt	hilt-android-compiler	DIコンポーネント生成
Glide	compiler	ImageLoaderのAPI生成
Dagger 2	dagger-compiler	依存グラフ生成
Moshi	moshi-kotlin-codegen	JSONアダプタ生成

---

6. kapt と KSP の違い

項目	kapt	KSP
処理方式	Java Annotation Processor 経由	Kotlin Symbol Processing
Kotlin最適化	✗ Stub経由で遅い	✓ Kotlin専用で高速
対応ライブラリ	Dagger / Hilt / Room	Room / Moshi / Koin / Ktorなど
利用推奨	既存Java系プロジェクト	新規・Kotlin特化プロジェクト

例：

• kapt("androidx.room:room-compiler:2.6.1")
• → KSP 版なら：ksp("androidx.room:room-compiler:2.6.1")

---

7. よくあるエラーと対処法

❌ Symbol is declared in module kapt stub

IntelliJ が kapt の stub を参照して混乱している場合。

対処:
Build > Clean Project や Invalidate Caches を実行。

---

❌ Unresolved reference: DaggerHiltComponent

kapt がまだ生成していない状態。

対処:
./gradlew kaptKotlin や Rebuild Project を実行。

---

8. 実行タスク（Gradle）

./gradlew kaptKotlin        # kapt のみ実行
./gradlew kaptDebugKotlin   # デバッグビルド用
./gradlew kaptClean         # 生成コード削除

---

まとめ

要点
kapt は Kotlin 用の Java Annotation Processor ブリッジ
Stub（仮Javaコード）を介して Java ライブラリを動かす
Room / Hilt / Dagger / Glide などで必須
Kotlin専用なら KSP の方が高速＆モダン