Kotlin Academy · 课时

创建并指定自定义注解的使用目标

Q: 「创建并指定自定义注解的使用目标」这节课中我会学到什么？

定义带保留策略的注解，并将其应用于类、函数和属性。 你通过在浏览器中直接运行的动手代码来练习 Kotlin Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

定义带保留策略的注解，并将其应用于类、函数和属性。

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

为什么需要自定义注解？

注解是附加到声明（类、函数、属性和参数）上的元数据。自定义注解可以让您标记代码，以便框架、构建工具（KSP/KAPT）或您自己的运行时逻辑进行处理。

声明注解

使用 annotation class 关键字。注解类可以拥有构造函数参数，但参数只能是基本类型、String、KClass、枚举、其他注解或它们的数组：

annotation class Validate(val minLength: Int = 1, val maxLength: Int = 255)

元注解：@Target

@Target 限制注解的使用位置。常见目标包括：CLASS、FUNCTION、PROPERTY、FIELD、VALUE_PARAMETER 和 CONSTRUCTOR。

@Target(AnnotationTarget.PROPERTY, AnnotationTarget.VALUE_PARAMETER)
annotation class Validate(val minLength: Int = 1, val maxLength: Int = 255)

@Retention：注解何时可用？

@Retention 控制注解的生命周期：

SOURCE——编译后丢弃
BINARY——存储在 .class 文件中，但无法通过反射看到
RUNTIME——存储并在运行时可见（大多数使用场景的默认值）

@Retention(AnnotationRetention.RUNTIME)
@Target(AnnotationTarget.PROPERTY)
annotation class Validate(val minLength: Int = 1)

@Repeatable：多次应用同一注解

默认情况下，一个注解只能应用于每个声明一次。将其标记为 @Repeatable 后，即可多次应用：

@Repeatable
@Target(AnnotationTarget.FUNCTION)
annotation class Role(val name: String)

标注构造函数和参数

您可以标注构造函数参数和主构造函数属性。使用 @field:、@get: 或 @param: 使用位置目标，控制哪个元素接收注解：

data class User(
    @field:Validate(minLength = 2) val name: String,
    @field:Validate(minLength = 0, maxLength = 120) val email: String
)

使用位置目标

Kotlin 会从一个属性生成多个字节码元素（字段、获取器、设置器和参数）。使用位置目标用于指定哪个元素接收注解：

@field: 后备字段
@get: 获取器
@set: 设置器
@param: 构造函数参数

标注类

在类上添加注解，可用于标记该类以供框架处理（例如，将类标记为可序列化、可注入，或标记为特定模块的一部分）：

@Target(AnnotationTarget.CLASS)
@Retention(AnnotationRetention.RUNTIME)
annotation class Repository

@Repository
class UserRepository

@MustBeDocumented

添加 @MustBeDocumented 可确保注解出现在生成的 API 文档中。对于构成公共 API 契约一部分的注解，请使用它。

@MustBeDocumented
@Target(AnnotationTarget.CLASS)
annotation class PublicApi(val since: String)

注解参数：默认值和数组

参数可以拥有默认值，也可以使用 vararg 关键字或显式数组类型来接收数组：

annotation class Roles(vararg val value: String)

@Roles("ADMIN", "EDITOR")
class AdminPanel

注解中的 KClass 参数

注解可以通过 KClass 引用类类型：

annotation class Serializer(val using: KClass<out Any>)

@Serializer(using = GsonAdapter::class)
class Event

快速检查

哪个 @Retention 值可以让自定义注解在运行时通过 Kotlin 反射访问？

回顾：自定义注解

关键要点：

使用 annotation class 声明；参数仅限于基本类型、String、KClass、枚举和数组
@Target——可以应用到哪里
@Retention——何时可用（反射场景使用 RUNTIME）
@Repeatable——允许在一个声明上多次应用
使用位置目标（@field:、@get: 等）控制哪个字节码元素接收注解

常见问题解答

「创建并指定自定义注解的使用目标」课时是免费的吗？

是的 — 「创建并指定自定义注解的使用目标」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 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