Kotlin知识归纳（十三） —— 注解

前序

      注解是什么？简单说注解就是一种标注（标记、标识），没有具体的功能逻辑代码。通过注解开发人员可以在不改变原有代码和逻辑的情况下在源代码中嵌入补充信息。Kotlin注解的使用和Java完全一样，声明注解类的语法略有不同。Java 注解与 Kotlin 100% 兼容。

注解的定义

      注解可以把额外的元数据关联到一个声明上，然后元数据可以被反射机制或相关的源代码工具访问。

声明Kotlin的注解

      Kotlin的声明注解的语法和常规类的声明非常相似，但需要在class关键字之前加上annotation修饰符。但Kotlin编译器禁止为注解类指定类主体，因为注解类只是用来定义关联到 声明 和 表达式 的元数据的结构。

#daqiKotlin.kt
annotation class daqiAnnotation

Java注解声明：

#daqiJava.java
public @interface daqiAnnotation {
}

注解的构造函数

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

其中注解的构造函数允许的参数类型有：

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

注解作为注解构造函数的参数

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

annotation class daqiAnnotation(val str: String)

annotation class daqiAnnotation2(
    val message: String,
    val annotation: daqiAnnotation = daqiAnnotation(""))

类作为注解构造函数的参数

当需要将一个类指定为注解的参数，请使用 Kotlin 类 （KClass）。Kotlin 编译器会自动将其转换为 Java 类，以便 Java 代码能够正常看到该注解及参数 。

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

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

将其反编译后，可以看到转换为相应的Java类：

@daqiAnnotation(
   arg1 = String.class,
   arg2 = int.class
)
public final class MyClass {
}

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

Kotlin的元注解

      和Java一样，Kotlin的注解类也使用元注解进行注解。用于其他注解的注解称为元注解，可以理解为最基本的标注。

image

      Kotlin标准库中定义了4个元注解，分别是:MustBeDocumented、Repeatable、Retention、Target。

@Target

@Target用于指定可以应用该注解的元素类型(类、函数、属性、表达式等)。

查看Target的源码：

#Annotation.kt
@Target(AnnotationTarget.ANNOTATION_CLASS)
@MustBeDocumented
public annotation class Target(vararg val allowedTargets: AnnotationTarget)

@Target注解中可以同时接收一个或多个AnnotationTarget枚举值：

public enum class AnnotationTarget {
    //作用于类(包括枚举类)、接口、object对象和注解类
    CLASS,
    //仅作用于注解类
    ANNOTATION_CLASS,
    //作用于泛型类型参数（暂时不支持）（JDK8）
    TYPE_PARAMETER,
    //作用于属性
    PROPERTY,
    //作用于字段（包括枚举常量和支持字段）。
    FIELD,
    //作用于局部变量
    LOCAL_VARIABLE,
    //作用于函数或构造函数的参数
    VALUE_PARAMETER,
    //作用于构造函数(包括主构造函数和次构造函数)
    CONSTRUCTOR,
    //作用于方法（不包括构造函数）
    FUNCTION,
    //仅作用于属性的getter函数
    PROPERTY_GETTER,
    //仅作用于属性的setter函数
    PROPERTY_SETTER,
    //作用于类型(如方法内参数的类型)
    TYPE,
    //作用于表达式
    EXPRESSION,
    //作用于文件,可配合 file点目标 使用: (例如： @file:JvmName("daqiKotlin"))
    FILE,
    //作用于类型别名
    @SinceKotlin("1.1")
    TYPEALIAS
}

       注意：Java代码中无法使用Target为AnnotationTarget.PROPERTY的注解。如果想让这样的注解在Java中使用，可以添加多一条AnnotationTarget.FIELD的注解。

@Retention

@Retention 声明注解的保留策略。

查看Retention的源码：

@Target(AnnotationTarget.ANNOTATION_CLASS)
public annotation class Retention(val value: AnnotationRetention = AnnotationRetention.RUNTIME)

@Retention注解中可以接收一个AnnotationRetention枚举值：

