從 kapt 遷移至 KSP

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

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

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

以下是遷移步驟總覽：

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

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

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

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

在專案中新增 KSP 外掛程式

首先，請在頂層 build.gradle.kts 檔案中宣告 KSP 外掛程式，您可以在 KSP GitHub 頁面中查看版本清單。

Kotlin

plugins {
    id("com.google.devtools.ksp") version "2.3.4" apply false
}

Groovy

plugins {
    id 'com.google.devtools.ksp' version '2.3.4' 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 處理工具。

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 外掛程式。

如果您是在 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
}

其他資源