Skip to content

Kotlin Symbol Processing API ​

Kotlin Symbol Processing (KSP) 是一套適用於 Kotlin 的原始碼產生架構。透過 KSP API,你可以建立用於檢查原始碼靜態資訊並從中產生新程式碼的處理器。最常見的使用案例是根據註解產生程式碼。

KSP 旨在簡化輕量級編譯器外掛程式的建立。使用 KSP 建置的編譯器外掛程式稱為符號處理器(symbol processor),簡稱處理器。KSP 定義明確的 API 隱藏了編譯器的變更,因此你無需耗費大量心力來維護處理器。然而,這種方法也有其權衡。例如,以 KSP 為基礎的處理器無法檢查運算式或陳述式,而且無法修改原始碼。

以 KSP 為基礎的外掛程式之典型使用案例包括:

若要了解如何建立你的第一個以 KSP 為基礎的處理器,請參閱 KSP 入門。

需求 ​

最新版的 KSP(2.3.12)支援以下相依性版本:

相依項最低與最高版本
Kotlin Gradle plugin (KGP)2.3.20–2.4.x
Android Gradle Plugin (AGP)8.13.0 或更新版本
Gradle8.13 或更新版本。若使用 AGP 9.0 或更新版本,請使用 Gradle 9.x。
JDK17 或更新版本

KSP 在編譯期間的運作方式 ​

KSP 根據 Kotlin 文法將 Kotlin 原始碼表示為符號階層結構。處理器使用這些符號來檢查宣告,例如類別、函式、屬性以及型別。

KSP 為宣告與型別資訊建立模型,但不允許處理器存取運算式或函式主體。

KSP 融入編譯流程的方式如下:

  1. KSP 處理器分析原始碼與資源。

  2. 處理器產生原始程式碼檔案或其他輸出。

  3. Kotlin 編譯器將原始原始碼與產生的程式碼一起編譯。

若要進一步了解 KSP,請觀看這部影片:

KSP 如何執行處理器 ​

KSP 使用 SymbolProcessorProvider 的實作作為建立 SymbolProcessor 執行個體的入口點:

kotlin
interface SymbolProcessorProvider {
    fun create(environment: SymbolProcessorEnvironment): SymbolProcessor
}

SymbolProcessor 介面包含處理邏輯。KSP 會呼叫 process() 函式並提供一個 Resolver,處理器可透過它來存取原始碼中的符號:

kotlin
interface SymbolProcessor {
    fun process(resolver: Resolver): List<KSAnnotated>
    fun finish() {}
    fun onError() {}
}

關於如何實作與註冊處理器的逐步指南,請參閱 KSP 入門。

支援的程式庫 ​

此表格列出了 Android 上的熱門程式庫及其對 KSP 的不同支援階段:

程式庫狀態
Room官方支援
Moshi官方支援
RxHttp官方支援
Kotshi官方支援
Lyricist官方支援
Lich SavedState官方支援
gRPC Dekorator官方支援
EasyAdapter官方支援
Koin Annotations官方支援
Glide官方支援
Micronaut官方支援
Epoxy官方支援
Paris官方支援
Auto Dagger官方支援
SealedX官方支援
Ktorfit官方支援
Mockative官方支援
Kotest官方支援
DeeplinkDispatch透過 airbnb/DeepLinkDispatch#323 支援
DaggerAlpha
MotifAlpha
Hilt進行中
Auto Factory尚未支援

其他資源 ​