public enum class AnnotationRetention {
    //表示注解仅保留在源代码中，编译器将丢弃该注解。
    SOURCE,
    //注解将由编译器记录在class文件中 但在运行时不需要由JVM保留。
    BINARY,
    //注解将由编译器记录在class文件中，并在运行时由JVM保留，因此可以反射性地读取它们。(默认行为)
    RUNTIME
}

       注意：Java的元注解默认会在.class文件中保留注解，但不会让它们在运行时被访问到。大多数注解需要在运行时存在，以至于Kotlin将RUNTIME作为@Retention注解的默认值。

@Repeatable

允许在单个元素上多次使用相同的该注解；

查看Repeatable的源码：

@Target(AnnotationTarget.ANNOTATION_CLASS)
public annotation class Repeatable

       注意：在"尝试使用"@Repeatable时发现，该注解必须要在Retention元注解指定为AnnotationRetention.SOURCE时才能重复使用，但Java的@Repeatable元注解并没有该限制。（具体的Java @Repeatable元注解的使用示例可以看这篇文章）。因为@Repeatable是Java 8引入的新的元注解，而兼容Java 6的Kotlin对此有点不兼容？

@MustBeDocumented

指定该注解是公有 API 的一部分，并且应该包含在生成的 API 文档中显示的类或方法的签名中。

查看MustBeDocumented的源码：

@Target(AnnotationTarget.ANNOTATION_CLASS)
public annotation class MustBeDocumented

消失的@Inherited元注解

      相对Java的5个元注解，Kotlin只提供了与其对应的4个元注解，Kotlin暂时不需要支持@Inherited元注解。

      @Inherited注解表明注解类型可以从超类继承。具体意思是：存在一个带@Inherited元注解的注解类型，当用户在某个类中查询该注解类型并且没有此类型的注解时，将尝试从该类的超类以获取注解类型。重复此过程，直到找到此类型的注解，或者到达类层次结构（对象）的顶部为止。如果没有超类具有此类型的注解，则查询将指示相关类没有此类注解。此注解仅适用于类声明。

Kotlin预定义的注解

      Kotlin为了与Java具有良好的互通性，定义了一系列注解用于携带一些额外信息，以便编译器做兼容转换。

image

@JvmDefault

将Kotlin接口的默认方法生成Java 8的默认方法的字节码

查看源码：

@SinceKotlin("1.2")
@RequireKotlin("1.2.40", versionKind = RequireKotlinVersionKind.COMPILER_VERSION)
@Target(AnnotationTarget.FUNCTION, AnnotationTarget.PROPERTY)
annotation class JvmDefault

      前面接口和类中提到，当在Kotlin中声明一个带默认方法的接口时，往往会将这些“默认方法”声明为抽象方法，同时也会在该接口中生成一个DefaultImpls静态内部类，并在其中定义同名的静态方法来提供默认实现。

      但这样会存在一个问题，当对旧的Kotlin接口添加新的默认方法时,实现该接口的Java类需要重新实现新添的接口方法，否则会编译不通过。同是默认方法，但与Java 8引入默认方法的初衷相违背。为此，Kotlin提供了@JvmDefault注解。对标有@JvmDefault注解的默认方法，编译器会将其编译为Java 8的默认接口。

#daqiKotlin.kt
public interface daqiInterface{
    @JvmDefault//刚添加会报错
    fun daqiFunc() = println("带@JvmDefault的默认方法")

    fun daqiFunc2() = println("默认方法")
}

#java文件
public interface daqiInterface {
   @JvmDefault
   default void daqiFunc() {
      String var1 = "带@JvmDefault的默认方法";
      System.out.println(var1);
   }

   void daqiFunc2();

   public static final class DefaultImpls {
      public static void daqiFunc2(daqiInterface $this) {
         String var1 = "默认方法";
         System.out.println(var1);
      }
   }
}

      当你直接添加 @JvmDefault时，编译器会报错。这时你需要在Gradle中配置以下参数：(具体Kotlin使用Gradle看官网)

tasks.withType<KotlinCompile> {
    kotlinOptions {
        freeCompilerArgs = ['-Xjvm-default = compatibility']
        //freeCompilerArgs = ['-Xjvm-default = enable']
    }
}

      通过@JvmDefault的注解得知，配置时可以选择-Xjvm-default = enable或-Xjvm-default = compatibility。这两个的区别是：

  • -Xjvm-default = enable会从DefaultImpls静态内部类中删除对应的方法。
  • -Xjvm-default = compatibility仍会在DefaultImpls静态内部类中保留对应的方法，提高兼容性。

