当前位置：首页 > news >正文

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

news 2025/8/26 12:37:29

Kotlin 常用注解详解与实战

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

什么是注解

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

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

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

Kotlin 常用注解分类

1. 基础注解

@JvmStatic

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

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

在 Java 中调用：

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

@JvmOverloads

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

class Greeting {@JvmOverloadsfun 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 demofun 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 {@PublishedApiinternal 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）
自定义注解可结合反射使用，扩展框架功能。