はじめに

kapt に代わる新しいアノテーション処理システムとして、
Google が開発した KSP（Kotlin Symbol Processing） が急速に普及しています。

特に、Room・Moshi・Koin などが続々と KSP 対応版を提供しており、
ビルド時間の短縮と Kotlin 向け最適化が進んでいます。

この記事では、
「kapt との違い」「仕組み」「導入方法」「移行実例」までを徹底解説します。

1. KSPとは？

KSP (Kotlin Symbol Processing) は Kotlin コードを直接解析し、
コード生成を行うための新しいアノテーション処理フレームワークです。

これまでの kapt（Kotlin Annotation Processing Tool）は、
Kotlin → Java Stub → Java Annotation Processor → 生成コード
という 遠回りの処理 を行っていました。

KSP はこれを根本的に改善します。

2. 動作の流れ

☑️ Stub生成なし！
☑️ 高速ビルド！
☑️ Kotlin専用構文の完全解析！

3. 導入方法

build.gradle.kts 設定

plugins {
    kotlin("kapt") // 旧方式（削除予定でも共存OK）
    id("com.google.devtools.ksp") version "2.0.21-1.0.24" // ✅ KSPプラグイン追加
}

dependencies {
    // Room の KSP 対応版
    implementation("androidx.room:room-runtime:2.6.1")
    ksp("androidx.room:room-compiler:2.6.1")

    // Moshi の KSP 対応版
    implementation("com.squareup.moshi:moshi-kotlin:1.15.1")
    ksp("com.squareup.moshi:moshi-kotlin-codegen:1.15.1")

    // Koin の KSP 対応版
    implementation("io.insert-koin:koin-annotations:1.3.1")
    ksp("io.insert-koin:koin-ksp-compiler:1.3.1")
}

4. `kapt` との違い

項目	kapt	KSP
処理対象	Java Annotation Processor	Kotlin Symbol Processor
中間生成物	Java Stub	なし（Kotlin直接解析）
対応言語	Javaベース	Kotlin専用
性能	遅い（Stub生成あり）	高速（Stub不要）
マルチプラットフォーム	非対応	KMP（Kotlin Multiplatform）対応
代表例	Dagger / Hilt / Glide / Room	Room / Koin / Moshi / Compose Compiler

KSP の方が最大 2〜3倍ビルドが速くなる と公式が発表しています。
（Google Developers Blog より）

5. コード生成例

Room (KSP版)

@Dao
interface UserDao {
    @Query("SELECT * FROM user WHERE id = :id")
    suspend fun findUserById(id: Int): User
}

ビルド後、自動生成される：

class UserDao_Impl(private val db: RoomDatabase) : UserDao {
    ...
}

kapt版と同様のコードが生成されますが、Stub生成なしでより高速。

6. KSP の出力フォルダ構造

KSP により生成されたコードは、以下の場所に出力されます：

build/generated/ksp/
 ├── debug/
 │   ├── kotlin/
 │   └── resources/
 └── release/

IDE（IntelliJ/Android Studio）はこのディレクトリを自動でソースルートとして認識します。

7. KSP 用 Gradle タスク

コマンド	内容
`./gradlew kspKotlin`	KSP処理を実行
`./gradlew kspDebugKotlin`	Debugビルド時のみ実行
`./gradlew cleanKspKotlin`	生成コード削除
`./gradlew assembleDebug`	通常ビルド時に自動含まれる

8. KSP 導入の実例（Room移行）

旧（kapt）

implementation("androidx.room:room-runtime:2.5.2")
kapt("androidx.room:room-compiler:2.5.2")

新（ksp）

implementation("androidx.room:room-runtime:2.6.1")
ksp("androidx.room:room-compiler:2.6.1")

そして build.gradle.kts に以下を追記：

id("com.google.devtools.ksp") version "2.0.21-1.0.24"

Room 2.4.0 以降で正式に KSP 対応。
kapt から簡単に切り替え可能です。

9. カスタムアノテーションプロセッサを作る（上級編）

KSP を使えば、自作のコード生成ツールも実装できます。

class HelloProcessor(
    private val codeGenerator: CodeGenerator,
    private val logger: KSPLogger
) : SymbolProcessor {

    override fun process(resolver: Resolver): List<KSAnnotated> {
        val symbols = resolver.getSymbolsWithAnnotation("com.example.Hello")
        symbols.forEach { symbol ->
            val name = symbol.simpleName.asString()
            val file = codeGenerator.createNewFile(
                Dependencies(false),
                "com.example.generated",
                "${name}Generated"
            )
            file.write("fun greet() = println(\"Hello, $name!\")".toByteArray())
        }
        return emptyList()
    }
}

→ @Hello アノテーションを付けたクラスごとに
Generated クラスを自動生成する。

まとめ

要点
`KSP` は Kotlin 専用のアノテーション処理機構
Stub 不要で高速（ビルド最大3倍速）
Room, Moshi, Koin, Compose などが正式対応
`kapt` からの移行は簡単：`kapt()` → `ksp()`
Kotlin Multiplatform にも対応