注意：只有JVM目标字节码版本1.8（-jvm-target 1.8）或更高版本才能生成默认方法。

@JvmField

指示Kotlin编译器不为此属性生成getter / setter并将其修饰为public。

查看源码：

@Target(AnnotationTarget.FIELD)
@Retention(AnnotationRetention.BINARY)
@MustBeDocumented
public actual annotation class JvmField

      Kotlin声明的属性都默认使用private修饰，并提供setter / getter访问器对其进行访问。而@JvmField就是告诉编译器不要为该属性自动创建setter / getter访问器,并将对其使用public修饰。（用在伴生对象的属性上，可生成public修饰的static属性）

#daqiKotlin.kt
class Person{
    @JvmField
    val name:String = ""
}

反编译后查看源码中只声明了一个public对象：

#java文件
public final class Person {
   @JvmField
   @NotNull
   public final String name = "";
}

       注意该注解只能用在有幕后字段的属性上，对于没有幕后字段的属性（例如：扩展属性、委托属性等）不能使用。因为只有拥有幕后字段的属性转换成Java代码时，才有对应的Java变量。

Kotlin属性拥有幕后字段需要满足以下条件之一：

  • 使用默认 getter / setter 的属性，一定有幕后字段。对于 var 属性来说，只要 getter / setter 中有一个使用默认实现，就会生成幕后字段。
  • 在自定义 getter / setter 中使用了 field 的属性。

@JvmName

指定生成Java类的类名或方法名。

查看源码：

@Target(AnnotationTarget.FUNCTION, AnnotationTarget.PROPERTY_GETTER, AnnotationTarget.PROPERTY_SETTER, AnnotationTarget.FILE)
@Retention(AnnotationRetention.BINARY)
@MustBeDocumented
public actual annotation class JvmName(actual val name: String)

      根据注解的声明，属性的访问器getter / setter也可以使用该注解，但属性不能使用~。

      在daqiKotlin.kt文件中声明的所有函数和属性（包括扩展函数）都被编译为名为在DaqiKotlinKt的Java类的静态方法。其中文件名首字母会被改为大写，后置Kt。当需要修改该Kotlin文件生成的Java类名称时，可以使用@JvmName名指定生成特定的文件名：

@file:JvmName("daqiKotlin")

package com.daqi.test

@JvmName("daqiStateFunc")
public fun daqiFunc(){

}

      反编译可以看到生成的Java类名称已经修改为daqiKotlin，而非DaqiKotlinKt，同时顶层函数daqiFunc的方法名被修改为daqiStateFunc：

public final class DaqiKotlinKt {
   @JvmName(name = "daqiStateFunc")
   public static final void daqiStateFunc() {
   }
}

@JvmMultifileClass

指示Kotlin编译器生成一个多文件的类。该文件具有在此文件中声明的顶级函数和属性。

查看源码：

@Target(AnnotationTarget.FILE)
@Retention(AnnotationRetention.SOURCE)
@MustBeDocumented
public actual annotation class JvmMultifileClass

      当需要将多个Kotlin文件中的方法和属性归到一个Java类时，可以在多个文件中声明一样的@JvmName,并在其下面添加@JvmMultifileClass注解。(多个文件中声明一样的@JvmName,但不添加@JvmMultifileClass注解会编译不通过)

#daqiKotlin.kt
@file:JvmName("daqiKotlin")
@file:JvmMultifileClass

package com.daqi.test

fun daqi(){

}

#daqiKotlin2.kt
@file:JvmName("daqiKotlin")
@file:JvmMultifileClass

package com.daqi.test

fun daqi2(){

}

      Kotlin编译器会将该两个文件中的方法和属性合并到@JvmName注解生成的指定名称的Java类中：

image

@JvmOverloads

指示Kotlin编译器为此函数生成替换默认参数值的重载函数（从最后一个开始省略每个参数）。

查看源码：

