KSP 入門
在本指南中,您將學習:
- 如何將以 KSP 為基礎的註解處理器新增至您的專案中。
- 如何使用 KSP API 建立您自己的註解處理器。
- 在何處尋找由處理器產生的程式碼。
將以 KSP 為基礎的處理器新增至您的專案
若要在您的專案中使用外部處理器,請在 build.gradle(.kts) 檔案中的 plugins {} 區塊中新增 KSP。如果該處理器僅在特定模組中需要,請改為新增至該模組的 build.gradle(.kts) 檔案中:
// build.gradle.kts
plugins {
kotlin("jvm") version "2.4.21"
id("com.google.devtools.ksp") version "2.3.12"
}// build.gradle
plugins {
id 'org.jetbrains.kotlin.jvm' version '2.4.21'
id 'com.google.devtools.ksp' version '2.3.12'
}若要尋找 KSP 的最新版本,請查看 GitHub 的 Releases。
在頂層的 dependencies {} 區塊中,新增您想要使用的處理器。本範例使用 Moshi,但其他處理器的方法也相同:
// build.gradle.kts
dependencies {
ksp("com.squareup.moshi:moshi-kotlin-codegen:1.15.2")
}// build.gradle
dependencies {
ksp 'com.squareup.moshi:moshi-kotlin-codegen:1.15.2'
}ksp(...) 組態僅將處理器套用於應用程式原始碼。若要處理測試原始碼,請使用 kspTest(...) 組態新增處理器。
ksp(...) 組態僅適用於單平台專案。 若要了解如何為個別 Kotlin Multiplatform 目標和編譯設定處理器,請參閱 在 Kotlin Multiplatform 中使用 KSP。
建立您自己的處理器
按照以下步驟,您將建立一個產生 helloWorld() 函式的簡單註解處理器。 雖然在實務上用處不大,但它展示了建立您自己的處理器與註解的基本概念。
將 KSP 新增至專案
建立一個新的 Kotlin 專案並新增 KSP 外掛程式:
在 IntelliJ IDEA 中,選取 File | New | Project。
在左側清單中,選擇 Kotlin。
選擇 Gradle 作為建構系統,然後點擊 Create。

將 KSP 外掛程式新增至
build.gradle(.kts)檔案中:kotlin// build.gradle.kts plugins { kotlin("jvm") version "2.4.21" id("com.google.devtools.ksp") version "2.3.12" apply false }groovy// build.gradle plugins { id 'org.jetbrains.kotlin.jvm' version '2.4.21' id 'com.google.devtools.ksp' version '2.3.12' apply false }
建立註解
在專案根目錄下建立一個新模組並宣告一個註解:
選取 File | New | Module。
在左側清單中,選取 Kotlin。
指定下列欄位並點擊 create:
- Name:annotations
- Build system:Gradle

