kapt 編譯器外掛程式

kapt 處於維護模式。我們將其與最新的 Kotlin 和 Java 版本保持同步，但沒有計劃實施新功能。請使用 Kotlin 符號處理 API (KSP) 進行註解處理。請參閱 KSP 支援的函式庫列表。

Kotlin 透過 kapt 編譯器外掛程式支援註解處理器（請參閱 JSR 269）。

簡而言之，kapt 透過啟用基於 Java 的註解處理，協助您在 Kotlin 專案中使用 Dagger 和資料繫結 (Data Binding) 等函式庫。

如果您在使用 kapt 搭配 K2 編譯器時遇到任何問題，請向我們的問題追蹤器回報，並在您的 gradle.properties 檔案中停用 K2 模式：
kotlin
kapt.use.k2=false

在 Gradle 中使用

要在 Gradle 中使用 kapt，請依照以下步驟操作：

在您的建置指令碼檔案 build.gradle(.kts) 中應用 kapt Gradle 外掛程式：

KotlinGroovy

kotlin

plugins {
    kotlin("kapt") version "2.2.10"
}

groovy

plugins {
    id "org.jetbrains.kotlin.kapt" version "2.2.10"
}

在 dependencies {} 區塊中使用 kapt 配置新增相應的依賴項：

KotlinGroovy

kotlin

dependencies {
    kapt("groupId:artifactId:version")
}

groovy

dependencies {
    kapt 'groupId:artifactId:version'
}

如果您之前曾使用 Android 支援進行註解處理器，請將 annotationProcessor 配置的用法替換為 kapt。如果您的專案包含 Java 類別，kapt 也會處理它們。
如果您將註解處理器用於您的 androidTest 或 test 來源，則相應的 kapt 配置名稱為 kaptAndroidTest 和 kaptTest。請注意，kaptAndroidTest 和 kaptTest 繼承自 kapt，因此您可以提供 kapt 依賴項，它將同時適用於生產來源和測試。

註解處理器引數

在您的建置指令碼檔案 build.gradle(.kts) 中使用 arguments {} 區塊將引數傳遞給註解處理器：

kotlin

kapt {
    arguments {
        arg("key", "value")
    }
}

Gradle 建置快取支援

kapt 註解處理任務預設情況下在 Gradle 中進行快取。然而，註解處理器可以執行任意程式碼，這可能無法可靠地將任務輸入轉換為輸出，或者可能存取和修改 Gradle 未追蹤的檔案。如果建置中使用的註解處理器無法正確快取，您可以透過在建置指令碼中指定 useBuildCache 屬性來完全停用 kapt 的快取。這有助於防止 kapt 任務的誤報快取命中：

groovy

kapt {
    useBuildCache = false
}

提升使用 kapt 的建置速度

平行執行 kapt 任務

為了提升使用 kapt 的建置速度，您可以為 kapt 任務啟用 Gradle Worker API。使用 Worker API 讓 Gradle 能夠平行執行單一專案中獨立的註解處理任務，這在某些情況下能顯著縮短執行時間。

當您在 Kotlin Gradle 外掛程式中使用自訂 JDK 主目錄功能時，kapt 任務 Worker 僅使用程序隔離模式。請注意，kapt.workers.isolation 屬性會被忽略。

如果您想為 kapt Worker 程序提供額外的 JVM 引數，請使用 KaptWithoutKotlincTask 的輸入 kaptProcessJvmArgs：

KotlinGroovy

kotlin

tasks.withType<org.jetbrains.kotlin.gradle.internal.KaptWithoutKotlincTask>()
    .configureEach {
        kaptProcessJvmArgs.add("-Xmx512m")
    }

groovy

tasks.withType(org.jetbrains.kotlin.gradle.internal.KaptWithoutKotlincTask.class)
    .configureEach {
        kaptProcessJvmArgs.add('-Xmx512m')
    }

Experimental

註解處理器類別載入器的快取

實驗性功能

註解處理器類別載入器的快取有助於 kapt 在您連續執行多個 Gradle 任務時更快地執行。

要啟用此功能，請在您的 gradle.properties 檔案中使用以下屬性：

none

# gradle.properties
#
# Any positive value enables caching
# Use the same value as the number of modules that use kapt
kapt.classloaders.cache.size=5

# Disable for caching to work
kapt.include.compile.classpath=false

如果您在註解處理器的快取方面遇到任何問題，請停用它們的快取：

none