@Target(AnnotationTarget.FUNCTION, AnnotationTarget.CONSTRUCTOR)
@Retention(AnnotationRetention.BINARY)
@MustBeDocumented
public actual annotation class JvmOverloads

      Java并没有参数默认值的概念，当你从Java中调用Kotlin的默认参数函数时，必须显示地指定所有参数值。使用@JvmOverloads注解该方法，Kotlin编译器会生成相应的Java重载函数，从最后一个参数开始省略每个函数。

#daqiKotlin.kt
@JvmOverloads
fun daqi(name :String = "daqi",age :Int = 2019){
    println("name = $name,age = $age ")
}
image

@JvmStatic

将对象声明或伴生对象的方法或属性的访问器暴露成一个同名的Java静态方法。

查看源码：

@Target(AnnotationTarget.FUNCTION, AnnotationTarget.PROPERTY, AnnotationTarget.PROPERTY_GETTER, AnnotationTarget.PROPERTY_SETTER)
@Retention(AnnotationRetention.RUNTIME)
@MustBeDocumented
public actual annotation class JvmStatic

      对于Kotlin的对象声明和伴生对象，在Kotlin中可以像静态函数那样调用类名.方法名进行调用。但在Java中，需要在这其中添加多一个Companion或INSTANCE,使调用很不自然。使用@JvmStatic注解标记伴生对象或对象声明中的方法和属性，使其在Java中可以像Kotlin一样调用这些方法和属性。

在Kotlin中定义一个伴生对象，并用标记@JvmStatic注解：

class daqi{
    companion object {
        @JvmStatic
        val name:String = ""

        @JvmStatic
        fun daqiFunc(){

        }
    }
}

      反编译可以观察到 伴生对象类 或 对象声明类 中声明了属于它们自己的方法和属性，但同时在对象声明类本身或伴生对象类的外部类中也声明了一样的静态的方法和属性访问器供外部直接访问。

public final class daqi {
   @NotNull
   private static final String name = "";
   public static final daqi.Companion Companion = new daqi.Companion((DefaultConstructorMarker)null);

   @NotNull
   public static final String getName() {
      daqi.Companion var10000 = Companion;
      return name;
   }

   @JvmStatic
   public static final void daqiFunc() {
      Companion.daqiFunc();
   }

   public static final class Companion {
      @JvmStatic
      public static void name$annotations() {
      }

      @NotNull
      public final String getName() {
         return daqi.name;
      }

      @JvmStatic
      public final void daqiFunc() {
      }
   }
}

      所以，如果对象声明和伴生对象需要和Java层进行比较频繁的交互时，建议还是加上@JvmStatic

@JvmSuppressWildcards 和 @JvmWildcard

@JvmSuppressWildcards指示编译器为泛型参数生成或省略通配符。(默认是省略)
@JvmWildcard指示编译器为为泛型参数生成通配符。

查看源码：

@Target(AnnotationTarget.CLASS, AnnotationTarget.FUNCTION, AnnotationTarget.PROPERTY, AnnotationTarget.TYPE)
@Retention(AnnotationRetention.BINARY)
@MustBeDocumented
public actual annotation class JvmSuppressWildcards(actual val suppress: Boolean = true)

--------------------------------------------------------------------------

@Target(AnnotationTarget.TYPE)
@Retention(AnnotationRetention.BINARY)
@MustBeDocumented
public actual annotation class JvmWildcard

@PurelyImplements

指示Kotlin编译器将带该注释的Java类视为给定Kotlin接口的纯实现。“Pure”在这里表示类的每个类型参数都成为该接口的非平台类型参数。

查看源码：

@Target(AnnotationTarget.CLASS)
@Retention(AnnotationRetention.RUNTIME)
@MustBeDocumented
public annotation class PurelyImplements(val value: String)

      Kotlin对来自Java的变量会当作平台类型来处理，由开发者觉得其是可空还是非空。但即便将其声明为非空，但其实他还是能接收空值或者返回空值。

#java文件
class MyList<T> extends AbstractList<T> { ... }

#kotlin文件
MyList<Int>().add(null) // 编译通过

      但可以借助@PurelyImplements注解，并携带对应的Kotlin接口。使其与Kotlin接口对应的类型参数不被当作平台类型来处理。