在該模組中,建立
HelloWorldAnnotation.kt檔案並宣告一個名為HelloWorldAnnotation的註解:kotlin// annotations/src/main/kotlin/com/example/annotations/HelloWorldAnnotation.kt package com.example.annotations annotation class HelloWorldAnnotation
建立並註冊處理器
在專案根目錄下建立另一個名為 processor 的模組。
在該模組的
build.gradle(.kts)檔案中,將 KSP API 以及您宣告的註解新增為相依性:kotlin// processor/build.gradle.kts plugins { kotlin("jvm") } dependencies { implementation(project(":annotations")) implementation("com.google.devtools.ksp:symbol-processing-api:2.3.6") }groovy// processor/build.gradle plugins { id 'org.jetbrains.kotlin.jvm' } dependencies { implementation project ':annotations' implementation 'com.google.devtools.ksp:symbol-processing-api:2.3.6' }在 processor 模組中,建立一個新的
HelloWorldProcessor.kt檔案並新增以下程式碼:kotlin// processor/src/main/kotlin/HelloWorldProcessor.kt class HelloWorldProcessor(val codeGenerator: CodeGenerator) : SymbolProcessor { // 1️⃣ process() 函式 override fun process(resolver: Resolver): List<KSAnnotated> { resolver .getSymbolsWithAnnotation("com.example.annotations.HelloWorldAnnotation") .filter { it.validate() } .filterIsInstance<KSFunctionDeclaration>() .forEach { it.accept(HelloWorldVisitor(), Unit) } return emptyList() } // 2️⃣ Visitor inner class HelloWorldVisitor : KSVisitorVoid() { override fun visitFunctionDeclaration(function: KSFunctionDeclaration, data: Unit) { createNewFileFrom(function).use { file -> file.write( """ fun helloWorld(): Unit { println("Hello world from function generated by KSP") } """.trimIndent() ) } } } // 3️⃣ createNewFileFrom() 函式 private fun createNewFileFrom(function: KSFunctionDeclaration): OutputStream { return codeGenerator.createNewFile( dependencies = createDependencyOn(function), packageName = "", fileName = "GeneratedHelloWorld" ) } // 3️⃣ createDependencyOn() 函式 private fun createDependencyOn(function: KSFunctionDeclaration): Dependencies { return Dependencies(aggregating = false, function.containingFile!!) } } // 用於將字串寫入 OutputStream 的公用程式函式 fun OutputStream.write(string: String): Unit { this.write(string.toByteArray()) }新增 IDE 建議的匯入項目。請確認從
com.google.devtools.ksp.processing匯入Resolver和Dependencies類別。或者,直接複製以下幾行至HelloWorldProcessor.kt的頂部:匯入陳述式 {...}
kotlin// processor/src/main/kotlin/HelloWorldProcessor.kt import com.google.devtools.ksp.processing.CodeGenerator import com.google.devtools.ksp.processing.Dependencies import com.google.devtools.ksp.processing.Resolver import com.google.devtools.ksp.processing.SymbolProcessor import com.google.devtools.ksp.symbol.KSAnnotated import com.google.devtools.ksp.symbol.KSFunctionDeclaration import com.google.devtools.ksp.symbol.KSVisitorVoid import com.google.devtools.ksp.validate import java.io.OutputStream讓我們逐一解析這段程式碼:
1️⃣
process()函式包含處理器的核心邏輯。它會取得所有標註有HelloWorldAnnotation的符號,並對每個符號呼叫HelloWorldVisitor。process()函式會回傳未處理的符號清單,以供後續輪次處理。在本範例中,它安全地回傳emptyList()。如需更多資訊,請參閱多輪次處理。2️⃣ 處理器透過 Visitor 遍歷 KSP 檢視下的 Kotlin 抽象語法樹 (AST)。在
HelloWorldProcessor類別內部,HelloWorldVisitor類別就是該 Visitor。由於HelloWorldAnnotation僅用於函式上,因此僅覆寫了visitFunctionDeclaration()。KSVisitorVoid是 KSP 提供的 Visitor 類別之一,您可以對其進行覆寫與調整。 您也可以透過實作KSVisitor<D, R>介面來建立自己的 Visitor。3️⃣
createNewFileFrom()會建立 KSP 產生程式碼的檔案。createDependencyOn()則讓產生的檔案相依於使用該註解的原始碼檔案。若要深入了解 KSP 如何建立和管理檔案,請參閱
CodeGenerator介面的原始碼。
建立一個
HelloWorldProcessorProvider.kt檔案。在其中宣告繼承自SymbolProcessorProvider的HelloWorldProcessorProvider類別:kotlin// processor/src/main/kotlin/HelloWorldProcessorProvider.kt import com.google.devtools.ksp.processing.SymbolProcessor import com.google.devtools.ksp.processing.SymbolProcessorEnvironment import com.google.devtools.ksp.processing.SymbolProcessorProvider class HelloWorldProcessorProvider : SymbolProcessorProvider { override fun create(environment: SymbolProcessorEnvironment): SymbolProcessor { return HelloWorldProcessor(environment.codeGenerator) } }註冊處理器提供者。在
resources/META-INF/services目錄中,建立一個名為com.google.devtools.ksp.processing.SymbolProcessorProvider的檔案,並填入提供者的完全限定類名:text## processor/src/main/resources/META-INF/services/com.google.devtools.ksp.processing.SymbolProcessorProvider HelloWorldProcessorProvider
使用您的處理器
現在您可以開始測試您的處理器了。請按照以下步驟建立用戶端模組,並讓您的處理器根據標註的元素產生程式碼:
在專案根目錄下建立一個名為
app的模組。在該模組的
build.gradle(.kts)檔案中:- 將 KSP 外掛程式新增至
plugins {}區塊。 - 將您的處理器和註解新增至
dependencies {}區塊。
例如:
kotlin// app/build.gradle.kts plugins { kotlin("jvm") id("com.google.devtools.ksp") } dependencies { implementation(project(":annotations")) ksp(project(":processor")) }groovy// app/build.gradle plugins { id 'com.google.devtools.ksp' } dependencies { implementation project (':annotations') ksp project (':processor') }- 將 KSP 外掛程式新增至
在專案層級的
settings.gradle(.kts)檔案中,確認所有子模組都已自動包含:kotlin// settings.gradle.kts include("annotations") include("app") include("processor")groovy// settings.gradle include 'processor' include 'annotations' include 'app'在
app模組中,建立一個Main.kt檔案並新增以下程式碼:kotlin// app/src/main/kotlin/Main.kt import com.example.annotations.HelloWorldAnnotation @HelloWorldAnnotation fun main() { helloWorld() }main()函式呼叫了helloWorld(),即使該函式目前尚不存在。您的 IDE 會將helloWorld()醒目提示為未定義的參照。這是正常現象:當您建置並執行專案時,KSP 即會產生helloWorld()函式。執行程式。您會在主控台中看到
helloWorld()函式的輸出:textHello world from function generated by KSPKSP 會在
GeneratedHelloWorld.kt檔案中產生程式碼:textapp/build/generated/ksp/main/kotlin/GeneratedHelloWorld.kt
探索專案結構
您專案的最終檔案結構應如下所示:
專案結構 {...}
.
├── app
│ ├── build.gradle.kts
│ └── src
│ └── main
│ └── kotlin
│ └── Main.kt
├── annotations
│ ├── build.gradle.kts
│ └── src
│ └── main
│ └── kotlin
| └── com
| └── example
| └── annotations
| └── HelloWorldAnnotation.kt
├── processor
│ ├── build.gradle.kts
│ └── src
│ └── main
│ ├── kotlin
│ │ ├── HelloWorldProcessor.kt
│ │ └── HelloWorldProcessorProvider.kt
│ └── resources/META-INF/services
| └── com.google.devtools.ksp.processing.SymbolProcessorProvider
├── build.gradle.kts
└── settings.gradle.kts您可能會有其他額外的檔案和目錄。
後續步驟?
- 在 KSP 儲存庫中瀏覽本範例的完整程式碼。
- 在 KSP 儲存庫中尋找更複雜的實際應用範例。
- 瀏覽支援 KSP 的程式庫清單。
