接下来学习Kotlin中的注解(Annotations)和类型别名(Type aliases)。
类型别名(Type aliases) 1.1版本
类型别名为现有类型提供替代名称。如果类型名称太长,您可以引入不同的较短的名称,并使用新的名称。
缩短长泛型类型:
typealias NodeSet = Set
typealias FileTable = MutableMap>
可以为功能类型提供不同的别名:
typealias MyHandler = (Int, String, Any) -> Unit
typealias Predicate = (T) -> Boolean
可以为内部和嵌套类创建新名称:
class A {
inner class Inner
}
class B {
inner class Inner
}
typealias AInner = A.Inner
typealias BInner = B.Inner
Kotlin中定义的类型别名
类型别名不会引入新类型,它们相当于相应的底层类型,在代码中添加了typealias Predicate
并使用Predicate
时,Kotlin编译器始终将其扩展为(Int) -> Boolean
。
因此,只要需要一般功能类型,就可以传递类型的变量,反之亦然:
typealias Predicate = (T) -> Boolean // 这里可以看出变量的类型是函数类型,参数是`T`,返回值是`Boolean`
/*
foo方法的返回值是Boolean,因为p的类型为Predicate,而Predicate是(Int) -> Boolean。
*/
fun foo(p: Predicate) = p(42)
fun main(args: Array) {
val f: (Int) -> Boolean = { it > 0 }
println(foo(f)) // prints "true"
val p: Predicate = { it > 0 } // 这里的Predicate等同于(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)
@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
}