#java文件
@PurelyImplements("kotlin.collections.MutableList")
class MyPureList<T> extends AbstractList<T> { ... }

MyPureList<Int>().add(null) // 编译不通过
MyPureList<Int?>().add(null) // 编译通过

@Throws

等价于Java的throws关键字

查看源码：

@Target(AnnotationTarget.FUNCTION, AnnotationTarget.PROPERTY_GETTER, AnnotationTarget.PROPERTY_SETTER, AnnotationTarget.CONSTRUCTOR)
@Retention(AnnotationRetention.SOURCE)
public annotation class Throws(vararg val exceptionClasses: KClass<out Throwable>)

例子

@Throws(IOException::class)
fun daqi() {
    
}

@Strictfp

等价于Java的strictfp关键字

查看源码：

@Target(FUNCTION, CONSTRUCTOR, PROPERTY_GETTER, PROPERTY_SETTER, CLASS)
@Retention(AnnotationRetention.SOURCE)
@MustBeDocumented
public actual annotation class Strictfp

@Transient

等价于Java的transient关键字

查看源码：

@Target(FIELD)
@Retention(AnnotationRetention.SOURCE)
@MustBeDocumented
public actual annotation class Transient

@Synchronized

等价于Java的synchronized关键字

查看源码：

@Target(FUNCTION, PROPERTY_GETTER, PROPERTY_SETTER)
@Retention(AnnotationRetention.SOURCE)
@MustBeDocumented
public actual annotation class Synchronized

@Volatile

等价于Java的volatile关键字

查看源码：

@Target(FIELD)
@Retention(AnnotationRetention.SOURCE)
@MustBeDocumented
public actual annotation class Volatile

点目标声明

      许多情况下， Kotlin代码中的单个声明会对应成多个 Java 声明 ，而且它们每
个都能携带注解。例如， Kotlin 属性就对应了 Java 宇段、 getter ，以
及一个潜在的 setter。这时需要使用点目标指定说明注解用在什么地方。

点目标声明被用来说明要注解的元素。使用点目标被放在＠符号和注解名
称之间，并用冒号和注解名称隔开。

点目标的完整列表如下：

  • property————Java 的注解不能应用这种使用点目标
  • field————为属性生成的字段
  • get ————属性的 getter
  • set ————属性的 setter
  • receiver ————扩展函数或者扩展属性的接收者参数。
  • param————构造方法的参数。
  • setparam————属性 setter 的参数
  • delegate ————为委托属性存储委托实例的字段
  • file ———— 包含在文件中声明的顶层函数和属性的类。
//注解的是get方法，而不是属性
@get:daqiAnnotation
val daqi:String = ""

@Target(AnnotationTarget.PROPERTY_GETTER)
annotation class daqiAnnotation()

参考资料：

android Kotlin系列：

Kotlin知识归纳（一） —— 基础语法

Kotlin知识归纳（二） —— 让函数更好调用

Kotlin知识归纳（三） —— 顶层成员与扩展

Kotlin知识归纳（四） —— 接口和类

Kotlin知识归纳（五） —— Lambda

Kotlin知识归纳（六） —— 类型系统

Kotlin知识归纳（七） —— 集合

Kotlin知识归纳（八） —— 序列

Kotlin知识归纳（九） —— 约定

Kotlin知识归纳（十） —— 委托

Kotlin知识归纳（十一） —— 高阶函数

Kotlin知识归纳（十二） —— 泛型

Kotlin知识归纳（十三） —— 注解

Kotlin知识归纳（十四） —— 反射

