Kotlin Academy · 课时

使用注解

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

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

为代码添加注解

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

什么是注解

注解会将元数据附加到代码上。注解本身不会改变行为，但工具、编译器和库会读取它们并据此做出决策。

您可以使用 @ 后跟名称来书写注解，并将其放在所应用元素的正前方。

第一个注解

标准库提供了多个实用的注解。@Deprecated 用于标记不应继续使用的代码，并会在调用位置显示警告。

@Deprecated("Use newGreet() instead")
fun greet() = "Hi"

fun newGreet() = "Hello"

fun main() {
    println(newGreet())
}

带参数的注解

注解可以接受参数，写法类似构造函数参数。@Deprecated 接受一条消息，还可以选择提供 ReplaceWith 提示。

@Deprecated(
    message = "Renamed for clarity",
    replaceWith = ReplaceWith("sum(a, b)")
)
fun add(a: Int, b: Int) = a + b

fun sum(a: Int, b: Int) = a + b

fun main() {
    println(sum(2, 3))
}

抑制警告

@Suppress 会告诉编译器，让其对添加了该注解的元素不显示特定警告。您需要将警告名称作为字符串传入。

@Suppress("UNUSED_VARIABLE")
fun main() {
    val unused = 42
    println("Runs without the unused-variable warning")
}

JvmStatic 及相关注解

某些注解会影响 Kotlin 编译为 JVM 代码的方式。@JvmStatic、@JvmField 和 @JvmName 会控制字节码，使 Java 调用方能够看到更友好的 API。

对于纯 Kotlin 代码，这些注解不会产生任何作用，但对于互操作性非常重要。

class Math {
    companion object {
        @JvmStatic
        fun square(x: Int) = x * x
    }
}

fun main() {
    println(Math.square(5))
}

注解使用点目标

一个属性可以生成多个 JVM 元素：字段、获取器、设置器和构造函数参数。使用点目标用于指定注解应放置的位置。

语法：@get:、@set:、@field:、@param:。

class User(@get:JvmName("fetchName") val name: String)

fun main() {
    val u = User("Ada")
    println(u.name)
}

用于 Java 互操作的 Throws

Kotlin 没有受检查的异常，因此除非添加 @Throws，否则 Java 调用方永远看不到 throws 子句。它会将异常类型记录到字节码签名中。

import java.io.IOException

@Throws(IOException::class)
fun readData(): String {
    return "data"
}

fun main() {
    println(readData())
}

多个注解

您可以在同一个元素上叠加多个注解。每个注解占一行（也可以用空格分隔）。顺序并不重要。

@Deprecated("old")
@Suppress("DEPRECATION")
fun legacy() = "still here"

fun main() {
    println(legacy())
}

表达式上的注解

注解也可以应用于表达式和局部声明，而不仅限于顶层函数或类。在函数体内部使用 @Suppress 就很常见。

fun main() {
    @Suppress("UNUSED_VARIABLE")
    val temp = computeOnce()
    println("Done")
}

fun computeOnce() = 99

OptIn 与实验性 API

库会使用自定义的选择加入注解标记不稳定的 API。要使用这些 API，您可以通过 @OptIn(SomeApi::class) 承认风险，或者传播该注解。

这样可以明确标记实验性功能，而不是让它们被意外使用。

fun main() {
    // @OptIn would appear here when calling an experimental function
    println("Opt-in keeps unstable APIs visible")
}

为什么要使用注解

注解可以向工具传达意图：编译器会在调用已弃用内容时发出警告，序列化库会将字段映射到对应内容，测试框架会查找测试方法，而 DI 框架会连接依赖项。

元数据，而不是逻辑
在编译时或运行时读取
让配置靠近代码

快速检查

测试您对注解使用方式的理解。

回顾

您学会了使用内置注解：

@Deprecated、@Suppress、@Throws
JVM 互操作：@JvmStatic、@JvmName
使用点目标，例如 @get: 和 @field:
为实验性 API 选择加入

接下来，您将定义自己的注解。

常见问题解答

「使用注解」课时是免费的吗？

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

「使用注解」这节课中我会学到什么？

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

学习 Kotlin Academy 需要有经验吗？

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

「使用注解」课时需要多长时间？

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

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

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

此课程中的所有课时

← 返回 Kotlin Academy