【Kotlin】Kotlin 常用注解详解与实战 - 实践

Kotlin 常用注解详解与实战

在 Kotlin 开发中，注解（Annotation）是一种非常常见的工具。它们不仅能帮助我们在编译期、运行时提供额外的信息，还能与框架（如 Spring、Room、Retrofit、Ktor 等）结合，发挥强大的作用。
本文将结合 具体示例，带你快速掌握 Kotlin 中常用的注解及使用方式。

目录

  1. 什么是注解

  2. Kotlin 常用注解分类

  3. 自定义注解

  4. 总结

什么是注解

注解（Annotation）是一种 元数据，它不会直接改变程序逻辑，但可以：

  • 给编译器提供提示
  • 在运行时通过反射获取额外信息
  • 被框架或库解析，从而改变运行行为

Kotlin 里的注解大多和 Java 保持兼容，因此很多 Java 的注解也能在 Kotlin 中使用。

Kotlin 常用注解分类

1. 基础注解

@JvmStatic

作用：在 伴生对象 或 object 单例 中，把方法或属性暴露为 Java 的静态方法。

class Utils {
companion object {
@JvmStatic
fun hello() {
println("Hello from Kotlin")
}
}
}

在 Java 中调用：

Utils.hello();
// ✅ 可以直接调用静态方法
@JvmOverloads

作用：给带有默认参数的方法自动生成 Java 可调用的重载方法。

class Greeting {
@JvmOverloads
fun sayHello(name: String = "World", times: Int = 1) {
repeat(times) {
println("Hello, $name")
}
}
}

在 Java 中调用：

new Greeting().sayHello();
new Greeting().sayHello("Tom");
new Greeting().sayHello("Tom", 3);
@JvmName

作用：修改 Kotlin 函数或文件的字节码方法名/类名。

@file:JvmName("MathUtils") // 改变生成的类名
package demo
fun add(a: Int, b: Int): Int = a + b

在 Java 中调用：

int result = MathUtils.add(1, 2);

2. 修饰符相关注解

@Deprecated

作用：标记方法或类为 弃用，并给出替代方案。

@Deprecated("Use newHello instead", ReplaceWith("newHello()"))
fun oldHello() {
println("Old Hello")
}
fun newHello() {
println("New Hello")
}

调用 oldHello() 时，IDE 会提示替换为 newHello()。

@Suppress

作用：抑制编译器或 IDE 的特定警告。

@Suppress("UNCHECKED_CAST")
fun <T>
  unsafeCast(value: Any): T {
  return value as T
  }
@PublishedApi

作用：修饰 internal 成员，保证它们能被 inline 方法正常使用。

internal class InternalApi {
@PublishedApi
internal fun log(msg: String) {
println("Log: $msg")
}
}

3. 序列化与反射注解

@Serializable （Kotlinx 序列化）

作用：将类标记为可序列化。

import kotlinx.serialization.Serializable
@Serializable
data class User
(
val id: Int,
val name: String
)

结合 Json.encodeToString(User(1, "Tom")) 就能转换为 JSON。

@Transient

作用：序列化时忽略该字段。

@Serializable
data class User
(
val id: Int,
val name: String,
@Transient val password: String = ""
)
@Reflection（配合反射）

例如常用于 KClass，框架会通过注解拿到类信息。

4. Android / 框架常见注解

@Inject（依赖注入，Dagger/Hilt）
class Repository @Inject
constructor()
@GET / @POST（Retrofit）
interface ApiService {
@GET("users")
suspend fun getUsers(): List<User>
  }
@Entity / @Dao（Room 数据库）
@Entity
data class User
(
@PrimaryKey val id: Int,
val name: String
)
@Dao
interface UserDao {
@Query("SELECT * FROM User")
fun getAll(): List<User>
  }

自定义注解

除了使用框架注解，我们也可以自定义：

@Target(AnnotationTarget.CLASS, AnnotationTarget.FUNCTION)
@Retention(AnnotationRetention.RUNTIME)
annotation class Loggable
(val level: String = "INFO")
@Loggable("DEBUG")
class MyService {
fun run() {
println("Service is running")
}
}

在运行时可以通过反射获取注解信息：

val clazz = MyService::class
val annotation = clazz.annotations.find { it is Loggable
} as? Loggable
println("Log level: ${annotation?.level
}")

总结

  • Kotlin 注解既能帮助 Java 互操作，也能与框架集成。

  • 常用注解分类：

    • 基础（@JvmStatic / @JvmOverloads / @JvmName）
    • 修饰符（@Deprecated / @Suppress / @PublishedApi）
    • 序列化（@Serializable / @Transient）
    • 框架注解（Retrofit / Room / Dagger）

  • 自定义注解可结合反射使用，扩展框架功能。

注解在 Kotlin 开发中既是 桥梁（兼容 Java），也是 利器（配合框架、工具提升开发效率）。

posted @ 2025-08-27 09:55  wzzkaifa  阅读(22)  评论(0)    收藏  举报