Kotlin-34.注解(Annotation)

官方文档: http://kotlinlang.org/docs/reference/annotations.html

1.声明注解(Annotation Declaration)

和java类似,kotlin注解就是在代码中附加元数据(metadata),
声明注解(在class前面添加annotation修饰符):
    annotation class Fancy

和java注解类似,kotlin注解的附加属性可以通过元注解(meta-annotation)来声明指定,
kotlin元注解(meta-annotation)有以下几种:
    @Target 注解目标: 指定该注解用于什么类型的元素(类,函数,属性,表达式等);
    @Retention 注解保留: 指定该注解是否存在编译后的class文件,以及在运行时能否通过反射可见(默认都是true);
    @Repeatable 允许该注解在单个元素上多次使用;        
    @MustBeDocumented 指定该注解是公有API的一部分,且应该包含在生成的API文档中(类或方法的文档注释)

注解声明(包括元注解)的示例:
    @Target(AnnotationTarget.CLASS, //用于类
            AnnotationTarget.FUNCTION, //用于函数
            AnnotationTarget.VALUE_PARAMETER, //用于函数参数
            AnnotationTarget.EXPRESSION) //用于表达式
    @Retention(AnnotationRetention.SOURCE) //表示注解只存在源码,不在编译后的class文件
    @MustBeDocumented //包含在API文档中
    annotation class Fancy

2.使用注解(Usage)

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

1.对类的主构造函数进行注解,需要在构造函数前面添加constructor关键字,注解添加到它的前面:
    class Foo @Inject constructor(dependency: MyDependency) {
        //...
    }
    
2.对属性访问器(get/set)进行注解:
    class Foo {
        var x: MyDependency? = null
            @Inject set
    }

3.对Lambda表达式进行注解:    
    annotation class Suspendable

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

3.声明注解的构造函数(Constructors)

注解可以有构造函数(用于接受参数):
    //声明注解
    @Target(AnnotationTarget.CLASS)        
    annotation class Special(val why: String)

    //使用注解
    @Special("example") class Foo {}

1.kotlin注解的参数类型:
    和Java原生类型对应的kotlin类型(Int,Long等);
    字符串string;
    kotlin类class(Foo::class);
    枚举enum;
    其它注解;
    以上类型构成的数组; 

    提示: 注解参数不能有可空(null)类型，因为JVM不支持存储null作为注解属性值!

2.注解作为另一个注解的参数,不需要添加@前缀:
    annotation class ReplaceWith(val expression: String)

    //ReplaceWith作为注解参数时,不需要加@前缀
    annotation class Deprecated(
            val message: String,
            val replaceWith: ReplaceWith = ReplaceWith(""))

    @Deprecated("This function is deprecated, use === instead", 
        ReplaceWith("this === other"))

3.kotlin类作为注解的参数
如果需要将一个类指定为注解的参数,请用Kotlin类(KClass),
Kotlin编译器会自动将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

4.精确注解/使用处目标(Annotation Use-site Targets)

当对属性或主构造函数参数进行注解时,一个Kotlin属性元素会生成多个Java元素,
说白了就是,主构造函数参数(有val/var)就是kotlin类属性,
而[kotlin类属性]就相当于[Java类field字段+get方法+set方法],
因此在kotlin源码编译成Java字节码时,该注解可能同时在多个元素上!

1.对属性元素(set/get/field/param)进行精确注解:
    //Ann是注解,@xx:是固定语法
    class Example(@field:Ann val foo, //对Java 字段 进行注解
                @get:Ann val bar,     //对Java get方法 进行注解
                @param:Ann val quux)  //对Java 构造函数参数 进行注解

2.同一目标元素有多个注解,可在方括号[]添加多个注解,空格分隔：
    class Example {
        //collaborator的set方法有两个注解Inject和VisibleForTesting
        @set:[Inject VisibleForTesting] 
        var collaborator: Collaborator
    }

3.使用相同语法注解整个文件,把@file注解放在文件的顶层(package指令之前):
    @file:JvmName("Foo")
    package org.jetbrains.demo

4.使用处目标(use-site target)的完整列表:
    @file:
    @property: (具有此目标的注解对Java不可见)
    @field:
    @get:      (属性的getter方法)
    @set:      (属性的setter方法)
    @receiver: (扩展函数或属性的接收者参数)
    @param:    (构造函数参数)
    @setparam: (属性的setter方法参数)
    @delegate: (为委托属性存储其委托实例对象的字段)

    对扩展函数的接收者参数进行注解,语法如下:
        fun @receiver:Fancy String.myExtension() { }

    如果不指定使用处目标,则根据注解的@Target来选择目标,有多个适用目标,
    则用以下列表的第一个目标:
        param
        property
        field

5.在Kotlin中使用Java注解(Java Annotation)

Java注解 与Kotlin 100%兼容,示例如下:
    // 导入Java注解
    import org.junit.Test
    import org.junit.Assert.*
    import org.junit.Rule
    import org.junit.rules.*

    // kotlin代码,使用java注解
    class Tests {
        // @Rule注解用于tempFolder属性的getter方法/函数
        @get:Rule val tempFolder = TemporaryFolder()

        // @Test注解用于simple方法/函数
        @Test fun simple() {
            val f = tempFolder.newFile()
            assertEquals(42, getTheAnswer())
        }
    }

1.因为Java声明的注解没有定义参数顺序,所以kotlin需要使用命名参数来传递注解参数:
    // Java代码,声明注解Ann
    public @interface Ann {
        int intValue();
        String stringValue();
    }

    // Kotlin代码,命名参数传递注解参数
    @Ann(intValue = 1, stringValue = "abc") class C

2.在Java注解中,有一个特殊的value参数无需显式指定参数名:
    // Java
    public @interface AnnWithValue {
        String value();
    }

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

3.如果Java注解的value参数类型是数组,那么在Kotlin中该参数类型就是vararg(参数个数可变)：
    // Java
    public @interface AnnWithArrayValue {
        String[] value();
    }
    // Kotlin,参数类型是vararg(参数个数可变),相当于数组
    @AnnWithArrayValue("abc", "foo", "bar") class C

4.如果Java注解的其它参数类型是数组,那么在Kotlin中该参数需要显式使用arrayOf:
    // Java
    public @interface AnnWithArrayMethod {
        String[] names();
    }
    
    // Kotlin
    @AnnWithArrayMethod(names = arrayOf("abc", "foo", "bar")) class C

5.Java注解实例对象值会作为Kotlin属性,暴露给Kotlin代码:
    // Java
    public @interface Ann {
        int value();
    }

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

简书：http://www.jianshu.com/p/7ec60cc61c7b
CSDN博客: http://blog.csdn.net/qq_32115439/article/details/74781883
GitHub博客：http://lioil.win/2017/07/07/Kotlin-annotation.html
Coding博客：http://c.lioil.win/2017/07/07/Kotlin-annotation.html