注解 · Kotin知識點難點歸納總結

# 注解 [TOC] ## 注解聲明 **注解是將元數據附加到代碼的方法**。要聲明注解，請將**annotation修飾符**放在類的前面： ```kotlin annotation class Fancy ``` **注解的附加屬性可以通過用元注解標注注解類來指定**： * [`@Target`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.annotation/-target/index.html) 指定可以用該注解標注的元素的可能的類型（類、函數、屬性、表達式等）；注解目標：指定該注解用于什么類型的元素(類，函數，屬性，表達式等)； * [`@Retention`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.annotation/-retention/index.html) 指定該注解是否存儲在編譯后的 class 文件中，以及它在運行時能否通過反射可見(默認都是 true)。 * [`@Repeatable`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.annotation/-repeatable/index.html) 允許在單個元素上多次使用相同的該注解； * [`@MustBeDocumented`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.annotation/-must-be-documented/index.html) 指定該注解是公有 API 的一部分，并且應該包含在生成的 API文檔中顯示的類或方法的簽名中。 ```kotlin @Target(AnnotationTarget.CLASS, //用于類 AnnotationTarget.FUNCTION, //用于函數 AnnotationTarget.VALUE_PARAMETER, //用于函數參數 AnnotationTarget.EXPRESSION) //用于表達式 @Retention(AnnotationRetention.SOURCE) //表示注解只存在源碼,不在編譯后的class文件 @MustBeDocumented //包含在API文檔中 annotation class Fancy ``` ### 用法 ```kotlin @Fancy class Foo { @Fancy fun baz(@Fancy foo: Int): Int { return (@Fancy 1) } } ``` **如果需要對類的主構造函數進行標注，則需要在構造函數聲明中添加constructor關鍵字，并將注解添加到其前面**： ```kotlin class Foo @Inject constructor(dependency: MyDependency) { …… } ``` 你也可以標注屬性訪問器(get/set)： ```kotlin class Foo { var x: MyDependency? = null @Inject set } ``` 對Lambda表達式進行注解： ``` annotation class Suspendable val f = @Suspendable { Fiber.sleep(10) } ``` ### 構造函數 **注解可以有接受參數的構造函數**。 ```kotlin //聲明注解 annotation class Special(val why: String) //使用注解 @Special("example") class Foo {} ``` kotlin注解允許的參數類型有： * 對應于 Java 原生類型的類型（Int、 Long等）； * 字符串； * 類（`Foo::class`）； * 枚舉； * 其他注解； * 上面已列類型的數組。 >[info]注意：注解參數不能有可空類型，因為 JVM 不支持將 `null` 作為注解屬性的值存儲。 **如果注解用作另一個注解的參數，則其名稱不以 @ 字符為前綴**： ```kotlin annotation class ReplaceWith(val expression: String) annotation class Deprecated( val message: String, val replaceWith: ReplaceWith = ReplaceWith("")) @Deprecated("This function is deprecated, use === instead", ReplaceWith("this === other")) ``` **如果需要將一個類指定為注解的參數，請使用 Kotlin 類**（[KClass](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.reflect/-k-class/index.html)）。**Kotlin 編譯器會自動將其轉換為 Java 類，以便 Java 代碼能夠正常看到該注解及參數**。 ```kotlin import kotlin.reflect.KClass annotation class Ann(val arg1: KClass<*>, val arg2: KClass<out Any>) @Ann(String::class, Int::class) class MyClass ``` ### Lambda 表達式注解也可以用于 lambda 表達式。它們會被應用于生成lambda 表達式體的 `invoke()`方法上。這對于像 [Quasar](http://www.paralleluniverse.co/quasar/) 這樣的框架很有用，該框架使用注解進行并發控制。 ```kotlin annotation class Suspendable val f = @Suspendable { Fiber.sleep(10) } ``` ## 注解使用處目標當對屬性或主構造函數參數進行標注時，從相應的 Kotlin 元素生成的 Java 元素會有多個，因此在生成的 Java 字節碼中該注解有多個可能位置。說白了就是，**主構造函數參數(有val/var)就是kotlin類屬性，而[kotlin類屬性] = [Java類字段+get方法+set方法]，因此在kotlin源碼編譯成Java字節碼時，該注解可能同時在多個元素上**！如果要精確地指定應該如何生成該注解，請使用以下語法： 1、對屬性元素(set/get/field/param)進行精確注解： ```kotlin class Example(@field:Ann val foo, // 標注 Java 字段 @get:Ann val bar, // 標注 Java getter方法注解 @param:Ann val quux) // 標注 Java 構造函數參數 ``` 2、可使用相同的語法來標注注解整個文件。要做到這一點，把帶有目標 `file` 的注解放在文件的頂層、package 指令之前或者在所有導入之前（如果文件在默認包中的話）： ```kotlin @file:JvmName("Foo") package org.jetbrains.demo ``` 注解的完整列表： ``` @file 注解整個文件, 放在文件頂部(package指令之前) property 具有此目標的注解對Java不可見 field 字段,Java字段注解 get 屬性的getter方法,對Java get方法注解 set 屬性的setter方法,對Java set方法注解 receiver 擴展函數或屬性的接收者參數 param 構造函數參數 setparam 屬性的setter方法參數 delegate 為委托屬性存儲其委托實例對象的字段 ``` **3、如果你對同一目標有多個注解，那么可以這樣來避免目標重復——在目標后面添加方括號并將所有注解放在方括號內，空格分隔**： ```kotlin class Example { @set:[Inject VisibleForTesting] var collaborator: Collaborator } ``` 支持的使用處目標的完整列表為： * `file`； * `property`（具有此目標的注解對 Java 不可見）； * `field`； * `get`（屬性 getter）； * `set`（屬性 setter）； * `receiver`（擴展函數或屬性的接收者參數）； * `param`（構造函數參數）； * `setparam`（屬性 setter 參數）； * `delegate`（為委托屬性存儲其委托實例的字段）。 4、要標注擴展函數的接收者參數，請使用以下語法： ```kotlin fun @receiver:Fancy String.myExtension() { ... } ``` 如果不指定使用處目標，則根據正在使用的注解的 `@Target` 注解來選擇目標。如果有多個適用的目標，則使用以下列表中的第一個適用目標： * `param`; * `property`; * `field`. ## Java 注解 Java 注解與 Kotlin 100% 兼容： ```kotlin // 導入Java注解 import org.junit.Test import org.junit.Assert.* import org.junit.Rule import org.junit.rules.* // kotlin代碼,使用java注解 class Tests { // 將 @Rule 注解應用于屬性 getter @get:Rule val tempFolder = TemporaryFolder() // @Test注解用于simple方法/函數 @Test fun simple() { val f = tempFolder.newFile() assertEquals(42, getTheAnswer()) } } ``` 因為 Java 編寫的注解沒有定義參數順序，所以不能使用常規函數調用語法來傳遞參數。相反，你**需要使用命名參數語法**： ``` java // Java代碼，聲明注解Ann public @interface Ann { int intValue(); String stringValue(); } ``` ```kotlin // Kotlin代碼，命名參數傳遞注解參數 @Ann(intValue = 1, stringValue = "abc") class C ``` 就像在 Java 中一樣，一個特殊的情況是 `value` 參數；它的值無需顯式名稱指定： ``` java // Java public @interface AnnWithValue { String value(); } ``` ```kotlin // Kotlin @AnnWithValue("abc") class C ``` ### 數組作為注解參數如果 Java 中的 `value` 參數具有數組類型，它會成為 Kotlin 中的一個 `vararg` 參數(參數個數可變)： ``` java // Java public @interface AnnWithArrayValue { String[] value(); } ``` ```kotlin // Kotlin，參數類型是vararg(參數個數可變)，相當于數組 @AnnWithArrayValue("abc", "foo", "bar") class C ``` 對于具有數組類型的其他參數，你需要顯式使用數組字面值語法（自 Kotlin 1.2 起）或者`arrayOf(……)`： ``` java // Java public @interface AnnWithArrayMethod { String[] names(); } ``` ```kotlin // Kotlin 1.2+： @AnnWithArrayMethod(names = ["abc", "foo", "bar"]) class C // 舊版本 Kotlin： @AnnWithArrayMethod(names = arrayOf("abc", "foo", "bar")) class D ``` ### 訪問注解實例的屬性 **注解實例的值會作為屬性暴露給 Kotlin 代碼**： ``` java // Java public @interface Ann { int value(); } ``` ```kotlin // Kotlin fun foo(ann: Ann) { val i = ann.value } ```