第四部分：Kotlin 进阶与实战应用

第 15 章：注解与反射

2. 元注解

什么是元注解？

元注解（Meta-annotations）是用于修饰其他注解的注解。它们提供了一种机制，用于定义注解的行为和作用范围。Kotlin 中的元注解直接借鉴自 Java，但语法更简洁，并增加了一些 Kotlin 特有的特性。

Kotlin 中的常用元注解

以下是 Kotlin 支持的元注解及其作用：

  1. @Target
    指定注解可以应用的目标（如类、函数、属性、表达式等）。
    示例：

    @Target(AnnotationTarget.CLASS, AnnotationTarget.FUNCTION)
annotation class MyAnnotation

    常用目标类型：

    • CLASS：类或接口
    • FUNCTION：函数
    • PROPERTY：属性
    • FIELD：字段
    • VALUE_PARAMETER：函数参数
    • EXPRESSION：表达式

  2. @Retention
    指定注解的保留策略，即注解在何时可用（源码、编译期或运行时）。
    可选值：

    • SOURCE：仅保留在源码中，编译后丢弃（如 @Suppress）。
    • BINARY：保留到编译后的字节码，但运行时不可见。
    • RUNTIME：保留到运行时，可通过反射读取（默认值）。

    示例：

    @Retention(AnnotationRetention.RUNTIME)
annotation class MyAnnotation

  3. @Repeatable
    允许在同一目标上多次使用相同的注解。
    示例：

    @Repeatable
annotation class Tag(val name: String)

@Tag("Kotlin")
@Tag("Annotation")
class MyClass

  4. @MustBeDocumented
    强制注解包含在生成的 API 文档中（如 KDoc 或 JavaDoc）。
    示例：

    @MustBeDocumented
annotation class ExperimentalFeature

自定义元注解示例

以下是一个结合元注解的自定义注解示例：

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

元注解的实际应用场景

  1. 框架开发：如 Spring 或 Ktor 中通过元注解定义控制器、路由等。
  2. 代码检查工具：自定义注解结合 SOURCE 保留策略实现静态分析。
  3. 依赖注入：标记需要注入的字段或构造函数。

注意事项

  • Kotlin 注解默认保留到运行时（RUNTIME），而 Java 默认是 CLASS。
  • 如果注解需要被 Java 调用，需添加 @JvmAnnotation 确保兼容性。

通过合理使用元注解，可以显著提升代码的可读性和工具链的集成能力。

Last Updated::