注解

注解是将元数据附加到代码的方法。要声明注解，请将 annotation 修饰符放在类的前面：

annotation class Fancy

注解的附加属性可以通过用元注解标注注解类来指定：

  • @Target 指定可以用该注解标注的元素的可能的类型（类、函数、属性与表达式）；
  • @Retention 指定该注解是否存储在编译后的 class 文件中，以及它在运行时能否通过反射可见 （默认都是 true）；
  • @Repeatable 允许在单个元素上多次使用相同的该注解；
  • @MustBeDocumented 指定该注解是公有 API 的一部分，并且应该包含在生成的 API 文档中显示的类或方法的签名中。
@Target(AnnotationTarget.CLASS, AnnotationTarget.FUNCTION,
        AnnotationTarget.TYPE_PARAMETER, AnnotationTarget.VALUE_PARAMETER, 
        AnnotationTarget.EXPRESSION)
@Retention(AnnotationRetention.SOURCE)
@MustBeDocumented
annotation class Fancy

用法

@Fancy class Foo {
    @Fancy fun baz(@Fancy foo: Int): Int {
        return (@Fancy 1)
    }
}

如果需要对类的主构造函数进行标注，则需要在构造函数声明中添加 constructor 关键字 ，并将注解添加到其前面：

class Foo @Inject constructor(dependency: MyDependency) { …… }

你也可以标注属性访问器：

class Foo {
    var x: MyDependency? = null
        @Inject set
}

构造函数

注解可以有接受参数的构造函数。

annotation class Special(val why: String)

@Special("example") class Foo {}

允许的参数类型有：

  • 对应于 Java 原生类型的类型（Int、 Long等）
  • 字符串
  • 类（Foo::class）
  • 枚举
  • 其他注解
  • 上面已列类型的数组

注解参数不能有可空类型，因为 JVM 不支持将 null 作为注解属性的值存储。

如果注解用作另一个注解的参数，则其名称不以 @ 字符为前缀：

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）。Kotlin 编译器会自动将其转换为 Java 类，以便 Java 代码能够正常访问该注解与参数 。


import kotlin.reflect.KClass

annotation class Ann(val arg1: KClass<*>, val arg2: KClass<out Any>)

@Ann(String::class, Int::class) class MyClass

Instantiation

In Java, an annotation type is a form of an interface, so you can implement it and use an instance. As an alternative to this mechanism, Kotlin lets you call a constructor of an annotation class in arbitrary code and similarly use the resulting instance.

annotation class InfoMarker(val info: String)

fun processInfo(marker: InfoMarker): Unit = TODO()

fun main(args: Array<String>) {
    if (args.isNotEmpty())
        processInfo(getAnnotationReflective(args))
    else
        processInfo(InfoMarker("default"))
}

Learn more about instantiation of annotation classes in this KEEP.

Lambda 表达式

注解也可以用于 lambda 表达式。它们会被应用于生成 lambda 表达式体的 invoke() 方法上。这对于像 Quasar 这样的框架很有用， 该框架使用注解进行并发控制。

annotation class Suspendable

val f = @Suspendable { Fiber.sleep(10) }

注解使用处目标

当对属性或主构造函数参数进行标注时，从相应的 Kotlin 元素生成的 Java 元素会有多个，因此在生成的 Java 字节码中该注解有多个可能位置 。如果要指定精确地指定应该如何生成该注解，请使用以下语法：

class Example(@field:Ann val foo,    // 标注 Java 字段
              @get:Ann val bar,      // 标注 Java getter
              @param:Ann val quux)   // 标注 Java 构造函数参数

可以使用相同的语法来标注整个文件。 要做到这一点，把带有目标 file 的注解放在文件的顶层、package 指令之前或者在所有导入之前（如果文件在默认包中的话）：

@file:JvmName("Foo")

package org.jetbrains.demo

如果你对同一目标有多个注解，那么可以这样来避免目标重复——在目标后面添加方括号并将所有注解放在方括号内：

class Example {
     @set:[Inject VisibleForTesting]
     var collaborator: Collaborator
}