# Specify annotation processors' full names to disable caching for them
kapt.classloaders.cache.disableForProcessors=[annotation processors full names]

如果您遇到此功能的任何問題，我們將感謝您在 YouTrack 中提供回饋。

測量註解處理器的效能

要獲取註解處理器執行的效能統計資料，請使用 -Kapt-show-processor-timings 外掛程式選項。範例輸出：

text

Kapt Annotation Processing performance report:
com.example.processor.TestingProcessor: total: 133 ms, init: 36 ms, 2 round(s): 97 ms, 0 ms
com.example.processor.AnotherProcessor: total: 100 ms, init: 6 ms, 1 round(s): 93 ms

您可以使用外掛程式選項 -Kapt-dump-processor-timings (org.jetbrains.kotlin.kapt3:dumpProcessorTimings) 將此報告傾印到檔案中。以下命令將執行 kapt 並將統計資料傾印到 ap-perf-report.file 檔案中：

bash

kotlinc -cp $MY_CLASSPATH \
-Xplugin=kotlin-annotation-processing-SNAPSHOT.jar -P \
plugin:org.jetbrains.kotlin.kapt3:aptMode=stubsAndApt,\
plugin:org.jetbrains.kotlin.kapt3:apclasspath=processor/build/libs/processor.jar,\
plugin:org.jetbrains.kotlin.kapt3:dumpProcessorTimings=ap-perf-report.file \
-Xplugin=$JAVA_HOME/lib/tools.jar \
-d cli-tests/out \
-no-jdk -no-reflect -no-stdlib -verbose \
sample/src/main/

測量使用註解處理器生成的檔案數量

kapt Gradle 外掛程式可以報告每個註解處理器生成的檔案數量的統計資料。

這有助於追蹤建置中是否包含任何未使用的註解處理器。您可以使用生成的報告來查找觸發不必要註解處理器的模組，並更新這些模組以避免這種情況。

要啟用統計報告：

在您的 build.gradle(.kts) 中將 showProcessorStats 屬性值設定為 true：
kotlin
```
// build.gradle.kts
kapt {
    showProcessorStats = true
}
```
在您的 gradle.properties 中將 kapt.verbose Gradle 屬性設定為 true：
none
```
# gradle.properties
kapt.verbose=true
```

您也可以透過命令列選項 verbose 啟用詳細輸出。

統計資料會以 info 等級顯示在日誌中。您會看到 Annotation processor stats: 行，其後是每個註解處理器執行時間的統計資料。這些行之後是 Generated files report: 行，其後是每個註解處理器生成的檔案數量的統計資料。例如：

text

[INFO] Annotation processor stats:
[INFO] org.mapstruct.ap.MappingProcessor: total: 290 ms, init: 1 ms, 3 round(s): 289 ms, 0 ms, 0 ms
[INFO] Generated files report:
[INFO] org.mapstruct.ap.MappingProcessor: total sources: 2, sources per round: 2, 0, 0

kapt 的編譯避免

為了改進使用 kapt 的增量建置時間，它可以使用 Gradle 編譯避免。啟用編譯避免後，Gradle 可以在重建專案時跳過註解處理。特別是，在以下情況下會跳過註解處理：

專案的原始檔未更改。
依賴項中的更改是 ABI 相容的。例如，僅方法主體有更改。

然而，編譯避免不能用於在編譯類別路徑中發現的註解處理器，因為它們的 任何更改 都需要執行註解處理任務。

要使用編譯避免來執行 kapt：

手動將註解處理器依賴項新增到 kapt* 配置中。
在 gradle.properties 檔案中關閉編譯類別路徑中註解處理器的發現：
none
```
# gradle.properties
kapt.include.compile.classpath=false
```

增量註解處理

kapt 預設支援增量註解處理。目前，註解處理只有在所有正在使用的註解處理器都是增量時才能增量。

要停用增量註解處理，請將此行新增到您的 gradle.properties 檔案中：

none

kapt.incremental.apt=false

請注意，增量註解處理也需要啟用增量編譯。

從超配置繼承註解處理器

您可以將一組常見的註解處理器定義為單獨的 Gradle 配置中的超配置，並在您的子專案的 kapt 特定配置中進一步擴展它。

例如，對於使用 Dagger 的子專案，在您的 build.gradle(.kts) 檔案中，請使用以下配置：

kotlin

val commonAnnotationProcessors by configurations.creating
configurations.named("kapt") { extendsFrom(commonAnnotationProcessors) }

