Kotlin 注解机制深度解析 - 从基础到高级用法

2025-06-27 18:38:07作者：裴麒琰

什么是注解

注解（Annotations）是 Kotlin 中一种强大的元数据机制，它允许开发者为代码添加额外的信息。这些信息可以被编译器、开发工具或运行时环境读取和使用。注解本身不会直接影响代码逻辑，但它们可以改变代码的处理方式。

基本语法

声明一个注解非常简单，只需要在类前加上 annotation 修饰符：

annotation class MyAnnotation

元注解：注解的注解

Kotlin 提供了几种元注解（meta-annotations），用于修饰注解类本身：

@Target - 指定注解可以应用的目标元素类型
- CLASS: 类、接口、对象
- FUNCTION: 函数
- PROPERTY: 属性
- FIELD: 字段
- 等等...
@Retention - 控制注解的保留策略
- SOURCE: 仅保留在源码中
- BINARY: 保留在编译后的字节码中
- RUNTIME: 保留到运行时（可通过反射获取）
@Repeatable - 允许在同一元素上多次使用同一注解
@MustBeDocumented - 表示注解是公共API的一部分

示例：

@Target(AnnotationTarget.CLASS, AnnotationTarget.FUNCTION)
@Retention(AnnotationRetention.RUNTIME)
@MustBeDocumented
annotation class ApiVersion(val version: String)

注解参数

注解可以包含参数，这些参数在声明注解时定义：

annotation class Route(val path: String, val method: HttpMethod)

参数支持的类型包括：

基本数据类型（Int、Long等）
字符串
KClass引用（使用::class语法）
枚举
其他注解
上述类型的数组

注意：注解参数不能为可空类型。

注解的使用场景

1. 类注解

@Serializable
class User(val name: String, val age: Int)

2. 函数注解

@Test
fun shouldReturnTrueWhenValid() {
    // 测试代码
}

3. 构造函数注解

class User @Inject constructor(val repository: UserRepository)

4. 属性访问器注解

var counter: Int = 0
    @Synchronized set

5. 文件级注解

@file:JvmName("MyUtils")
package com.example

高级用法

注解使用目标（Use-site Targets）

当注解可能应用于多个生成的Java元素时，可以指定具体目标：

class Example(
    @field:MyAnnotation val foo,   // 注解Java字段
    @get:MyAnnotation val bar,     // 注解getter方法
    @param:MyAnnotation val quux    // 注解构造参数
)

重复注解

Kotlin 1.6+ 支持重复注解：

@Repeatable
annotation class Tag(val name: String)

@Tag("important")
@Tag("fast")
fun processData() { ... }

Lambda 表达式注解

val handler = @Suspendable { /* 可挂起的代码 */ }

Java 注解互操作性

Kotlin 完全兼容 Java 注解：

@JvmStatic
fun utilityMethod() { ... }

对于Java注解中的数组参数：

// Java注解
public @interface JavaAnn {
    String[] value();
}

// Kotlin中使用
@JavaAnn("a", "b", "c") 
class MyClass

运行时处理注解

通过反射API可以获取运行时注解信息：

fun processAnnotations(obj: Any) {
    obj::class.annotations.forEach { annotation ->
        when (annotation) {
            is ApiVersion -> println("API版本: ${annotation.version}")
            // 处理其他注解...
        }
    }
}