# Kotlin 注解處理 [TOC] > 譯注：kapt 即 Kotlin annotation processing tool（Kotlin 注解處理工具）縮寫。 在 Kotlin 中通過 *kapt* 編譯器插件支持注解處理器（參見[JSR 269](https://jcp.org/en/jsr/detail?id=269)）。 簡而言之，你可以在 Kotlin 項目中使用像 [Dagger](https://google.github.io/dagger/) 或者 [Data Binding](https://developer.android.com/topic/libraries/data-binding/index.html) 這樣的庫。 關于如何將 *kapt* 插件應用于 Gradle/Maven 構建中，請閱讀下文。 ## 在 Gradle 中使用 應用 `kotlin-kapt` Gradle 插件： ```groovy //groovy plugins { id "org.jetbrains.kotlin.kapt" version "{{ site.data.releases.latest.version }}" } ``` ```kotlin //kotlin plugins { kotlin("kapt") version "{{ site.data.releases.latest.version }}" } ``` 或者使用 `apply plugin` 語法： ```groovy //groovy apply plugin: 'kotlin-kapt' ``` 然后在 `dependencies` 塊中使用 `kapt` 配置添加相應的依賴項： ```groovy //groovy dependencies { kapt 'groupId:artifactId:版本' } ``` ```kotlin //kotlin dependencies { kapt("groupId:artifactId:版本") } ``` 如果你以前使用 [Android 支持](https://developer.android.com/studio/build/gradle-plugin-3-0-0-migration.html#annotationProcessor_config)作為注解處理器，那么以 `kapt` 取代 `annotationProcessor` 配置的使用。如果你的項目包含 Java 類，`kapt` 也會顧全到它們。 如果為 `androidTest` 或 `test` 源代碼使用注解處理器，那么相應的 `kapt` 配置名為 `kaptAndroidTest` 和 `kaptTest`。請注意 `kaptAndroidTest` 和 `kaptTest` 擴展了 `kapt`，所以你可以只提供 `kapt` 依賴而它對生產和測試源代碼都可用。 ## 注解處理器參數 使用 `arguments {}` 塊將參數傳給注解處理器： ```groovy //groovy kapt { arguments { arg("key", "value") } } ``` ## Gradle 構建緩存支持（自 1.2.20 起） 默認情況下，kapt 注解處理任務就會[在 Gradle 中緩存](https://guides.gradle.org/using-build-cache/)。注解處理器所運行的任意代碼可能不一定將輸入轉換為輸出、可能訪問與修改 Gradle 未跟蹤的文件等。If the annotation processors used in the build cannot be properly cached, it is possible to disable caching for kapt entirely by adding the following lines to the build script, in order to avoid false-positive cache hits for the kapt tasks: ```groovy kapt { useBuildCache = false } ``` ## 并行運行 kapt 任務（自 1.2.60 起） To improve the speed of builds that use kapt, you can enable the [Gradle worker API](https://guides.gradle.org/using-the-worker-api/) for kapt tasks. Using the worker API lets Gradle run independent annotation processing tasks from a single project in parallel, which in some cases significantly decreases the execution time. However, running kapt with Gradle worker API enabled can result in increased memory consumption due to parallel execution. To use the Gradle worker API for parallel execution of kapt tasks, add this line to your `gradle.properties` file: ``` kapt.use.worker.api=true ``` ## kapt 的避免編譯（自 1.3.20 起） To improve the times of incremental builds with kapt, it can use the Gradle [compile avoidance](https://docs.gradle.org/current/userguide/java_plugin.html#sec:java_compile_avoidance). With compile avoidance enabled, Gradle can skip annotation processing when rebuilding a project. Particularly, annotation processing is skipped when: * The project's source files are unchanged. * The changes in dependencies are [ABI](https://en.wikipedia.org/wiki/Application_binary_interface) compatible. For example, the only changes are in method bodies. However, compile avoidance can't be used for annotation processors discovered in the compile classpath since _any changes_ in them require running the annotation processing tasks. To run kapt with compile avoidance: * Add the annotation processor dependencies to the `kapt*` configurations manually as described [above](http://www.kotlincn.net/docs/reference/kapt.html#%E5%9C%A8-gradle-%E4%B8%AD%E4%BD%BF%E7%94%A8). * Turn off the discovery of annotation processors in the compile classpath by adding this line to your `gradle.properties` file: ``` kapt.include.compile.classpath=false ``` ## 增量注解處理（自 1.3.30 起） Starting from version 1.3.30, kapt supports incremental annotation processing as an experimental feature. Currently, annotation processing can be incremental only if all annotation processors being used are incremental. To enable incremental annotation processing, add this line to your `gradle.properties` file: ``` kapt.incremental.apt=true ``` Note that incremental annotation processing requires [incremental compilation](http://www.kotlincn.net/docs/reference/using-gradle.html#%E5%A2%9E%E9%87%8F%E7%BC%96%E8%AF%91) to be enabled as well. ## Java 編譯器選項 Kapt 使用 Java 編譯器來運行注解處理器。以下是將任意選項傳給 javac 的方式： ```groovy kapt { javacOptions { // 增加注解處理器的最大錯誤次數 // 默認為 100。 option("-Xmaxerrs", 500) } } ``` ## 非存在類型校正 一些注解處理器（如 `AutoFactory`）依賴于聲明簽名中的精確類型。默認情況下，Kapt 將每個未知類型（包括生成的類的類型）替換為 `NonExistentClass`，但你可以更改此行為。將額外標志添加到 `build.gradle` 文件以啟用在存根（stub）中推斷出的錯誤類型： ```groovy kapt { correctErrorTypes = true } ``` ## 在 Maven 中使用 在 `compile` 之前在 kotlin-maven-plugin 中添加 `kapt` 目標的執行： ```xml <execution> <id>kapt</id> <goals> <goal>kapt</goal> </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> ``` 你可以在[Kotlin 示例版本庫](https://github.com/JetBrains/kotlin-examples/tree/master/maven/dagger-maven-example) 中找到一個顯示使用 Kotlin、Maven 和 Dagger 的完整示例項目。 請注意，IntelliJ IDEA 自身的構建系統目前還不支持 kapt。當你想要重新運行注解處理時，請從“Maven Projects”工具欄啟動構建。 ## 在命令行中使用 Kapt 編譯器插件已隨 Kotlin 編譯器的二進制發行版分發。可以使用 kotlinc 選項 `Xplugin` 提供該 JAR 文件的路徑來附加該插件： ```bash -Xplugin=$KOTLIN_HOME/lib/kotlin-annotation-processing.jar ``` 以下是可用選項的列表： * `sources`（*必需*）：所生成文件的輸出路徑。 * `classes`（*必需*）：所生成類文件與資源的輸出路徑。 * `stubs`（*必需*）：存根文件的輸出路徑。換句話說，一些臨時目錄。 * `incrementalData`：二進制存根的輸出路徑。 * `apclasspath`（*可重復*）：注解處理器 JAR 包路徑。如果有的多個 JAR 包就傳多個 `apclasspath` 選項。 * `apoptions`：注解處理器選項的 base64 編碼列表。詳見 [AP/javac options encoding](#apjavac-選項編碼)。 * `javacArguments`：傳給 javac 的選項的 base64 編碼列表。詳見 [AP/javac options encoding](#apjavac-選項編碼)。 * `processors`：逗號分隔的注解處理器全類名列表。如果指定，kapt 就不會嘗試在 `apclasspath` 中查找注解處理器。 * `verbose`：啟用詳細輸出。 * `aptMode`（*必需*） * `stubs`——只生成注解處理所需的存根； * `apt`——只運行注解處理； * `stubsAndApt`——生成存根并運行注解處理。 * `correctErrorTypes`：參見[下文](#在-gradle-中使用)。默認未啟用。 插件選項格式為：`-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"]` 所指定的目錄，這些文件會與主源代碼一起編譯。 可以在 [kotlin-examples](https://github.com/JetBrains/kotlin-examples/tree/master/gradle/kotlin-code-generation) Github 版本庫中找到完整的示例。 請注意，對于所生成 Kotlin 文件，Kapt 不支持多輪處理。 ## 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()) } ```