dependencies {
    implementation("com.google.dagger:dagger:2.48.1")
    commonAnnotationProcessors("com.google.dagger:dagger-compiler:2.48.1")
}

在此範例中，commonAnnotationProcessors Gradle 配置是您希望用於所有專案的註解處理的通用超配置。您使用 extendsFrom() 方法將 commonAnnotationProcessors 新增為超配置。kapt 看到 commonAnnotationProcessors Gradle 配置對 Dagger 註解處理器有依賴項。因此，kapt 在其註解處理配置中包含了 Dagger 註解處理器。

Java 編譯器選項

kapt 使用 Java 編譯器來執行註解處理器。以下是如何將任意選項傳遞給 javac：

groovy

kapt {
    javacOptions {
        // 增加來自註解處理器的最大錯誤數量。預設值為 100。
        option("-Xmaxerrs", 500)
    }
}

不存在的類型校正

一些註解處理器（例如 AutoFactory）依賴於宣告簽章中的精確類型。預設情況下，kapt 會將每個未知類型（包括生成類別的類型）替換為 NonExistentClass，但您可以更改此行為。將該選項新增到 build.gradle(.kts) 檔案中以在 Stub 中啟用錯誤類型推斷：

groovy

kapt {
    correctErrorTypes = true
}

在 Maven 中使用

在 compile 之前，新增 kotlin-maven-plugin 中 kapt 目標的執行：

xml

<execution>
    <id>kapt</id>
    <goals>
        <goal>kapt</goal> <!-- 如果您為外掛程式啟用擴展，則可以跳過 <goals> 元素 -->
    </goals>
    <configuration>
        <sourceDirs>
            <sourceDir>src/main/kotlin</sourceDir>
            <sourceDir>src/main/java</sourceDir>
        </sourceDirs>
        <annotationProcessorPaths>
            <!-- 在此處指定您的註解處理器 -->
            <annotationProcessorPath>
                <groupId>com.google.dagger</groupId>
                <artifactId>dagger-compiler</artifactId>
                <version>2.9</version>
            </annotationProcessorPath>
        </annotationProcessorPaths>
    </configuration>
</execution>

要配置註解處理的等級，請在 <configuration> 區塊中設定以下任一 aptMode：

stubs – 僅生成註解處理所需的 Stub。
apt – 僅執行註解處理。
stubsAndApt – (預設) 生成 Stub 並執行註解處理。

例如：

xml

<configuration>
   ...
   <aptMode>stubs</aptMode>
</configuration>

在 IntelliJ 建置系統中使用

IntelliJ IDEA 自身的建置系統不支援 kapt。每當您想重新執行註解處理時，請從「Maven Projects」工具列啟動建置。

在命令列介面中使用

kapt 編譯器外掛程式在 Kotlin 編譯器的二進位發行版中可用。

您可以透過使用 Xplugin kotlinc 選項提供其 JAR 檔案的路徑來附加外掛程式：

bash

-Xplugin=$KOTLIN_HOME/lib/kotlin-annotation-processing.jar

以下是可用選項的列表：

sources (必填): 生成檔案的輸出路徑。
classes (必填): 生成類別檔案和資源的輸出路徑。
stubs (必填): Stub 檔案的輸出路徑。換句話說，一些暫存目錄。
incrementalData: 二進位 Stub 的輸出路徑。
apclasspath (可重複): 註解處理器 JAR 的路徑。根據您擁有的 JAR 數量，傳遞相同數量的 apclasspath 選項。
apoptions: 註解處理器選項的 Base64 編碼列表。有關詳細資訊，請參閱 AP/javac 選項編碼。
javacArguments: 傳遞給 javac 的選項的 Base64 編碼列表。有關詳細資訊，請參閱 AP/javac 選項編碼。
processors: 以逗號分隔的註解處理器合格類別名稱列表。如果指定，kapt 不會嘗試在 apclasspath 中查找註解處理器。
verbose: 啟用詳細輸出。
aptMode (必填)
- stubs – 僅生成註解處理所需的 Stub。
- apt – 僅執行註解處理。
- stubsAndApt – 生成 Stub 並執行註解處理。
correctErrorTypes: 有關詳細資訊，請參閱不存在的類型校正。預設情況下停用。
dumpFileReadHistory: 每個檔案的輸出路徑，用於傾印在註解處理期間使用的類別列表。

