編譯器插件 · Kotin知識點難點歸納總結

# 編譯器插件 [TOC] ## 全開放編譯器插件 Kotlin 的類及其成員默認是 `final` 的，這使得像 Spring AOP 這樣需要類為 `open` 的框架與庫用起來很不方便。這個 *all-open* 編譯器插件會適配 Kotlin 以滿足那些框架的需求，并使用指定的注解標注類而其成員無需顯式使用 `open` 關鍵字打開。例如，當你使用 Spring 時，你不需要打開所有的類，而只需要使用特定的注解標注，如 `@Configuration` 或 `@Service`。*All-open* 允許指定這些注解。我們為全開放插件提供 Gradle 與 Maven 支持并有完整的 IDE 集成。注意：對于 Spring，你可以使用 `kotlin-spring` 編譯器插件（[見下文](http://www.kotlincn.net/docs/reference/compiler-plugins.html#spring-%E6%94%AF%E6%8C%81)）。 ### 在 Gradle 中使用將插件構件添加到 buildscript 依賴中并應用該插件： ```groovy buildscript { dependencies { classpath "org.jetbrains.kotlin:kotlin-allopen:$kotlin_version" } } apply plugin: "kotlin-allopen" ``` 另一種方式是使用 `plugins` 塊啟用之： ```groovy plugins { id "org.jetbrains.kotlin.plugin.allopen" version "{{ site.data.releases.latest.version }}" } ``` 然后指定會打開類的注解的列表： ```groovy allOpen { annotation("com.my.Annotation") // annotations("com.another.Annotation", "com.third.Annotation") } ``` 如果類（或任何其超類）標有 `com.my.Annotation` 注解，類本身及其所有成員會變為開放。它也適用于元注解： ```kotlin @com.my.Annotation annotation class MyFrameworkAnnotation @MyFrameworkAnnotation class MyClass // 將會全開放 ``` `MyFrameworkAnnotation` 已由全開放元注解 `com.my.Annotation` 標注，所以它也成了一個全開放注解。 ### 在 Maven 中使用下面是全開放與 Maven 一起使用的用法： ```xml <plugin> <artifactId>kotlin-maven-plugin</artifactId> <groupId>org.jetbrains.kotlin</groupId> <version>${kotlin.version}</version> <configuration> <compilerPlugins>  <plugin>all-open</plugin> </compilerPlugins> <pluginOptions>  <option>all-open:annotation=com.my.Annotation</option> <option>all-open:annotation=com.their.AnotherAnnotation</option> </pluginOptions> </configuration> <dependencies> <dependency> <groupId>org.jetbrains.kotlin</groupId> <artifactId>kotlin-maven-allopen</artifactId> <version>${kotlin.version}</version> </dependency> </dependencies> </plugin> ``` 關于全開放注解如何工作的詳細信息，請參考上面的“在 Gradle 中使用”一節。 ### Spring 支持如果使用 Spring，可以啟用 *kotlin-spring* 編譯器插件而不是手動指定 Spring 注解。kotlin-spring 是在全開放之上的一層包裝，并且其運轉方式也完全相同。與全開放一樣，將該插件添加到 buildscript 依賴中： ```groovy buildscript { dependencies { classpath "org.jetbrains.kotlin:kotlin-allopen:$kotlin_version" } } apply plugin: "kotlin-spring" // 取代 "kotlin-allopen" ``` 或者使用 Gradle 插件 DSL： ```groovy plugins { id "org.jetbrains.kotlin.plugin.spring" version "{{ site.data.releases.latest.version }}" } ``` 在 Maven 中，則啟用 `spring` 插件： ```xml <compilerPlugins> <plugin>spring</plugin> </compilerPlugins> ``` 該插件指定了以下注解： [`@Component`](http://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/stereotype/Component.html)、 [`@Async`](http://docs.spring.io/spring/docs/current/javadoc-api/org/springframework/scheduling/annotation/Async.html)、 [`@Transactional`](http://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/transaction/annotation/Transactional.html)、 [`@Cacheable`](http://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/cache/annotation/Cacheable.html) 以及 [`@SpringBootTest`](https://docs.spring.io/spring-boot/docs/current/api/org/springframework/boot/test/context/SpringBootTest.html)。由于元注解的支持，標注有 [`@Configuration`](https://docs.spring.io/spring/docs/current/javadoc-api/org/springframework/context/annotation/Configuration.html)、 [`@Controller`](https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/stereotype/Controller.html)、 [`@RestController`](https://docs.spring.io/spring/docs/current/javadoc-api/org/springframework/web/bind/annotation/RestController.html)、 [`@Service`](https://docs.spring.io/spring/docs/current/javadoc-api/org/springframework/stereotype/Service.html) 或者 [`@Repository`](https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/stereotype/Repository.html) 的類會自動打開，因為這些注解標注有元注解 [`@Component`](http://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/stereotype/Component.html)。當然，你可以在同一個項目中同時使用 `kotlin-allopen` 與 `kotlin-spring`。請注意，如果使用 [start.spring.io](http://start.spring.io/#!language=kotlin) 服務生成的項目模板，那么默認會啟用 `kotlin-spring` 插件。 ### 在命令行中使用全開放編譯器插件的 JAR 包已隨 Kotlin 編譯器的二進制發行版分發。可以使用 kotlinc 選項 `Xplugin` 提供該 JAR 文件的路徑來附加該插件： ```bash -Xplugin=$KOTLIN_HOME/lib/allopen-compiler-plugin.jar ``` 可以使用 `annotation` 插件選項或者啟用“預設”來直接指定全開放注解。現在可用于全開放的唯一預設是 `spring`。 ```bash # The plugin option format is: "-P plugin:<plugin id>:<key>=<value>". # Options can be repeated. -P plugin:org.jetbrains.kotlin.allopen:annotation=com.my.Annotation -P plugin:org.jetbrains.kotlin.allopen:preset=spring ``` ## 無參編譯器插件 *無參（no-arg）*編譯器插件為具有特定注解的類生成一個額外的零參數構造函數。這個生成的構造函數是合成的，因此不能從 Java 或 Kotlin 中直接調用，但可以使用反射調用。這允許 Java Persistence API（JPA）實例化一個類，就算它從 Kotlin 或 Java 的角度看沒有無參構造函數（參見[下面](http://www.kotlincn.net/docs/reference/compiler-plugins.html#jpa-%E6%94%AF%E6%8C%81)的 `kotlin-jpa` 插件的描述）。 ### 在 Gradle 中使用其用法非常類似于全開放插件。添加該插件并指定注解的列表，這些注解一定會導致被標注的類生成無參構造函數。 ```groovy buildscript { dependencies { classpath "org.jetbrains.kotlin:kotlin-noarg:$kotlin_version" } } apply plugin: "kotlin-noarg" ``` 或者使用 Gradle 插件 DSL： ```groovy plugins { id "org.jetbrains.kotlin.plugin.noarg" version "{{ site.data.releases.latest.version }}" } ``` 然后指定無參注解列表： ```groovy noArg { annotation("com.my.Annotation") } ``` 如果希望該插件在合成的構造函數中運行其初始化邏輯，請啟用 `invokeInitializers` 選項。由于在未來會解決的 [`KT-18667`](https://youtrack.jetbrains.com/issue/KT-18667) 及 [`KT-18668`](https://youtrack.jetbrains.com/issue/KT-18668)，自 Kotlin 1.1.3-2 起，它被默認禁用。 ```groovy noArg { invokeInitializers = true } ``` ### 在 Maven 中使用 ```xml <plugin> <artifactId>kotlin-maven-plugin</artifactId> <groupId>org.jetbrains.kotlin</groupId> <version>${kotlin.version}</version> <configuration> <compilerPlugins>  <plugin>no-arg</plugin> </compilerPlugins> <pluginOptions> <option>no-arg:annotation=com.my.Annotation</option>   </pluginOptions> </configuration> <dependencies> <dependency> <groupId>org.jetbrains.kotlin</groupId> <artifactId>kotlin-maven-noarg</artifactId> <version>${kotlin.version}</version> </dependency> </dependencies> </plugin> ``` ### JPA 支持與 *kotlin-spring* 插件類似，*kotlin-jpa* 是在 *no-arg* 之上的一層包裝。該插件自動指定了 [`@Entity`](http://docs.oracle.com/javaee/7/api/javax/persistence/Entity.html)、 [`@Embeddable`](http://docs.oracle.com/javaee/7/api/javax/persistence/Embeddable.html) 與 [`@MappedSuperclass`](https://docs.oracle.com/javaee/7/api/javax/persistence/MappedSuperclass.html) 這幾個 *無參* 注解。這是在 Gradle 中添加該插件的方法： ``` groovy buildscript { dependencies { classpath "org.jetbrains.kotlin:kotlin-noarg:$kotlin_version" } } apply plugin: "kotlin-jpa" ``` 或者使用 Gradle 插件 DSL： ```groovy plugins { id "org.jetbrains.kotlin.plugin.jpa" version "{{ site.data.releases.latest.version }}" } ``` 在 Maven 中，則啟用 `jpa` 插件： ```xml <compilerPlugins> <plugin>jpa</plugin> </compilerPlugins> ``` ### 在命令行中使用與全開放類似，將插件 JAR 文件添加到編譯器插件類路徑并指定注解或預設 ```bash -Xplugin=$KOTLIN_HOME/lib/noarg-compiler-plugin.jar -P plugin:org.jetbrains.kotlin.noarg:annotation=com.my.Annotation -P plugin:org.jetbrains.kotlin.noarg:preset=jpa ``` ## 帶有接收者的 SAM 編譯器插件編譯器插件 *sam-with-receiver* 使所注解的 Java“單抽象方法”接口方法的第一個參數成為 Kotlin 中的接收者。這一轉換只適用于當 SAM 接口作為 Kotlin 的 lambda 表達式傳遞時，對 SAM 適配器與 SAM 構造函數均適用（詳見其[文檔](http://www.kotlincn.net/docs/reference/java-interop.html#sam-%E8%BD%AC%E6%8D%A2)）。這里有一個示例： ```java public @interface SamWithReceiver {} @SamWithReceiver public interface TaskRunner { void run(Task task); } ``` ```kotlin fun test(context: TaskContext) { val runner = TaskRunner { // 這里的“this”是“Task”的一個實例 println("$name is started") context.executeTask(this) println("$name is finished") } } ``` ### 在 Gradle 中使用除了事實上 sam-with-receiver 沒有任何內置預設、并且需要指定自己的特殊處理注解列表外，其用法與 all-open 及 no-arg 相同。 ```groovy buildscript { dependencies { classpath "org.jetbrains.kotlin:kotlin-sam-with-receiver:$kotlin_version" } } apply plugin: "kotlin-sam-with-receiver" ``` 然后指定 SAM-with-receiver 的注解列表： ```groovy samWithReceiver { annotation("com.my.SamWithReceiver") } ``` ### 在 Maven 中使用 ```xml <plugin> <artifactId>kotlin-maven-plugin</artifactId> <groupId>org.jetbrains.kotlin</groupId> <version>${kotlin.version}</version> <configuration> <compilerPlugins> <plugin>sam-with-receiver</plugin> </compilerPlugins> <pluginOptions> <option> sam-with-receiver:annotation=com.my.SamWithReceiver </option> </pluginOptions> </configuration> <dependencies> <dependency> <groupId>org.jetbrains.kotlin</groupId> <artifactId>kotlin-maven-sam-with-receiver</artifactId> <version>${kotlin.version}</version> </dependency> </dependencies> </plugin> ``` ### 在 CLI 中使用只需將該插件的 JAR 文件添加到編譯器插件類路徑中，并指定 sam-with-receiver 注解列表即可： ```bash -Xplugin=$KOTLIN_HOME/lib/sam-with-receiver-compiler-plugin.jar -P plugin:org.jetbrains.kotlin.samWithReceiver:annotation=com.my.SamWithReceiver ```