Kotlin 与 Java 互操作中常用注解

以下是 Kotlin 与 Java 互操作中常用注解的详细说明，涵盖其作用、使用场景及注意事项：

---

一、参数与方法适配类注解​

1. @JvmOverloads

• ​作用​：为带默认参数的 Kotlin 函数生成 Java 兼容的重载方法。

• ​使用场景​：需从 Java 调用 Kotlin 默认参数方法时。

• ​示例​：

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

  生成 Java 重载：

  greet();        // 调用 greet("")
  greet("Alice"); // 调用 greet("Alice")

• ​限制 ​：不可用于扩展函数或 vararg参数。

2. @JvmName

• ​作用​：修改 Kotlin 元素（函数、类、属性）在 Java 中的名称。

• ​使用场景​：

  • 解决 Kotlin 特殊字符（如 ?）与 Java 命名规范冲突。

  • 避免同名方法冲突。

• ​示例​：

  @file:JvmName("StringUtils") // 修改文件生成类名
  package com.example
  fun isNullOrEmpty(str: String?): Boolean = str.isNullOrEmpty()

  Java 调用：StringUtils.isNullOrEmpty("")。

---

二、属性与字段适配类注解​

1. @JvmField

• ​作用​：将 Kotlin 属性直接暴露为 Java 公共字段，跳过 getter/setter。

• ​使用场景​：性能敏感场景或需与 Java 反射库（如 Gson）集成。

• ​示例​：

  class User {
      @JvmField val name: String = "Alice"
  }

  Java 直接访问：user.name。

• ​限制 ​：不可用于私有属性或 var变量。

2. @JvmStatic

• ​作用​：将伴生对象或对象声明的成员暴露为 Java 静态成员。

• ​使用场景​：需从 Java 以静态方式调用 Kotlin 伴生对象方法。

• ​示例​：

  class Config {
      companion object {
          @JvmStatic val API_KEY = "12345"
      }
  }

  Java 调用：Config.API_KEY。

---

三、异常与类型安全类注解​

1. @Throws

• ​作用​：声明 Kotlin 方法可能抛出的异常，强制 Java 调用者处理。

• ​使用场景 ​：Kotlin 抛出受检异常（如 IOException）时。

• ​示例​：

  @Throws(IOException::class)
  fun readFile(path: String) {
      throw IOException("File not found")
  }

  Java 需添加 try-catch。

2. @JvmSuppressWildcards

• ​作用 ​：禁止 Kotlin 泛型类型参数在 Java 中被转换为通配符（?）。

• ​使用场景​：需严格保持泛型类型不变的场景（如序列化）。

• ​示例​：

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

  Java 无法传入 List<?>。

---

四、文件与包级配置注解​

1. @file:JvmName

• ​作用​：修改 Kotlin 文件编译生成的 Java 类名。

• ​示例​：

  @file:JvmName("MathUtils")
  package com.example
  fun add(a: Int, b: Int): Int = a + b

  Java 调用：MathUtils.add(1, 2)。

2. @file:JvmMultifileClass

• ​作用​：将多个 Kotlin 文件合并到同一个 Java 类中。

• ​使用场景​：拆分大型工具类为多个文件。

• ​示例​：

  // File1.kt
  @file:JvmName("Utils")
  @file:JvmMultifileClass
  fun func1() { ... }
  
  // File2.kt
  @file:JvmName("Utils")
  @file:JvmMultifileClass
  fun func2() { ... }

  Java 调用：Utils.func1()和 Utils.func2()。

---

五、其他实用注解​

1. @Synchronized

• ​作用 ​：将方法标记为同步方法，等效于 Java 的 synchronized关键字。

• ​示例​：

  @Synchronized
  fun incrementCounter() { ... }

  确保多线程安全。

2. @Volatile

• ​作用​：标记属性为易变，确保多线程可见性。

• ​示例​：

  @Volatile
  var isRunning = true

  避免指令重排序问题。

---

📝 ​总结​

​注解​	​核心用途​	​典型场景​
@JvmOverloads	生成默认参数重载方法	Java 调用 Kotlin 默认参数函数
@JvmName	修改元素在 Java 中的名称	解决命名冲突或规范适配
@JvmField	暴露属性为 Java 字段	性能优化或与反射库集成
@JvmStatic	暴露伴生对象成员为静态方法	Java 静态调用伴生对象方法
@Throws	声明受检异常	Kotlin 抛出 Java 受检异常

​注意事项​：

• 避免滥用 @JvmField破坏封装性。

• @JvmOverloads可能生成冗余重载，需权衡 API 复杂度。

• 泛型相关注解（如 @JvmSuppressWildcards）需谨慎处理类型擦除问题。