はじめに

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 の方が高速＆モダン