注解(Annotations)是Kotlin中一种强大的元编程工具，它允许你在代码中添加元数据，这些元数据可以被编译器、运行时环境或第三方工具处理。下面详细介绍Kotlin注解的相关知识。

基本概念

注解是用@符号前缀表示的元数据标签：

@Deprecated("Use newFunction instead", ReplaceWith("newFunction()"))
fun oldFunction() { ... }

注解声明

要声明一个注解，使用annotation关键字：

annotation class Fancy

带参数的注解

annotation class Special(val why: String)

@Special("example") class Foo {}

注解参数可以是：

• 基本类型(Int, Long等)

• 字符串

• 类(KClass<*>)

• 枚举

• 其他注解

• 以上类型的数组

内置注解

Kotlin提供了一些内置注解：

1. 标准库注解

• @Deprecated - 标记元素已过时

• @Suppress - 抑制警告

• @JvmName - 指定JVM名称

• @JvmStatic - 生成静态成员

• @JvmOverloads - 生成重载方法

• @Throws - 声明抛出异常

2. 元注解(用于注解其他注解)

• @Target - 指定注解可应用的目标(类、函数、属性等)

• @Retention - 指定注解保留策略(SOURCE, BINARY, RUNTIME)

• @Repeatable - 允许在同一元素上多次使用同一注解

• @MustBeDocumented - 表示注解是公开API的一部分

注解使用目标

当注解属性或主构造函数参数时，可以使用目标指定：

class Example(
    @field:Positive val number: Int,
    @param:MyAnnotation param: String
) {
    @get:JvmName("isEmpty")
    val isEmpty: Boolean
        get() = size == 0
}

可用目标：

• file

• property

• field

• get (属性getter)

• set (属性setter)

• receiver (扩展函数或属性接收者)

• param (构造函数参数)

• setparam (属性setter参数)

• delegate (委托属性字段)

Java注解互操作

Kotlin兼容Java注解：

@java.lang.Deprecated // 使用Java注解
fun javaDeprecated() { ... }

注解参数限制

注解参数不能是：

• 可空类型

• 泛型类型

• 非编译时常量

使用示例

自定义注解

@Target(AnnotationTarget.CLASS, AnnotationTarget.FUNCTION)
@Retention(AnnotationRetention.RUNTIME)
annotation class DebugLog(val level: Int = 1)

@DebugLog(2)
class Test {
    @DebugLog fun testMethod() { ... }
}

运行时处理注解

fun processAnnotations(obj: Any) {
    obj.javaClass.annotations.forEach { annotation ->
        when (annotation) {
            is DebugLog -> println("Debug level: ${annotation.level}")
        }
    }
}

高级用法

重复注解

@Repeatable
@Target(AnnotationTarget.CLASS)
annotation class Tag(val name: String)

@Tag("First")
@Tag("Second")
class MyClass

注解作为参数

annotation class Ann(val arg: String)

annotation class AnnContainer(vararg val value: Ann)

@AnnContainer(Ann("a"), Ann("b"))
class C

注意事项

1. 注解参数必须是编译时常量

2. 注解本身不能包含任何代码

3. 注解在运行时处理需要@Retention(AnnotationRetention.RUNTIME)

4. Kotlin注解与Java注解在字节码层面兼容

通过合理使用注解，可以实现代码生成、静态检查、运行时处理等多种功能，大大提高代码的表达能力和工具支持。