注解 | Kotlin 语言参考文档中文版

注解的使用

@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 {}

注解的参数不能是可为 null 的类型, 因为 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

创建注解类的实例

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

Lambda 表达式

注解也可以用在 Lambda 上. 此时, Lambda 表达式的函数体内容将会生成一个invoke() 方法, 注解将被添加到这个方法上. 这个功能对于 Quasar 这样的框架非常有用, 因为这个框架使用注解来进行并发控制.

annotation class Suspendable

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

注解的使用目标(Use-site Target)

class Example(@field:Ann val foo,    // 只对 Java 域变量添加注解
              @get:Ann val bar,      // 只对属性的 Java get 方法添加注解
              @param:Ann val quux)   // 只对 Java 构造器参数添加注解

同样的语法也可以用来对整个源代码文件添加注解. 你可以添加一个目标为 file 的注解, 放在源代码文件的最顶端, package 指令之前, 如果这个源代码属于默认的包, 没有 package 指令, 则放在所有的 import 语句之前:

@file:JvmName("Foo")

package org.jetbrains.demo

如果你有目标相同的多个注解, 那么可以目标之后添加方括号, 然后将所有的注解放在方括号之内, 这样就可以避免重复指定相同的目标(all 目标除外):

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

file
field
property (使用这个目标的注解, 在 Java 中无法访问)
get (属性的 get 方法)
set (属性的 set 方法)
all (实验性功能, 用于属性的目标, 关于它的目的和使用方法, 请参见下文)
receiver (扩展函数或扩展属性的接受者参数)
要对扩展函数的接受者参数添加注解, 请使用以下语法:
```
fun @receiver:Fancy String.myExtension() { ... }
```
param (构造器的参数)
setparam (属性 set 方法的参数)
delegate (保存代理属性的代理对象实例的域变量)

没有指定使用目标时的默认值

如果不指定注解的使用目标, 那么将会根据这个注解的 @Target 注解来自动选定使用目标. 如果存在多个可用的目标, 将会使用以下列表中的第一个:

@Target(value={METHOD,FIELD,ANNOTATION_TYPE,CONSTRUCTOR,PARAMETER,TYPE_USE})
public @interface Email { }

data class User(val username: String,
                // 这里的 @Email 等于 @param:Email
                @Email val email: String) {
    // 这里的 @Email 等于 @field:Email
    @Email val secondaryEmail: String? = null
}

data class User(val username: String,
                // 这里的 @Email 现在会等于 @param:Email @field:Email
                @Email val email: String) {
    // 这里的 @Email 继续等于 @field:Email
    @Email val secondaryEmail: String? = null
}

如果存在多个目标, 并且 param, property, 或 field 都不可使用, 那么注解无效.

// build.gradle.kts
kotlin {
    compilerOptions {
        freeCompilerArgs.add("-Xannotation-default-target=param-property")
    }
}

在特定的情况下, 明确指定需要的目标, 例如, 使用 @param:Annotation, 而不是 @Annotation.

对整个项目, 在你的 Gradle 构建文件中使用以下设置:

// build.gradle.kts
kotlin {
    compilerOptions {
        freeCompilerArgs.add("-Xannotation-default-target=first-only")
    }
}

`all` meta-target

all 目标可以更容易的将同一个注解不仅应用于参数和属性或域变量, 而且应用于对应的 get 方法和 set 方法.

具体来说, 如果可用, 那么标注了 all 的注解会:

@Target(value={METHOD,FIELD,ANNOTATION_TYPE,CONSTRUCTOR,PARAMETER,TYPE_USE})
public @interface Email { }

在下面的示例中, 这个 @Email 注解被应用于所有相关的目标:

data class User(
    val username: String,
    // 将 `@Email` 应用到 `param`, `field` 和 `get`
    @all:Email val email: String,
    // 将 `@Email` 应用到 `param`, `field`, `get`, 和 `setparam`
    @all:Email var name: String,
) {
    // 将 `@Email` 应用到 `field` 和 `getter` (不应用于 `param`, 因为这个属性声明不在构造器中)
    @all:Email val secondaryEmail: String? = null
}

你可以对任何属性使用 all 目标, 无论是在主构造器之内还是之外.

限制

all 目标存在一些限制:

它不会将注解传播到类型, 潜在的扩展接受者, 或上下文接受者或参数.

它不能与多个注解一起使用:

@all:[A B] // 禁止这种用法, 请使用 `@all:A @all:B`
val x: Int = 5

它不能用于委托属性.

如何启用

要在你的项目中启用 all 目标, 请在命令行中使用以下编译器选项:

-Xannotation-target-all

或者, 添加到你的 Gradle 构建文件的 compilerOptions {} 代码段:

// build.gradle.kts
kotlin {
    compilerOptions {
        freeCompilerArgs.add("-Xannotation-target-all")
    }
}

Java 注解

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

class Tests {
    // 对属性的 get 方法使用 @Rule 注解
    @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 一样, 有一个特殊情况就是 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

访问注解实例的属性值

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

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

可重复注解

与 Java 中使用的方法的主要区别在于, 不存在容器注解(containing annotation), Kotlin 编译器会使用预定义的名称自动生成容器注解. 对于下面示例中的注解, 会生成名为 @Tag.Container 的容器注解:

@Repeatable
annotation class Tag(val name: String)

// 编译器生成名为 @Tag.Container 的容器注解

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

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

注解﻿

注解的使用﻿

构造器﻿

创建注解类的实例﻿

Lambda 表达式﻿

注解的使用目标(Use-site Target)﻿

没有指定使用目标时的默认值﻿

all meta-target﻿

限制﻿

如何启用﻿

Java 注解﻿

使用数组作为注解参数﻿

访问注解实例的属性值﻿

不生成 JVM 1.8+ 注解目标(Target)的能力﻿

可重复注解﻿

注解