Kotlin学习（十四）: 类型别名(Type aliases)和注解(Annotations)

接下来学习Kotlin中的注解(Annotations)和类型别名(Type aliases)。

类型别名(Type aliases) 1.1版本

类型别名为现有类型提供替代名称。如果类型名称太长，您可以引入不同的较短的名称，并使用新的名称。
缩短长泛型类型：

typealias NodeSet = Set<Network.Node>

typealias FileTable<K> = MutableMap<K, MutableList<File>>

可以为功能类型提供不同的别名：

typealias MyHandler = (Int, String, Any) -> Unit

typealias Predicate<T> = (T) -> Boolean

可以为内部和嵌套类创建新名称：

class A {
    inner class Inner
}
class B {
    inner class Inner
}

typealias AInner = A.Inner
typealias BInner = B.Inner

Kotlin中定义的类型别名

类型别名不会引入新类型，它们相当于相应的底层类型，在代码中添加了typealias Predicate <T>并使用Predicate<Int>时，Kotlin编译器始终将其扩展为(Int) -> Boolean。
因此，只要需要一般功能类型，就可以传递类型的变量，反之亦然：

typealias Predicate<T> = (T) -> Boolean // 这里可以看出变量的类型是函数类型，参数是`T`，返回值是`Boolean`

/*
foo方法的返回值是Boolean，因为p的类型为Predicate<Int>，而Predicate<Int>是(Int) -> Boolean。
*/
fun foo(p: Predicate<Int>) = p(42)

fun main(args: Array<String>) {
    val f: (Int) -> Boolean = { it > 0 }
    println(foo(f)) // prints "true"

    val p: Predicate<Int> = { it > 0 } // 这里的Predicate<Int>等同于(Int) -> Boolean
    println(listOf(1, -2).filter(p)) // prints "[1]"
}

注解声明(Annotation Declaration)

与Java一样，Kotlin中也是有注解的，同样是用annotation关键字声明：

annotation class Fancy

Kotlin同样可以通过元注解来自定义注解，在这里介绍下元注解：

@Retention注解

指定该注解是否存储在编译后的Class文件中，以及它在运行时能否通过反射可见，有三个值，默认是AnnotationRetention.RUNTIME，分别为：
- AnnotationRetention.SOURCE：不存储在编译后的Class文件。
- AnnotationRetention.BINARY：存储在编译后的Class文件，但是反射不可见。
- AnnotationRetention.RUNTIME：存储在编译后的Class文件，反射可见。

@Target注解

表示该注解可以用于什么地方，类型有
- AnnotationTarget.CLASS：类，接口或对象，注解类也包括在内。
- AnnotationTarget.ANNOTATION_CLASS：只有注解类。
- AnnotationTarget.TYPE_PARAMETER：Generic type parameter (unsupported yet)通用类型参数（还不支持）。
- AnnotationTarget.PROPERTY：属性。
- AnnotationTarget.FIELD：字段，包括属性的支持字段。
- AnnotationTarget.LOCAL_VARIABLE：局部变量。
- AnnotationTarget.VALUE_PARAMETER：函数或构造函数的值参数。
- AnnotationTarget.CONSTRUCTOR：仅构造函数（主函数或者第二函数）。
- AnnotationTarget.FUNCTION：方法（不包括构造函数）。
- AnnotationTarget.PROPERTY_GETTER：只有属性的getter。
- AnnotationTarget.PROPERTY_SETTER：只有属性的setter。
- AnnotationTarget.TYPE：类型使用。
- AnnotationTarget.EXPRESSION：任何表达式。
- AnnotationTarget.FILE：文件。
- AnnotationTarget.TYPEALIAS：@SinceKotlin("1.1")类型别名，Kotlin1.1已可用。

@Repeatable注解

表示允许在同一申明类型（类，属性，或方法）的多次使用同一个注解

@MustBeDocumented注解

决定了注解是公共API的一部分，因此应该包含在用于注解的元素的生成文档注解中。

实例

这里声明一个Fancy注解：

@Target(AnnotationTarget.CLASS, AnnotationTarget.FUNCTION,
        AnnotationTarget.VALUE_PARAMETER, AnnotationTarget.EXPRESSION)
@Retention(AnnotationRetention.SOURCE)
@MustBeDocumented
annotation class Fancy

说明：Fancy注解可用在类，接口、对象、注解类、方法（不包括构造函数）、函数或构造函数的值参数和任何的表达式，不存储在编译后的Class文件，可用于生成文档中。

使用(Usage)

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

构造方法(Constructors)

带参数构造函数的注解：

annotation class Special(val why: String)

@Special("example") class Foo {}

参数类型可以有：
- 类型对应于Java原始类型（Int，Long等）
- 字符串
- 类（Foo::class）
- 枚举
- 其他注解
- 以上类型的数组

注解参数必须是nullable类型，因为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")) // 这里的ReplaceWith注解呗用作另一个注解的参数，则不需要加@符号

如果您需要将类指定为注解的参数，请使用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

Lambda

注解也可以用在lambda表达式中。

annotation class Suspendable

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

注解使用目标(Annotation Use-site Targets)

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

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

可以使用相同的语法来注解整个文件，但必须放在最上面，在包指令之前或在所有导入之前：

@file:JvmName("Foo")

package org.jetbrains.demo

如果有一个使用目标(Use-site Targets)具有多个注解，可以添加方括号[]，并将所有注解放在括号中：

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

使用例子：

annotation class Ann()
annotation class Annn()
class Example(@field:[Ann Annn] val foo: String) {
      @set:[Ann Annn]
      var fsoo: String = ""
}

使用目标(Use-site Targets)支持的有：
- file
- property使用此目标的注解对Java不可见
- field
- get 属性的getter
- set 属性的setter
- receiver 扩展函数或属性的接收器参数
- param 构造函数参数
- setparam 属性的setter的参数
- delegate 该字段存储代理属性的代理实例

其中，要注解扩展函数的接收器参数，请使用以下语法：

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

如果不指定使用目标(Use-site Targets)，则会根据所使用注解的@Target注解来选择目标。
如果有多个适用目标，则使用以下列表中的第一个适用目标：
- param
- property
- field

Java Annotations

Java注解与Kotlin 100％兼容：

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

class Tests {
      // apply @Rule annotation to property 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中调用，使用命名参数：

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

与Java一样，默认的参数名为value，它的值可以被指定而没有明确的名称：

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

参数名为默认值的时候，可以直接写值：

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

如果value的参数类型为数组类型的时候，在Kotlin中必须使用vararg这个参数类型：

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

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

如果参数名部位默认值并且为数组类型的时候：

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

在Kotlin中必须使用arrayOf，并且使用命名参数：

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

Java注解的实例的值可以做为Kotlin中的属性：

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

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