《Kotlin实战》-第10章：注解与反射

第十章注解与反射

注解与反射可以让我们编写出事先未知的任意类的代码，可以使用注解赋予这些类库特定的语义，而反射允许你在运行时分析这些类的结构。

10.1 声明并应用注解

10.1.1 应用注解

Kotlin中使用注解的方法和Java一样：以@字符作为注解名字的前缀，并放在要注解的声明的最前面。
可以注解不同的代码元素，例如函数和类。
示例：

import org.junit.*
class MyTest{@Test fun testTrue(){....}
}

可以给注解提供实参，示例：

//如果有人使用remove函数，IDEA不仅会提示过期，还会提供一个快速修正
//RepalceWith是一个注解，在这里为Deprecated的实参
@Deprecated("Use removeAt(index) instead",ReplaceWith("removeAt(index)"))
fun remove(index:Int){ ... }

注解可以拥有的类型参数：

基本数据类型
字符串
枚举
类引用
其他的注解类
上述类型的数组

相比Java来说，Kotlin指定注解实参的语法的特点：

要把一个类指定为注解实参,在类名后加上::class,例如
- @MyAnnotation(MyClass::class)
要把另一个注解指定为一个实参，去掉@，例如上面示例中的ReplaceWith
要把一个数组指定为一个实参，使用arrayOf函数。
- @RequestMapping(path = arrayOf("/foo","/bar"))
注解实参不能引用任意的属性作为实参，除非用const来标记。这是因为注解实参需要在编译期是已知的，这样就是编译期常量。

10.1.2 注解目标

许多情况下，Kotlin源代码中的单个声明会对应成多个Java声明，而且其中每个元素都可能携带注解。
例如，一个Kotlin属性就对应了一个Java字段、一个getter，以及一个潜在的setter和它的参数。
因此，说明哪些元素需要注解十分必要。
Kotlin的解决方式就是使用点目标声明被用来说明要注解的元素：@ + 使用目标 + : + 注解名称。
示例：

//注解的是getter而不是属性
@get:Rule
val folder = Temporary()

Kotlin支持的使用点目标的完整列表：

propertay：Java的注解不能应用这种。
field：为属性生成的字段。
get：属性的getter。
set：属性的setter。
receiver：扩展函数或者扩展属性的接受者参数。
param：构造方法的参数。
setparam：属性setter的参数。
delegate：为委托属性存储委托实例的字段。
file：包含在文件中声明的顶层函数和属性的类。任何应用到file目标的注解都必须放在文件的顶层，放在package指令之前。

注意，和Java不一样的是：Kotlin允许对任意的表达式应用注解，而不仅仅是类和函数的声明及类型。
常见的例子是Suppress注解，可以用它抑制被注解的表达式的上下文中的特定的编译器的警告。

fun test(list:List<*>){@Suppress("UNCHECKED_CAST")val strings = list as LIst<String>....
}

这里提一个注解应用的方向：用注解控制Java API，用来控制Kotlin代码如何编译成字节码并暴露给Java调用者。
有以下注解：

@Volatile：充当Java中关键字volatile。
@Strictfp：充当Java关键字strictfp。
@JvmName：改变由Kotlin生成的Java方法或字段的名称。
@JvmStatic：能被用在对象声明或者伴生对象的方法上，把它们暴露成Java的静态方法。
@JvmOverloads：让Kotlin编译器为带默认参数值的函数生成多个重载。
@JvmField：可以应用于一个属性，把这个属性暴露成一个没有访问器的共有Java字段。

10.1.3 使用注解定制JSON序列化

注解的经典用法之一就是定制化对象的序列化。

序列化：把对象转换成可以存储或者在网路上传输的二进制或者文本的表示法。
反序列化：把这种表示法转换回一个对象。

