Java 与 Kotlin 混合开发避坑指南：老项目平滑迁移 Kotlin 实操手册

"Kotlin 虽好，但老项目不敢动。"

这是很多 Android 团队的真实写照。其实，Kotlin 在设计之初就把"与 Java 100% 互操作"作为核心目标 。只要踩点正确，老项目完全可以做到：小步快跑、逐步迁移、风险可控。

本文结合真实项目经验，从工程配置 → 编码互操作 → 常见大坑 → 平滑迁移步骤四个维度，给你一套可落地的实操方案。

一、为什么 Java + Kotlin 混合开发是"最佳过渡态"

在理想世界里，你会一次性把项目重写成 Kotlin。但在现实里：

项目庞大，重写成本不可接受
历史逻辑复杂，重写 = 引入新 Bug
团队技能参差不齐
线上稳定性压倒一切

✅ 混合开发的最大优势：

新代码用 Kotlin，老代码保留 Java，互不干扰，渐进替换。

JetBrains 官方也明确表示：

Kotlin 不是为了取代 Java，而是为了与它共存。

二、环境准备：老项目接入 Kotlin（一步都不能错）

1️⃣ 最低配置检查

项目	建议版本
Gradle	≥ 7.0
AGP（Android Gradle Plugin）	≥ 7.0
Kotlin	≥ 1.8
JDK	11+

⚠️ 低版本 Gradle + 高版本 Kotlin 极易出现诡异编译错误。

2️⃣ 工程级 build.gradle

复制代码

buildscript {
    ext.kotlin_version = '1.9.22'
    dependencies {
        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
    }
}

3️⃣ Module 级 build.gradle（关键）

复制代码

plugins {
    id 'com.android.application'
    id 'kotlin-android'
    id 'kotlin-kapt' // 如果用注解处理器（Room、Dagger）
}

android {
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_11
        targetCompatibility JavaVersion.VERSION_11
    }

    kotlinOptions {
        jvmTarget = "11"
    }
}

dependencies {
    implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version"
}

✅ 必做项：

kotlin-android：支持 Kotlin 编译
kotlin-kapt：替代 annotationProcessor
jvmTarget 必须与 Java 保持一致

三、Java ↔ Kotlin 互操作核心规则（避坑重点）

1️⃣ Null Safety 是最大差异点

Java 调用 Kotlin

复制代码

// Kotlin
fun getName(): String         // 非空
fun getNameNullable(): String? // 可空

Java 视角：

复制代码

String name = repo.getName();           // OK
String name2 = repo.getNameNullable();  // 依然是 String

⚠️ Java 不知道 Kotlin 的可空性，因此：

@NotNull / @Nullable 注解至关重要
否则 NPE 会在运行时才炸

✅ 正确写法：

复制代码

fun getName(): @NotNull String
fun getNameNullable(): @Nullable String?

2️⃣ Kotlin 调用 Java（平台类型）

复制代码

val text = intent.getStringExtra("key") // 平台类型 String!

String! 的含义：

Kotlin 编译器也不知道它是不是 null。

✅ 防御式写法：

复制代码

val text = intent.getStringExtra("key") ?: ""

或：

复制代码

intent.getStringExtra("key")?.let {
    // 安全使用
}

3️⃣ Getter / Setter 的自动映射

Java：

复制代码

public class User {
    private String name;
    public String getName() { return name; }
}

Kotlin：

复制代码

val user = User()
val name = user.name // 实际调用 getName()

✅ 看起来像字段访问，本质是方法调用

❌ 不要自己写 getXxx() / setXxx() 的 Kotlin 扩展

4️⃣ static → companion object（但不完全等价）

Java：

复制代码

public class Utils {
    public static void log(String msg) {}
}

Kotlin：

复制代码

class Utils {
    companion object {
        @JvmStatic
        fun log(msg: String) {}
    }
}

✅ 强烈建议加上 @JvmStatic：

Java 调用更自然
避免生成合成方法（影响性能 & 反射）

四、老项目迁移中最容易踩的 10 个坑

❌ 坑 1：Kotlin 文件直接替换 Java 文件

后果：编译通过，运行崩溃

原因：混淆规则、反射、类名变化

✅ 正确姿势：

新建 Kotlin 文件
老 Java 文件保留一段时间
确认无误后再删除

