Kotlin Academy · 课时

定义注解

Q: 「定义注解」这节课中我会学到什么？

创建自定义注解 你通过在浏览器中直接运行的动手代码来练习 Kotlin Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

创建自定义注解

第 2 / 4 课13 个步骤

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

声明注解

您可以使用 annotation class 关键字定义注解。最简单的注解不携带任何数据，只充当标记。

annotation class Beta

@Beta
fun newFeature() = "experimental"

fun main() {
    println(newFeature())
}

注解参数

注解可以通过构造函数参数保存数据。允许的类型十分有限：基本类型、String、枚举、其他注解、KClass，以及这些类型的数组。

annotation class ApiVersion(val value: Int)

@ApiVersion(2)
fun endpoint() = "v2"

fun main() {
    println(endpoint())
}

@Target

@Target 会限制注解可以应用的位置。您可以传入一个或多个 AnnotationTarget 值，例如 CLASS、FUNCTION 或 PROPERTY。

@Target(AnnotationTarget.FUNCTION)
annotation class Loggable

@Loggable
fun process() = "processing"

fun main() {
    println(process())
}

@Retention

@Retention 控制注解可以保留多长时间：

SOURCE — 由编译器丢弃
BINARY — 保留在类文件中，但对反射不可见
RUNTIME — 保留且对反射可见（默认值）

@Retention(AnnotationRetention.RUNTIME)
annotation class Important

@Important
class Order

fun main() {
    println("Important is readable at runtime")
}

多个目标

列出多个目标，即可允许注解出现在多个位置。这里的注解既可以应用于类，也可以应用于函数。

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

@Audited
class Account {
    @Audited
    fun withdraw() = "ok"
}

fun main() {
    println(Account().withdraw())
}

参数默认值

注解参数可以设置默认值，因此调用方可以省略这些参数。这样可以让常见情况更加简洁。

annotation class Cache(val seconds: Int = 60)

@Cache
fun cheap() = 1

@Cache(seconds = 300)
fun expensive() = 2

fun main() {
    println("" + cheap() + " " + expensive())
}

数组参数

您可以使用数组类型。在注解用法中，使用数组字面量语法 [ ... ] 提供值。

annotation class Roles(val names: Array<String>)

@Roles(["admin", "editor"])
fun restricted() = "secret"

fun main() {
    println(restricted())
}

@Repeatable

默认情况下，一个注解在每个元素上只能出现一次。将其标记为 @Repeatable 后，就可以多次应用该注解。

@Repeatable
annotation class Tag(val value: String)

@Tag("db")
@Tag("cache")
fun layered() = "ok"

fun main() {
    println(layered())
}

嵌套注解参数

一个注解参数本身可以是另一个注解，这样您就能构建结构化元数据。

annotation class Author(val name: String)
annotation class Module(val owner: Author)

@Module(Author("Grace"))
class Payments

fun main() {
    println("Nested annotation metadata defined")
}

设计良好的注解

一个设计良好的注解：

具有明确且单一的用途
设置 @Target，使误用成为编译错误
仅在反射需要时使用 RUNTIME 保留策略
提供合理的默认值

从定义到使用

定义注解只是整个过程的一半。注解本身只是不会产生作用的元数据。必须有某些机制读取它——通常是在运行时通过反射读取，或是在编译时由注解处理器读取。您很快就会使用反射。

快速检查

测试您对注解定义方式的理解。

在交互式课程中回答

回顾

您学会了定义注解：

带参数的 annotation class
使用 @Target 限制放置位置
使用 @Retention 控制生命周期
使用 @Repeatable 和默认值

下一步：使用反射检查类型。

免费开始

用 AI 导师学习 Kotlin — 免费

在浏览器中编写并运行真实代码，获得全天候 AI 导师的即时帮助，并在网页或应用中继续学习。

课程: 51
课程: 203

免费开始学习查看完整课程

常见问题解答

「定义注解」课时是免费的吗？

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

「定义注解」这节课中我会学到什么？

创建自定义注解你通过在浏览器中直接运行的动手代码来练习 Kotlin Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 Kotlin Academy 需要有经验吗？

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

「定义注解」课时需要多长时间？

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

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

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

此课程中的所有课时

← 返回 Kotlin Academy