外掛程式選項格式為：-P plugin:<plugin id>:<key>=<value>。選項可以重複。

範例：

bash

-P plugin:org.jetbrains.kotlin.kapt3:sources=build/kapt/sources
-P plugin:org.jetbrains.kotlin.kapt3:classes=build/kapt/classes
-P plugin:org.jetbrains.kotlin.kapt3:stubs=build/kapt/stubs

-P plugin:org.jetbrains.kotlin.kapt3:apclasspath=lib/ap.jar
-P plugin:org.jetbrains.kotlin.kapt3:apclasspath=lib/anotherAp.jar

-P plugin:org.jetbrains.kotlin.kapt3:correctErrorTypes=true

生成 Kotlin 來源

kapt 可以生成 Kotlin 來源。只需將生成的 Kotlin 來源檔案寫入由 processingEnv.options["kapt.kotlin.generated"] 指定的目錄，這些檔案將與主要來源一起編譯。

請注意，kapt 不支援對生成的 Kotlin 檔案進行多輪處理。

AP/Javac 選項編碼

apoptions 和 javacArguments 命令列介面選項接受選項的編碼映射。以下是如何自行編碼選項：

kotlin

fun encodeList(options: Map<String, String>): String {
    val os = ByteArrayOutputStream()
    val oos = ObjectOutputStream(os)

    oos.writeInt(options.size)
    for ((key, value) in options.entries) {
        oos.writeUTF(key)
        oos.writeUTF(value)
    }

    oos.flush()
    return Base64.getEncoder().encodeToString(os.toByteArray())
}

保留 Java 編譯器的註解處理器

預設情況下，kapt 執行所有註解處理器並停用 javac 的註解處理。然而，您可能需要一些 javac 的註解處理器正常運作（例如 Lombok）。

在 Gradle 建置檔案中，使用選項 keepJavacAnnotationProcessors：

groovy

kapt {
    keepJavacAnnotationProcessors = true
}

如果您使用 Maven，則需要指定具體的外掛程式設定。請參閱 Lombok 編譯器外掛程式設定的範例。

基本類型

建構器

Spring

使用 Spring Boot 建立一個包含資料庫的 RESTful Web 服務

Java 遷移至 Kotlin 指南

C 互通

Objective-C 互通

記憶體管理器

參考與提示

用於 JS 平台的 Kotlin

概覽

執行 Dokka

輸出格式

最小化心智複雜度

kapt 編譯器外掛程式

在 Gradle 中使用

註解處理器引數

Gradle 建置快取支援

提升使用 kapt 的建置速度

平行執行 kapt 任務

註解處理器類別載入器的快取

測量註解處理器的效能

測量使用註解處理器生成的檔案數量

kapt 的編譯避免

增量註解處理

從超配置繼承註解處理器

Java 編譯器選項

不存在的類型校正

在 Maven 中使用

在 IntelliJ 建置系統中使用

在命令列介面中使用

生成 Kotlin 來源

AP/Javac 選項編碼

保留 Java 編譯器的註解處理器

使用 Spring Boot 建立一個包含資料庫的 RESTful Web 服務

kapt 編譯器外掛程式 ​

在 Gradle 中使用 ​

註解處理器引數 ​

Gradle 建置快取支援 ​

提升使用 kapt 的建置速度 ​

平行執行 kapt 任務 ​

註解處理器類別載入器的快取

測量註解處理器的效能 ​

測量使用註解處理器生成的檔案數量 ​

kapt 的編譯避免 ​

增量註解處理 ​

從超配置繼承註解處理器 ​

Java 編譯器選項 ​

不存在的類型校正 ​

在 Maven 中使用 ​

在 IntelliJ 建置系統中使用 ​

在命令列介面中使用 ​

生成 Kotlin 來源 ​

AP/Javac 選項編碼 ​

保留 Java 編譯器的註解處理器 ​

kapt 編譯器外掛程式

在 Gradle 中使用

註解處理器引數

Gradle 建置快取支援

提升使用 kapt 的建置速度

平行執行 kapt 任務

測量註解處理器的效能

測量使用註解處理器生成的檔案數量

kapt 的編譯避免

增量註解處理

從超配置繼承註解處理器

Java 編譯器選項

不存在的類型校正

在 Maven 中使用

在 IntelliJ 建置系統中使用

在命令列介面中使用

生成 Kotlin 來源

AP/Javac 選項編碼

保留 Java 編譯器的註解處理器