Kotlin Academy · 课时

在运行时读取注解

Q: 「在运行时读取注解」这节课中我会学到什么？

使用 Kotlin 反射从声明中获取注解实例。 你通过在浏览器中直接运行的动手代码来练习 Kotlin Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

使用 Kotlin 反射从声明中获取注解实例。

在运行时读取注解 是 CoddyKit 上的免费 Kotlin Academy 课时。这是第 3 节课，共 4 节。你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。这是 Kotlin Academy 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 Kotlin Academy 课程共包含 4 节课。

前置条件

要在运行时读取注解，您需要满足以下条件：(1) 使用 @Retention(RUNTIME) 声明注解；(2) 类路径中包含 kotlin-reflect 依赖项；(3) 拥有指向带注解元素的 KClass、KFunction 或 KProperty 引用。

从 KClass 读取注解

对 KClass 调用 annotations，可以获取该类上的所有注解；也可以使用 findAnnotation() 获取特定类型的注解：

@Retention(AnnotationRetention.RUNTIME)
@Target(AnnotationTarget.CLASS)
annotation class Table(val name: String)

@Table(name = "users")
class UserEntity

val ann = UserEntity::class.findAnnotation<Table>()
println(ann?.name)  // "users"

从属性读取注解

通过 KProperty.annotations 或 findAnnotation() 访问属性上的注解：

@Retention(AnnotationRetention.RUNTIME)
@Target(AnnotationTarget.PROPERTY)
annotation class Column(val name: String)

data class User(@Column("user_name") val name: String)

val prop = User::name
val col = prop.findAnnotation<Column>()
println(col?.name)  // "user_name"

从函数读取注解

使用 KFunction.findAnnotation() 读取函数上的注解：

@Retention(AnnotationRetention.RUNTIME)
@Target(AnnotationTarget.FUNCTION)
annotation class Transactional

class UserService {
    @Transactional
    fun save(user: User) { /*...*/ }
}

val fn = UserService::save
val isTx = fn.hasAnnotation<Transactional>()
println(isTx)  // true

遍历所有属性以查找注解

一种常见模式是扫描类中声明的所有属性，并收集使用特定注解标记的属性：

fun <A : Annotation> KClass<*>.annotatedProperties(
    annotationClass: KClass<A>
): List<Pair<KProperty1<*, *>, A>> =
    declaredMemberProperties
        .mapNotNull { prop ->
            prop.findAnnotation(annotationClass)?.let { ann -> prop to ann }
        }

读取参数上的注解

通过 KFunction.parameters 访问构造函数参数上的注解：

class Repo(
    @param:Validate(minLength = 3) val name: String
)

val ctor = Repo::class.primaryConstructor!!
val param = ctor.parameters.first()
val ann = param.findAnnotation<Validate>()
println(ann?.minLength)  // 3

hasAnnotation 与 findAnnotation

使用 hasAnnotation() 进行布尔检查；当需要注解的属性值时，使用 findAnnotation()。这两个函数都是来自 kotlin.reflect.full 的扩展函数。

遍历类层次结构

Kotlin 反射不会自动继承超类或接口上的注解。若需要继承的注解，您必须遍历 KClass.superclasses，或使用 KClass.allSuperclasses。

fun KClass<*>.findAnnotationRecursive(ann: KClass<out Annotation>) =
    generateSequence(this) { null } // simplified — real impl walks supers
        .flatMap { it.annotations }
        .firstOrNull { it.annotationClass == ann }

性能

反射调用速度较慢。如果您在框架启动时扫描注解，请将结果缓存到以 KClass 为键的映射中。切勿在每次请求或每帧执行的高频路径中读取注解。

使用位置目标和 JVM 字段

对于使用 @field: 目标的属性注解，该注解位于 JVM 后备字段上。请通过 Java 反射（KProperty.javaField?.annotations）访问它，而不要使用 Kotlin 的 annotations 列表，因为后者只涵盖 Kotlin 声明位置。

实践示例：简单 ORM 映射器

一个小型 ORM 映射器读取 @Column 注解，以构建 SQL 列列表：

fun columns(klass: KClass<*>): String =
    klass.declaredMemberProperties
        .mapNotNull { it.findAnnotation<Column>()?.name }
        .joinToString(", ")

println(columns(User::class))  // "user_name, email"

快速检查

如何从 KClass 中读取类型为 MyAnn 的特定注解？

回顾：在运行时读取注解

关键要点：

注解必须具有 @Retention(RUNTIME)
使用 findAnnotation() 获取注解的值，使用 hasAnnotation() 进行布尔检查
适用于 KClass、KFunction、KProperty 和 KParameter
在启动时缓存扫描结果，避免每次请求产生额外开销
对于 @field: 注解，请使用 KProperty.javaField

常见问题解答

「在运行时读取注解」课时是免费的吗？

是的 — 「在运行时读取注解」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 Kotlin Academy 课程的其余内容，请升级到 CoddyKit PRO。 Kotlin Academy 课程共包含 4 节课。

「在运行时读取注解」这节课中我会学到什么？

使用 Kotlin 反射从声明中获取注解实例。你通过在浏览器中直接运行的动手代码来练习 Kotlin Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 Kotlin Academy 需要有经验吗？

无需任何先前经验。CoddyKit 上的 Kotlin Academy 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。这是第 3 节课，共 4 节。

「在运行时读取注解」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 Kotlin Academy 课中编写并运行代码吗？

能。每节 Kotlin Academy 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

← 返回 Kotlin Academy