支持的使用处目标的完整列表为：

  • file
  • property（具有此目标的注解对 Java 不可见）
  • field
  • get（属性 getter）
  • set（属性 setter）
  • receiver（扩展函数或属性的接收者参数）
  • param（构造函数参数）
  • setparam（属性 setter 参数）
  • delegate（为委托属性存储其委托实例的字段）

要标注扩展函数的接收者参数，请使用以下语法：

fun @receiver:Fancy String.myExtension() { ... }

如果不指定使用处目标，则根据正在使用的注解的 @Target 注解来选择目标 。如果有多个适用的目标，则使用以下列表中的第一个适用目标：

  • param
  • property
  • field

Java 注解

Java 注解与 Kotlin 100% 兼容：

import org.junit.Test
import org.junit.Assert.*
import org.junit.Rule
import org.junit.rules.*

class Tests {
    // 将 @Rule 注解应用于属性 getter
    @get:Rule val tempFolder = TemporaryFolder()

    @Test fun simple() {
        val f = tempFolder.newFile()
        assertEquals(42, getTheAnswer())
    }
}

因为 Java 编写的注解没有定义参数顺序，所以不能使用常规函数调用语法来传递参数。相反，你需要使用具名实参语法：

// Java
public @interface Ann {
    int intValue();
    String stringValue();
}

// Kotlin
@Ann(intValue = 1, stringValue = "abc") class C

就像在 Java 中一样，一个特殊的情况是 value 参数；它的值无需显式名称指定：

// Java
public @interface AnnWithValue {
    String value();
}

// Kotlin
@AnnWithValue("abc") class C

数组作为注解参数

如果 Java 中的 value 参数具有数组类型，它会成为 Kotlin 中的一个 vararg 参数：

// Java
public @interface AnnWithArrayValue {
    String[] value();
}

// Kotlin
@AnnWithArrayValue("abc", "foo", "bar") class C

对于具有数组类型的其他参数，你需要显式使用数组字面值语法或者 arrayOf(……)：

// Java
public @interface AnnWithArrayMethod {
    String[] names();
}

@AnnWithArrayMethod(names = ["abc", "foo", "bar"]) 
class C

访问注解实例的属性

注解实例的值会作为属性暴露给 Kotlin 代码：

// Java
public @interface Ann {
    int value();
}

// Kotlin
fun foo(ann: Ann) {
    val i = ann.value
}

Ability to not generate JVM 1.8+ annotation targets

If a Kotlin annotation has TYPE among its Kotlin targets, the annotation maps to java.lang.annotation.ElementType.TYPE_USE in its list of Java annotation targets. This is just like how the TYPE_PARAMETER Kotlin target maps to the java.lang.annotation.ElementType.TYPE_PARAMETER Java target. This is an issue for Android clients with API levels less than 26, which don't have these targets in the API.

To avoid generating the TYPE_USE and TYPE_PARAMETER annotation targets, use the new compiler argument -Xno-new-java-annotation-targets.

Repeatable annotations

Just like in Java, Kotlin has repeatable annotations, which can be applied to a single code element multiple times. To make your annotation repeatable, mark its declaration with the @kotlin.annotation.Repeatable meta-annotation. This will make it repeatable both in Kotlin and Java. Java repeatable annotations are also supported from the Kotlin side.

The main difference with the scheme used in Java is the absence of a containing annotation, which the Kotlin compiler generates automatically with a predefined name. For an annotation in the example below, it will generate the containing annotation @Tag.Container:

@Repeatable
annotation class Tag(val name: String)

// The compiler generates the @Tag.Container containing annotation

You can set a custom name for a containing annotation by applying the @kotlin.jvm.JvmRepeatable meta-annotation and passing an explicitly declared containing annotation class as an argument:

@JvmRepeatable(Tags::class)
annotation class Tag(val name: String)

annotation class Tags(val value: Array<Tag>)

To extract Kotlin or Java repeatable annotations via reflection, use the KAnnotatedElement.findAnnotations() function.

Learn more about Kotlin repeatable annotations in this KEEP.