注解声明

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

annotation class Fancy

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

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

@Target(AnnotationTarget.CLASS, AnnotationTarget.FUNCTION,
        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{: .keyword} 关键字，并将注解添加到其前面：

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"))

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 这样的框架很有用，该框架使用注解进行并发控制。

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: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 注解

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
public @interface Ann {
    int intValue();
    String stringValue();
}

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

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

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

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

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

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

// Kotlin
@AnnWithArrayMethod(names = arrayOf("abc", "foo", "bar")) class C

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

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