Kotlin JVM 注解详解

前言

Kotlin 作为一门现代 JVM 语言，提供了出色的 Java 互操作性。为了更好地支持与 Java 代码的交互，Kotlin 提供了一系列 JVM 相关注解。这些注解不仅能帮助我们控制 Kotlin 代码编译成 Java 字节码的行为，还能让我们的 Kotlin 代码更好地被 Java 代码调用。虽然在日常开发中我们最常用的是 @JvmOverloads、@JvmStatic、@JvmName 和 @JvmField 这几个注解，但 Kotlin 其实还提供了更多强大的 JVM 注解。本文系统地整理下这些注解的作用、使用场景和具体示例，便于开发。
ps：以下整理基于kotlin-stdlib-1.7.10.jar!\kotlin\jvm\JvmInline.class。

目录

• @JvmOverloads
• @JvmStatic
• @JvmName
• @JvmMultifileClass
• @JvmPackageName
• @JvmSynthetic
• @Throws
• @JvmField
• @JvmSuppressWildcards
• @JvmWildcard
• @JvmInline
• @JvmRecord

@JvmOverloads

作用

为带有默认参数值的函数生成重载方法。

使用场景

当 Kotlin 函数需要被 Java 代码调用时，特别是函数包含默认参数值的情况。

示例

@JvmOverloads
fun greet(name: String, greeting: String = "Hello") {
    println("$greeting, $name!")
}

编译后的 Java 代码

void greet(String name) {
    greet(name, "Hello");
}

void greet(String name, String greeting) {
    System.out.println(greeting + ", " + name + "!");
}

@JvmStatic

作用

生成静态方法或静态属性访问器。

使用场景

在 companion object 中定义需要作为静态成员的方法或属性。

示例

class MyClass {
    companion object {
        @JvmStatic
        fun staticMethod() { }
        
        @JvmStatic
        var staticProperty: String = ""
    }
}

@JvmName

作用

指定生成的 Java 类或方法的名称。

使用场景

• 解决签名冲突
• 自定义生成的 Java 代码名称
• 改善 Java 代码的可读性

示例

@JvmName("filterString")
fun filter(list: List<String>) { }

@JvmName("filterInt")
fun filter(list: List<Int>) { }

@JvmMultifileClass

作用

指示编译器生成多文件类，将多个文件中的顶级函数和属性合并到一个类中。

使用场景

需要将分散在多个文件中的相关功能组织在一起时。

示例

// File1.kt
@JvmName("Utils")
@JvmMultifileClass
fun function1() { }

// File2.kt
@JvmName("Utils")
@JvmMultifileClass
fun function2() { }

@JvmPackageName

作用

更改生成的 .class 文件的 JVM 包名。

使用场景

需要自定义生成的 Java 代码的包名时。

注意

• 内部注解，不推荐直接使用
• 自 Kotlin 1.2 版本引入

@JvmSynthetic

作用

在 Java 字节码中设置 ACC_SYNTHETIC 标志，使目标对 Java 代码不可见。

使用场景

需要隐藏 Kotlin 特定的目标，使其对 Java 代码不可见，但保持对 Kotlin 代码可见。

示例

@JvmSynthetic
fun internalFunction() { }

@Throws

作用

指定函数编译为 JVM 方法时应声明的异常。

使用场景

需要从 Kotlin 代码中抛出 Java 检查异常时。

示例

@Throws(IOException::class)
fun readFile() { }

编译后的 Java 代码

void readFile() throws IOException { }

@JvmField

作用

指示编译器不要为属性生成 getter/setter，而是将其作为字段暴露。

使用场景

需要将 Kotlin 属性作为 Java 字段使用时。

示例

class MyClass {
    @JvmField
    var field: String = ""
}

@JvmSuppressWildcards

作用

控制是否生成通配符。

使用场景

需要控制泛型类型参数的 Java 表示时。

示例

@JvmSuppressWildcards
fun process(list: List<String>) { }

@JvmWildcard

作用

为带声明点变异的类型参数生成通配符。

使用场景

需要控制泛型类型参数的 Java 表示时。

示例

fun process(@JvmWildcard list: List<String>) { }

@JvmInline

作用

指定值类为内联类。

使用场景

创建零开销的类型安全包装器。

示例

@JvmInline
value class Password(val value: String)

特点

• 只能有一个主构造函数参数
• 参数必须是不可变的（val）
• 不能有 backing field
• 不能有 init 块
• 不能有 lateinit 属性

@JvmRecord

作用

指示编译器将类标记为记录类。

使用场景

创建不可变的数据类。

示例

@JvmRecord
data class Person(val name: String, val age: Int)

特点

• 自 Kotlin 1.5 版本引入
• 生成 toString、equals、hashCode 方法
• 适用于不可变数据模型

最佳实践

1. 选择合适的注解

   • 根据具体需求选择合适的注解
   • 考虑 Java 互操作性的需求
   • 注意注解的版本兼容性

2. 性能考虑

   • 使用 @JvmInline 减少运行时开销
   • 合理使用 @JvmField 避免不必要的 getter/setter
   • 注意 @JvmStatic 的使用场景

3. 代码可维护性

   • 使用 @JvmName 提高代码可读性
   • 使用 @Throws 明确异常处理
   • 使用 @JvmSynthetic 控制 API 可见性

4. 版本兼容性

   • 注意注解的引入版本
   • 考虑向后兼容性
   • 关注 Kotlin 版本更新