49、Kotlin与Java互操作：@JvmStatic、@JvmOverloads、@JvmName、平台类型

说实话，Kotlin 和 Java 互操作这块，是每个从 Java 转 Kotlin 的开发者都绕不开的坎。我记得刚用 Kotlin 那会儿，写了个工具类，Java 那边死活调不对，气得我差点把键盘摔了。后来才发现，就是少了个注解的事。

今天咱们就把这几个互操作的核心注解和概念掰扯清楚。你想想看，Kotlin 编译完还是 JVM 字节码，Java 那边怎么优雅地调用，全靠这些注解来「翻译」。

一、@JvmStatic：让伴生对象的方法变成真正的静态

Kotlin 里没有 static 关键字。你想定义静态方法？得用 companion object（伴生对象）。但问题来了——Java 那边调用时，得写成 MyClass.Companion.doSomething()，这谁受得了？

// Kotlin 代码
class MyUtil {
    companion object {
        @JvmStatic
        fun showMessage(msg: String) {
            println("消息：$msg")
        }

        fun showMessageWithoutStatic(msg: String) {
            println("消息：$msg")
        }
    }
}

// Java 调用
public class JavaCaller {
    public static void main(String[] args) {
        // 有 @JvmStatic —— 直接调用，舒服
        MyUtil.showMessage("你好");

        // 没有 @JvmStatic —— 得通过 Companion，别扭
        MyUtil.Companion.showMessageWithoutStatic("你好");
    }
}

我在项目中遇到过这种情况：团队里有人写了个工具类，所有方法都放在伴生对象里，但忘了加 @JvmStatic。结果 Java 那边的同事天天抱怨代码丑。后来我们定了个规矩：只要伴生对象里的方法是给 Java 用的，一律加 @JvmStatic。

二、@JvmOverloads：解决默认参数的兼容问题

Kotlin 支持函数参数默认值，这个特性太香了。但 Java 不支持啊！Java 那边调用时，必须把所有参数都传进去，否则编译报错。

@JvmOverloads 就是干这个的——它让编译器生成多个重载方法，每个重载方法省略一个参数。

// Kotlin 代码
class Greeter {
    @JvmOverloads
    fun greet(name: String, greeting: String = "你好", times: Int = 1) {
        repeat(times) {
            println("$greeting, $name!")
        }
    }
}

// Java 调用 —— 编译器自动生成了三个重载版本
public class JavaCaller {
    public static void main(String[] args) {
        Greeter greeter = new Greeter();

        // 相当于调用了 greet(name, "你好", 1)
        greeter.greet("小明");

        // 相当于调用了 greet(name, "早上好", 1)
        greeter.greet("小明", "早上好");

        // 全参数版本
        greeter.greet("小明", "晚上好", 3);
    }
}

嗯，这里要注意：@JvmOverloads 只对 有默认值的参数 生效。如果你所有参数都没有默认值，加了这个注解也没用。

三、@JvmName：给 Kotlin 函数换个 Java 名字

这个注解挺有意思。Kotlin 允许顶层函数和扩展函数，但 Java 没有这个概念。编译器会把顶层函数放到一个「文件名 + Kt」的类里。比如 utils.kt 里的顶层函数，Java 那边得写成 UtilsKt.doSomething()。

@JvmName 可以帮你做两件事：

1. 改类名：把 UtilsKt 改成你想要的类名
2. 解决签名冲突：Kotlin 里两个函数参数类型不同但 JVM 签名相同（比如 List<Int> 和 List<String> 在 JVM 里都是 List）

// Kotlin 代码 —— utils.kt 文件
@file:JvmName("StringUtils")

fun joinToString(list: List<String>, separator: String): String {
    return list.joinToString(separator)
}

// 解决 JVM 签名冲突
@JvmName("joinInts")
fun joinToString(list: List<Int>, separator: String): String {
    return list.joinToString(separator)
}

// Java 调用
public class JavaCaller {
    public static void main(String[] args) {
        // 类名变成了 StringUtils，而不是 UtilsKt
        StringUtils.joinToString(Arrays.asList("a", "b"), ",");

        // 两个同名函数，靠 @JvmName 区分
        StringUtils.joinInts(Arrays.asList(1, 2, 3), ",");
    }
}

我个人习惯：所有工具类的顶层函数文件，都在文件头部加 @file:JvmName。这样 Java 那边调用时，类名一看就知道是干什么的，不用猜文件名。

四、平台类型：Kotlin 眼中的「薛定谔的 null」

这是 Kotlin 和 Java 互操作里最坑的地方，没有之一。

Kotlin 有严格的空安全：String? 可空，String 不可空。但 Java 里的所有引用类型，在 Kotlin 看来都是「平台类型」——它不知道这个值到底能不能为 null。

平台类型用 String! 表示（注意那个感叹号），但你在代码里看不到这个类型，它只出现在错误提示里。

// Java 代码
public class JavaProvider {
    public static String getName() {
        return null; // 可能返回 null
    }
}

// Kotlin 代码
fun main() {
    // 危险！编译器不会报错，但运行时可能 NPE
    val name: String = JavaProvider.getName()
    println(name.length) // 这里崩了

    // 安全做法：显式声明为可空
    val safeName: String? = JavaProvider.getName()
    println(safeName?.length) // 安全调用
}

我曾经在线上环境吃过这个亏。一个 Java 接口返回了 null，我这边用 String 接住，结果半夜报警电话打爆了。从那以后，我给自己定了个规矩：所有 Java 互操作的边界，必须加空安全检查。

五、知识体系总览

下面这张图把今天讲的内容串起来了。你可以看到，Kotlin 和 Java 互操作的核心就是「翻译」——把 Kotlin 的特性翻译成 Java 能理解的形式。

六、实战建议

说了这么多，最后给几个我实际项目中的经验：

场景	推荐做法	原因
工具类伴生对象方法	加 @JvmStatic	Java 调用更自然，不用写 Companion
有默认参数的函数	加 @JvmOverloads	Java 那边可以少传参数
顶层函数文件	加 @file:JvmName	类名语义化，不暴露文件名
从 Java 获取返回值	声明为可空类型	防止运行时 NPE
Kotlin 调用 Java 方法	用安全调用 ?.	Java 没有空安全注解时保命

说白了，Kotlin 和 Java 互操作没那么玄乎。你只要记住：Kotlin 有的特性 Java 没有，就用注解补上；Java 有的坑 Kotlin 没有，就手动防住。做到这两点，两边就能愉快地玩耍了。