image
最后编辑于 ：
©著作权归作者所有,转载或内容合作请联系作者
  • 人面猴
    序言：七十年代末，一起剥皮案震惊了整个滨河市，随后出现的几起案子，更是在滨河造成了极大的恐慌，老刑警刘岩，带你破解...
    沈念sama阅读 206,839评论 6赞 482
  • 死咒
    序言：滨河连续发生了三起死亡事件，死亡现场离奇诡异，居然都是意外死亡，警方通过查阅死者的电脑和手机，发现死者居然都...
    沈念sama阅读 88,543评论 2赞 382
  • 救了他两次的神仙让他今天三更去死
    文/潘晓璐 我一进店门，熙熙楼的掌柜王于贵愁眉苦脸地迎上来，“玉大人，你说我怎么就摊上这事。” “怎么了？”我有些...
    开封第一讲书人阅读 153,116评论 0赞 344
  • 道士缉凶录：失踪的卖姜人
    文/不坏的土叔 我叫张陵，是天一观的道长。 经常有香客问我，道长，这世上最难降的妖魔是什么？ 我笑而不...
    开封第一讲书人阅读 55,371评论 1赞 279
  • 港岛之恋（遗憾婚礼）
    正文 为了忘掉前任，我火速办了婚礼，结果婚礼上，老公的妹妹穿的比我还像新娘。我一直安慰自己，他们只是感情好，可当我...
    茶点故事阅读 64,384评论 5赞 374
  • 恶毒庶女顶嫁案：这布局不是一般人想出来的
    文/花漫 我一把揭开白布。 她就那样静静地躺着，像睡着了一般。 火红的嫁衣衬着肌肤如雪。 梳的纹丝不乱的头发上，一...
    开封第一讲书人阅读 49,111评论 1赞 285
  • 城市分裂传说
    那天，我揣着相机与录音，去河边找鬼。 笑死，一个胖子当着我的面吹牛，可吹牛的内容都是我干的。 我是一名探鬼主播，决...
    沈念sama阅读 38,416评论 3赞 400
  • 双鸳鸯连环套：你想象不到人心有多黑
    文/苍兰香墨 我猛地睁开眼，长吁一口气：“原来是场噩梦啊……” “哼！你这毒妇竟也来了？” 一声冷哼从身侧响起，我...
    开封第一讲书人阅读 37,053评论 0赞 259
  • 万荣杀人案实录
    序言：老挝万荣一对情侣失踪，失踪者是张志新（化名）和其女友刘颖，没想到半个月后，有当地人在树林里发现了一具尸体，经...
    沈念sama阅读 43,558评论 1赞 300
  • 护林员之死
    正文 独居荒郊野岭守林人离奇死亡，尸身上长有42处带血的脓包…… 初始之章·张勋 以下内容为张勋视角 年9月15日...
    茶点故事阅读 36,007评论 2赞 325
  • 白月光启示录
    正文 我和宋清朗相恋三年，在试婚纱的时候发现自己被绿了。 大学时的朋友给我发了我未婚夫和他白月光在一起吃饭的照片。...
    茶点故事阅读 38,117评论 1赞 334
  • 活死人
    序言：一个原本活蹦乱跳的男人离奇死亡，死状恐怖，灵堂内的尸体忽然破棺而出，到底是诈尸还是另有隐情，我是刑警宁泽，带...
    沈念sama阅读 33,756评论 4赞 324
  • 日本核电站爆炸内幕
    正文 年R本政府宣布，位于F岛的核电站，受9级特大地震影响，放射性物质发生泄漏。R本人自食恶果不足惜，却给世界环境...
    茶点故事阅读 39,324评论 3赞 307
  • 男人毒药：我在死后第九天来索命
    文/蒙蒙 一、第九天 我趴在偏房一处隐蔽的房顶上张望。 院中可真热闹，春花似锦、人声如沸。这庄子的主人今日做“春日...
    开封第一讲书人阅读 30,315评论 0赞 19
  • 一桩弑父案，背后竟有这般阴谋
    文/苍兰香墨 我抬头看了看天上的太阳。三九已至，却和暖如春，着一层夹袄步出监牢的瞬间，已是汗流浃背。 一阵脚步声响...
    开封第一讲书人阅读 31,539评论 1赞 262
  • 情欲美人皮
    我被黑心中介骗来泰国打工， 没想到刚下飞机就差点儿被人妖公主榨干…… 1. 我叫王不留，地道东北人。 一个月前我还...
    沈念sama阅读 45,578评论 2赞 355
  • 代替公主和亲
    正文 我出身青楼，却偏偏与公主长得像，于是被迫代替她去往敌国和亲。 传闻我的和亲对象是个残疾皇子，可洞房花烛夜当晚...
    茶点故事阅读 42,877评论 2赞 345