从本小节开始，就是以本书提供的一个练习库JKid(http://github.com/yole/jkid)为例，讲解注解和反射的一些用法。
JKid库是以序列化相关为功能目的，以纯Kotlin代码编写的。这个项目有一系列练习，可以在读完本章内容后把练习做一遍来巩固对本章知识的理解。

现在先来介绍下JKid主要的两个方法：

serialize：序列化函数，返回一个包含参数实例JSON表示法的字符串。
deserialize：反序列化函数，从JSON表示法字符串中返回一个对象。当然肯定要知道对应类。

JKid的两个注解：

@JsonExclude：标记属性，这个属性应该排除在序列化和反序列化之外。
@JsonName：标记属性，让这个属性在序列化时位于JSON键值对中的键是一个给定字符串。

使用示例：

data class Person(@JsonName("alias") val firstName:String,@JsonExclude val age:Int? = null
)

具体实现会在本章后面逐步讲解。

10.1.4 声明注解

1.声明一个没有参数的注解：

在class关键字前加上annotation即可。
注解类不能包含任何代码，因为它只是用来定义关联到声明和表达式的元数据的结构。

annotation class JsonExclude

2.声明带参数的注解，在类的主构造方法中声明参数。

//声明
annotation class JsonName(val name:String)
//使用，两种方式一样
@JsonName(name="hehe")
@JsonName("hehe")

3.Java中声明同样的注解：

public @interface JsonName{String value();
}

特别的，Java注解有一个叫做value的方法。

Java注解里，需要提供value以外所有指定特性显式名称。
如果需要把Java中声明的注解应用到Kotlin元素上，必须对除了value以外的所有实参使用命名实参方法，而value也会被Kotlin特殊对待。

10.1.5 元注解：控制如何处理一个注解

1.元注解概念
可以应用到注解类上的注解就是元注解。
标准库中定义了一些元注解，它们会控制编译器如何处理注解。
最常见的元注解是Target,这个元注解说明了注解可以被应用的元素类型。也可以指定多个目标类型。
示例：

//这个PROPERTY前面提到过，只能在Kotlin中用，要想在Java中用的话需要添加FIELD
@Target(AnnotationTarget.PROPERTY)
annotation class JsonExcluede

2.声明元注解
使用@Target(AnnotationTarget.ANNOTATION_CLASS)即可。

@Target(AnnotationTarget.ANNOTATION_CLASS)
annotation class BindingAnnotation

这里特别贴下Target的声明，免得陷入到蛋和鸡哪个先有的问题：

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

10.1.6 使用类做注解参数

KClass类是Java的java.lang.Class类型在Kotlin的对应类型，用来保存Kotlin类的引用。
使用类做注解参数的示例：

//声明
annotation class DeserializeInterface(val targetClass:KClass<out Any>)
//使用
inteface Company{ val name:String
}
data class CompanyImpl(override val name:String):Company
data class Person(val name:String,//这里由于有了out才能用CompanyImpl，否则只能用Any::class@DeserializeInterface(CompanyImpl::class) val company:Company
)

10.1.7 使用泛型类做注解参数

以JKid的CustomSerializer为例来展示泛型类做注解参数。
默认情况下，JKid把非基本数据类型的属性当成嵌套的对象序列化，但可以用CustomSerializer改变。
示例：

//这是个通用序列化接口
interface ValueSerializer<T>{fun toJsonValue(value:T):Any?fun fromJsonValue(jsonValue:Any?):T
}
//声明注解类，这里的参数是一个必须实现了ValueSerializer的泛型类
annotation class CustomSerializer(val serializerClass:KClass<out ValueSerializer<*>>)//使用
class DateSerializer : ValueSerializer<Date> {private val dateFormat = SimpleDateFormat("dd-mm-yyyy")override fun toJsonValue(value: Date): Any? =dateFormat.format(value)override fun fromJsonValue(jsonValue: Any?): Date =dateFormat.parse(jsonValue as String)
}data class Person(val name:String@CustomSerializer(DateSerializer::class) val birthDate:Date)

10.2 反射：在运行时对Kotlin对象进行自省

当在Kotlin中使用反射时，有两种不同的反射API：

标准的Java反射，定义在java.lang.reflect中。
- Kotlin类会被编译成普通的Java字节码，Java反射API可以完美的支持它们。
Kotlin反射API，定义在包kotlin.reflect中。可以允许访问在Java世界里不存在的概念，如属性和可空类型。
- 它没有为Java反射API提供完全对应的替身，有些情况下仍然需要使用Java反射。
- Kotlin反射API不仅限于Kotlin类，而是可以访问任何用JVM语言写成的类。

Kotlin反射API在有些平台上被打成了单独的jar包，库的地址是org.jetbrains.kotlin:kotlin-reflect。

10.2.1 Kotlin反射API：KClass、KCallable、KFunction和KProperty

1.KClass
Kotlin反射API的主要入口，代表了一个类。

KClass对应的是java.lang.class。
MyClass::class表示一个KClass实例。
要在运行时获取一个对象的类的方式:先用javaClass获取java类，然后用.kotlin切换。

//声明类
class Person(val name:String,val age:Int)
//调用
val person = Person("Alice",29)
val kClass = person.javaClass.kotlin
println(kClass.simpleName)
kClass.memberProperties.forEach{println(it.name)
}
>>>>>
Person
age
name

KClass声明中有大量方便的方法用于访问类内容，如simpleName,qualifiedName,members,constructors等。

2.KCallable
函数(KFunction)和属性(KProperty)的超接口，声明了call方法，可以调用对应的函数或者属性的getter。
声明示例：

interface KCallable<out R>{fun call(vararg args:Any?):R...
}

通过反射call来调用一个函数：

fun foo(x:Int) = println(x)
val kCallable = ::foo
kCallable.call(42)

3.KFunction
反射中的代表函数的类。
上面示例中foo的kCallable.call的参数类型不对的话会引发异常，为避免，可以用更具体的方法来调用这个函数：KFuction1<Int,Unit>，这里包含了形参类型和返回类型。
一个更复杂的KFunction使用示例：

import kotlin.reflect.KFunction2fun sum(x:Int,y:Int) = x + y
val kFunction:KFunction2<Int,Int,Int> = ::sum
//11.3章节会介绍为什么可不用invoke也可调用
println(kFunction.invoke(1,2) + kFunction(3,4))
//kFunction(1)编译无法通过
>>>>>
10

这里关于KFunctionN接口特别解释下：

这些类型称为合成的编译器生成类型，在包中是找不到声明的。也就意味着可以使用任意数量参数的函数接口。
合成类型的方式减小了kotlin-reflect.jar的尺寸，避免了对函数类型参数数量的认为限制。
对函数反射来说，应优先使用有具体类型的KFunctionN的invoke方法，而不是提供不了类型安全性的KCallable的call方法。

4.KProperty
反射中代表属性的接口。主要有两个实现类：

KProperty0：get方法无参数，适用于顶层属性。
KProperty1：get方法有参数，适用于成员属性。

使用示例：

//顶层属性
var counter = 0;
val kProperty = ::counter
kProperty.setter.call(21)
println(kProperty.get())
//成员属性
class Person(val name:String,val age:Int)
val person = Person("Alice",29)
val memberProperty = Person::age
println(memberProperty.get(person))

要注意的几点：

KProperty1是一个泛型类，上面示例中是KProperty<Person,Int>,参数一个是接受者的类型，一个是属性的类型。
只能使用反射访问定义在最外层或者类中的属性，不能访问函数的局部变量。

5.Kotlin反射API的接口层级结构

几个要点：

所有的声明都能被注解，所以顶层接口是KAnnotatedElement。
KClass既可以表示类，也可以表示对象。
KProperty可以表示任何属性，它的子类KMutableProperty表示一个用var声明的可变属性。
可以使用声明在KProperty中的特殊接口Getter和Setter把属性的访问器当成函数使用。两个访问器接口都继承了KFuction。

10.2.2 用反射实现对象序列化

本小节到后面都是JKid库如何实现的具体解释，最好自己看下源码实现。
这里考虑到代码解释的复杂性和知识点的简要性，就不按照原书内容一一进行解释，只是摘要关键点和需要注意的地方。

首先是序列化函数，还是比较简单的：

//序列化函数入口
fun serialize(obj: Any): String = buildString { serializeObject(obj) }
//serializeObject的简单实现,扩展函数
private fun StringBuilder.serializeObject(obj: Any) {val kClass = obj.javaClass.kotlinval properties = kClass.memberProperties//这里的prop的类型是KProperty1<Any,*>properties.joinToStringBuilder(this, prefix = "{", postfix = "}") {serializeProperty(it, obj)}
}

10.2.3 用注解定制序列化

1.KAnnotatedElement
此接口定义了属性annotations,是一个由应用到源码中元素上的所有注解的实例组成的集合。
KProperty继承了KAnnotatedElement，也就可以用property.annotations访问一个属性的所有注解。
辅助函数findAnnotation可以帮助找到特定注解：

inline fun <reified T> KAnnotatedElement.findAnnotation(): T?= annotations.filterIsInstance<T>().firstOrNull()

在JKid中应用：

private fun StringBuilder.serializeObject(obj: Any) {obj.javaClass.kotlin.memberProperties//筛选JsonExclude注解.filter { it.findAnnotation<JsonExclude>() == null }.joinToStringBuilder(this, prefix = "{", postfix = "}") {serializeProperty(it, obj)}
}private fun StringBuilder.serializeProperty(prop: KProperty1<Any, *>, obj: Any
) {//寻找JsonName注解val jsonNameAnn = prop.findAnnotation<JsonName>()val propName = jsonNameAnn?.name ?: prop.nameserializeString(propName)append(": ")serializePropertyValue(prop.get(obj))
}

2.KClass
KClass可以表示类和对象，区别在于，对象拥有非空值的objectInstance属性，可用来访问为object创建的单例实例。
当表示一个类时，则可以调用createInstance来创建一个新的实例。

在JKid中应用示例：

fun KProperty<*>.getSerializer(): ValueSerializer<Any?>? {//寻找CustomSerializer注解val customSerializerAnn = findAnnotation<CustomSerializer>() ?: return nullval serializerClass = customSerializerAnn.serializerClass//是对象就直接用，否则就创建val valueSerializer = serializerClass.objectInstance?: serializerClass.createInstance()@Suppress("UNCHECKED_CAST")return valueSerializer as ValueSerializer<Any?>
}

10.2.4 JSON解析和对象反序列化

反序列化一般包含三阶段：

词法分析器
语法分析器
反序列化组件本身

10.2.5 反序列化的最后一步：callBy()和使用反射创建对象

前面提到过KCallable的call方法可以调用函数或者构造方法，并接受一个实参组成的列表。
这个方法很好用，但有个限制是不支持默认参数值。
这里可以使用callBy方法,参数是包含形参和对应值的map:

public actual interface KCallable<out R> : KAnnotatedElement {public fun callBy(args: Map<KParameter, Any?>): R...
}

JKid中应用示例：

class ClassInfo<T : Any>(cls: KClass<T>) {private val className = cls.qualifiedName//主构造函数private val constructor = cls.primaryConstructor?: throw JKidException("Class ${cls.qualifiedName} doesn't have a primary constructor")fun createInstance(arguments: Map<KParameter, Any?>): T {ensureAllParametersPresent(arguments)//创建对象return constructor.callBy(arguments)}private fun ensureAllParametersPresent(arguments: Map<KParameter, Any?>) {for (param in constructor.parameters) {if (arguments[param] == null && !param.isOptional && !param.type.isMarkedNullable) {throw JKidException("Missing value for parameter ${param.name}")}}}......
}