❌ 坑 2：DataBinding / ViewBinding 混用

Kotlin 推荐使用 ViewBinding
DataBinding + Kotlin 易出 BR 类冲突

✅ 建议：

复制代码

buildFeatures {
    viewBinding true
    dataBinding false
}

❌ 坑 3：lateinit 滥用

复制代码

lateinit var context: Context

❌ Java 中访问会抛 UninitializedPropertyAccessException

✅ 替代方案：

复制代码

@JvmField
var context: Context? = null

❌ 坑 4：Kotlin 泛型 + Java 原始类型

Java：

复制代码

List list = new ArrayList();

Kotlin：

复制代码

val list: List<*> = javaList // 星投影

✅ 明确泛型边界，避免 * 满天飞

❌ 坑 5：Lambda 与 SAM 转换陷阱

Java 接口：

复制代码

interface Callback {
    void onResult(String s);
}

Kotlin：

复制代码

callback = Callback { } // 仅单抽象方法接口可用

❌ 多个方法的接口不能用 Lambda

❌ 坑 6：kapt 与 annotationProcessor 混用

✅ Room / Dagger / ARouter 必须统一：

复制代码

kapt "androidx.room:room-compiler:x.x.x"

❌ 不要混用：

复制代码

annotationProcessor "..." // 删除

❌ 坑 7：Kotlin 反射 ≠ Java 反射

::class.java ≠ .class
Kotlin Metadata 存在额外信息

✅ 第三方库反射代码要验证 Kotlin 兼容性

❌ 坑 8：默认参数在 Java 中不可用

复制代码

fun showToast(msg: String = "default") {}

Java：

复制代码

showToast(); // ❌ 编译失败
showToast("hello"); // ✅

✅ 解决方案：

复制代码

@JvmOverloads
fun showToast(msg: String = "default") {}

❌ 坑 9：object 单例被反射破坏

Kotlin：

复制代码

object Singleton

Java 反射可调用构造函数（反序列化漏洞）

✅ 加固方式：

复制代码

object Singleton {
    @Throws(IllegalStateException::class)
    private fun readResolve(): Any = Singleton
}

❌ 坑 10：混淆规则缺失

Kotlin 生成的类：

-$$Lambda$
Companion
DefaultImpls

✅ Proguard 至少保留：

复制代码

-keep class kotlin.** { *; }
-keepclassmembers class **$Companion { *; }

五、老项目平滑迁移 Kotlin：实操 6 步走

✅ Step 1：新功能全部 Kotlin 化

新页面 / 新工具类 / Repository
强制 Code Review 检查 Java 回潮

✅ Step 2：工具类优先迁移

适合迁移的类：

Utils
Constants
Extensions

不适合：

Activity / Fragment（依赖复杂）

✅ Step 3：使用 Android Studio 一键转换（但要人工校验）

Code → Convert Java File to Kotlin File

⚠️ 转换后必查：

null 安全性
lateinit 是否合理
泛型是否丢失

✅ Step 4：ViewModel / Repository 层迁移

这一层：

业务逻辑集中
UI 无关
测试覆盖率高

✅ 最适合 Kotlin Coroutine + Flow

✅ Step 5：UI 层逐步迁移（Activity / Fragment）

建议顺序：

新建 Kotlin Activity
旧 Activity 复制逻辑到新文件
双跑验证
删除旧文件

✅ Step 6：统一编码规范 & Lint

复制代码

dependencies {
    implementation "androidx.lifecycle:lifecycle-runtime-ktx:..."
    implementation "androidx.activity:activity-ktx:..."
}

Lint 规则：

禁止 Java 文件中新增业务代码
新 PR 必须有 Kotlin 覆盖率

六、迁移收益回顾（给老板看的）

维度	改进
代码量	减少 20%~30%
NPE 崩溃率	显著下降
可读性	大幅提升
协程支持	异步代码线性化
招聘吸引力	提升团队技术形象

七、总结一句话

Kotlin 迁移不是一场革命，而是一场渐进式重构。

Java 负责稳定，Kotlin 负责进化。

只要遵循：

✅ 工程配置对齐
✅ 互操作规则清晰
✅ 小步迁移、持续验证

你的老项目完全可以在零事故的前提下，平稳迈入 Kotlin 时代。