@JvmMultifileClass 是 Kotlin 中的一个文件级注解（File-level Annotation），通常与 @file:JvmName 配合使用，将多个 Kotlin 文件的顶层声明合并到同一个 JVM 类中。
其核心作用是解决“同一功能模块的代码分散在多个 Kotlin 文件中时，如何在 Java 中以统一的类名调用”的问题，提升跨语言调用的便利性。
背景与问题场景
Kotlin 的顶层函数（不在类或对象中定义的函数）默认会被编译到一个与文件名关联的 JVM 类中（命名规则：文件名 + "Kt"，例如 StringUtils.kt 生成 StringUtilsKt 类）。
若一个功能模块的工具方法分散在多个 Kotlin 文件中（例如 StringUtils.kt、NumberUtils.kt），每个文件会生成独立的 JVM 类（如 StringUtilsKt、NumberUtilsKt），导致 Java 调用时需要分别引用不同的类，不够直观。
示例问题：
// File1: StringUtils.kt
package com.example.utils
fun isEmpty(str: String) = str.isEmpty()
// File2: NumberUtils.kt
package com.example.utils
fun isPositive(num: Int) = num > 0
// Java 调用时需分别引用两个类：
// boolean empty = StringUtilsKt.isEmpty("test");
// boolean positive = NumberUtilsKt.isPositive(10);
@JvmMultifileClass 的解决方案
通过 @file:JvmName 为多个文件指定相同的 JVM 类名，并添加 @file:JvmMultifileClass 注解，Kotlin 编译器会将这些文件的顶层声明合并到同一个 JVM 类中。这样，Java 调用时只需通过一个类名即可访问所有分散的顶层函数。
使用步骤与示例
- 为目标文件指定相同的 @file:JvmName
在所有需要合并的 Kotlin 文件顶部，使用 @file:JvmName 注解指定相同的 JVM 类名（需包含包名）。
- 添加 @file:JvmMultifileClass 注解
在每个文件的 @file:JvmName 下方添加 @file:JvmMultifileClass 注解，告知编译器合并这些文件的顶层声明。
示例代码：
// File1: StringUtils.kt
@file:JvmName("CommonUtils") // 指定 JVM 类名为 com.example.utils.CommonUtils
@file:JvmMultifileClass // 标记为需要合并的文件
package com.example.utils // 包名需一致
fun isEmpty(str: String) = str.isEmpty()
// File2: NumberUtils.kt
@file:JvmName("CommonUtils") // 与 File1 相同的 JVM 类名
@file:JvmMultifileClass // 同样标记为需要合并的文件
package com.example.utils // 包名必须一致
fun isPositive(num: Int) = num > 0
- Java 调用效果
编译后，两个文件的顶层函数会被合并到 com.example.utils.CommonUtils 类中。Java 调用时只需通过该统一类名访问：
// Java 调用（无需区分 StringUtilsKt 或 NumberUtilsKt）
boolean empty = CommonUtils.isEmpty("test"); // 来自 StringUtils.kt
boolean positive = CommonUtils.isPositive(10); // 来自 NumberUtils.kt
关键注意事项
-
包名必须一致：所有参与合并的 Kotlin 文件必须属于同一个包（即 package 语句相同），否则无法合并。
-
@file:JvmName 的名称需全局唯一：指定的 JVM 类名（如 CommonUtils）不能与同一模块中其他类的名称冲突，否则会导致编译错误。
-
仅合并顶层声明：@JvmMultifileClass 仅对顶层函数、顶层属性生效，类、对象、伴生对象等声明不会被合并。
-
注解顺序要求：@file:JvmName 必须位于 @file:JvmMultifileClass 之前，且两者均需放在文件顶部（package 语句之前）。
-
避免过度合并：合并的文件应具有逻辑关联性（如同一功能模块的工具类），否则可能导致 JVM 类过于庞大，影响可读性和维护性。
典型应用场景
• 工具类拆分：将一个大型工具类（如 StringUtils、NumberUtils）拆分为多个 Kotlin 文件，但通过 @JvmMultifileClass 合并为同一个 JVM 类，方便 Java 调用。
• 模块化开发：团队开发中，不同开发者负责同一功能模块的不同部分（如网络请求的工具函数、数据校验的工具函数），通过合并注解保持对外接口的统一。
总结
@JvmMultifileClass 是 Kotlin 为优化 JVM 平台互操作性设计的注解，通过与 @file:JvmName 配合，将多个文件的顶层声明合并到同一个 JVM 类中，解决了“分散代码的统一调用”问题。合理使用可提升跨语言代码的可读性和维护性，尤其适用于工具类或模块化开发的场景。
