從 kapt 遷移至 KSP

Kapt (Kotlin 註解處理工具) 可讓您將 Java 註解處理工具與 Kotlin 程式碼搭配使用，即使這些處理工具並未支援 Kotlin 也沒問題，方法是透過 Kotlin 檔案產生 Java 虛設常式，供這些處理工具讀取。產生這類虛設常式是相當耗費資源的作業，並會大幅影響建構速度。

KSP (Kotlin Symbol Processing) 是以 Kotlin 優先的 kapt 替代方案，可直接分析 Kotlin 程式碼，且速度可達 2 倍。此外，KSP 對於 Kotlin 的語言結構有更充分的瞭解。

Kapt 目前處於維護模式，建議您盡可能從 kapt 遷移至 KSP。在大部分情況下，您只需要變更專案的建構設定即可遷移。

您可於遷移期間在專案中並行執行 kapt 和 KSP，並可針對各個模組和各個程式庫逐一進行遷移。

注意：如果模組中仍有 kapt 處理工具，該模組仍會產生虛設常式。這表示在大多數情況下，只有在模組完全停止使用 kapt 時，效能才會有所改善。

以下是遷移步驟總覽：

1. 確認您使用的程式庫是否支援 KSP
2. 在專案中新增 KSP 外掛程式
3. 使用 KSP 取代註解處理工具
4. 移除 kapt 外掛程式

確認您使用的程式庫是否支援 KSP

首先，請確認您目前搭配 kapt 使用的程式庫是否支援 KSP。許多熱門程式庫 (包括 Dagger、Glide、Room 和 Moshi) 都是如此。

您可以查看說明文件中的支援的程式庫清單，或參閱所用程式庫的說明文件和問題追蹤工具。

注意：雖然傳統上不是隨附的程式庫依附元件，但資料繫結也會使用註解處理工具提供其功能，且目前沒有針對資料繫結提供 KSP 支援的計畫。如要降低 kapt 對建構作業的影響，您可以在不同模組中使用資料繫結。

在專案中新增 KSP 外掛程式

首先，請在頂層 build.gradle.kts 檔案中宣告 KSP 外掛程式，並確認所選 KSP 版本與專案的 Kotlin 版本一致。您可以在 KSP GitHub 頁面中查看版本清單。

Kotlin

plugins {
    id("com.google.devtools.ksp") version "1.8.10-1.0.9" apply false
}

Groovy

plugins {
    id 'com.google.devtools.ksp' version '1.8.10-1.0.9' apply false
}

接著在模組層級 build.gradle.kts 檔案中啟用 KSP：

Kotlin

plugins {
    id("com.google.devtools.ksp")
}

Groovy

plugins {
    id 'com.google.devtools.ksp'
}

使用 KSP 取代註解處理工具

啟用 KSP 後，您就能開始使用 KSP 取代 kapt。針對大部分的程式庫，您只需要在宣告依附元件時將 kapt 變更為 ksp 即可，原因是這兩者會在相同成果中提供其註解處理工具和 KSP 處理工具。

注意：針對某些程式庫 (例如 Glide)，您可能還需要將依附元件變更至其他成果。請務必參閱程式庫的說明文件。

Kotlin

dependencies {
    kapt("androidx.room:room-compiler:2.5.0")
    ksp("androidx.room:room-compiler:2.5.0")
}

Groovy

dependencies {
    kapt 'androidx.room:room-compiler:2.5.0'
    ksp 'androidx.room:room-compiler:2.5.0'
}

遷移至 KSP 之後，請同步處理並建構專案，確認專案是否仍可正常運作。

以下是幾個需要留意的常見問題：

• 某些程式庫針對 kapt 和 KSP 支援的功能並不相同。 如果程式碼在遷移後發生問題，請參閱程式庫的說明文件。
• 與 kapt 相比，KSP 的 Kotlin 類型資訊 (例如是否可為空值的相關資訊) 更加準確。這表示在類型要求方面，KSP 可能較明確。因此，除了更新建構檔案以外，您可能還需要稍微修正原始碼。
• 如果您先前透過引數傳遞至註解處理工具，則現在可能必須透過那些引數傳遞至 KSP。請注意，kapt 和 KSP 的引數格式可能並不相同。詳情請參閱 KSP 說明文件和所用程式庫的說明文件。

移除 kapt 外掛程式

當模組中已沒有 kapt 隨附的依附元件時，請移除 kapt 外掛程式。

注意：如要在模組中啟用資料繫結，您也必須使用 kapt。在使用資料繫結的模組中，您無法移除 kapt。

如果您是在 plugins 區塊中宣告 kapt 外掛程式：

Kotlin

plugins {
    id("org.jetbrains.kotlin.kapt")
}

Groovy

plugins {
    id 'org.jetbrains.kotlin.kapt'
}

如果 kapt 外掛程式使用 Groovy 的 apply plugin 語法：

apply plugin: 'kotlin-kapt'

您也必須移除與 kapt 相關的所有其他設定，例如：

Kotlin

kapt {
    correctErrorTypes = true
    useBuildCache = true
}

Groovy

kapt {
    correctErrorTypes true
    useBuildCache true
}

其他資源

• Kotlinlang.org 提供的 KSP 說明文件
• GitHub 的 KSP 頁面
• Kotlinlang.org 的 kapt 頁面 -->