kotlin-tooling-java-to-kotlin

Java 转 Kotlin

使用严格的 4 步转换方法，将 Java 源文件转换为符合 Kotlin 惯用写法的代码，并在每一步检查 5 项不变量。支持感知框架的转换，可处理注解目标、库惯用写法和 API 保留。

工作流

digraph j2k_workflow {
  rankdir=TB;
  "User specifies files" -> "Step 0: Scan & Detect";
  "Step 0: Scan & Detect" -> "Load framework guides";
  "Load framework guides" -> "Step 1: Convert";
  "Step 1: Convert" -> "Step 2: Write .kt";
  "Step 2: Write .kt" -> "Step 3: Git rename";
  "Step 3: Git rename" -> "Step 4: Verify";
  "Step 4: Verify" -> "Next file?" [label="pass"];
  "Step 4: Verify" -> "Fix issues" [label="fail"];
  "Fix issues" -> "Step 1: Convert";
  "Next file?" -> "Step 0: Scan & Detect" [label="batch: yes"];
  "Next file?" -> "Done" [label="no more files"];
}

步骤 0：扫描并检测框架

转换前，扫描 Java 文件的导入语句，检测使用了哪些框架。仅加载匹配的框架参考文件，以便聚焦上下文。

框架检测表

导入前缀	框架指南
org.springframework.*	SPRING.md
lombok.*	LOMBOK.md
javax.persistence.*、jakarta.persistence.*、org.hibernate.*	HIBERNATE.md
com.fasterxml.jackson.*	JACKSON.md
io.micronaut.*	MICRONAUT.md
io.quarkus.*、javax.enterprise.*、jakarta.enterprise.*	QUARKUS.md
dagger.*、dagger.hilt.*	DAGGER-HILT.md
io.reactivex.*、rx.*	RXJAVA.md
org.junit.*、org.testng.*	JUNIT.md
com.google.inject.*	GUICE.md
retrofit2.*、okhttp3.*	RETROFIT.md
org.mockito.*	MOCKITO.md

如果检测到 javax.inject.*，请检查是否有其他框架的导入语句，以判断使用的是 Dagger/Hilt 还是 Guice。如果无法确定，则加载两份指南。

步骤 1：转换

按照 CONVERSION-METHODOLOGY.md 中的转换方法进行操作。

这是一个 4 步的思维链流程：

1. 忠实的 1:1 翻译 — 保留精确语义
2. 可空性与可变性审查 — 检查 val/var 和可空类型
3. 集合类型转换 — 将 Java 可变类型转换为 Kotlin 类型
4. 惯用写法转换 — 转换为属性、字符串模板和 lambda

每一步后检查 5 项不变量。如果有任何不变量遭到破坏，则回退到上一步并重新执行。

在第 4 步（惯用写法转换）中，应用已加载的框架专属指南。

步骤 2：写入输出

将转换后的 Kotlin 代码写入 .kt 文件，文件名与原 Java 文件相同，且位于同一目录。

步骤 3：保留 Git 历史记录

为保留 git blame 历史记录，请使用两阶段方法：

# Phase 1: Rename (creates rename tracking)
git mv src/main/java/com/example/Foo.java src/main/kotlin/com/example/Foo.kt
git commit -m "Rename Foo.java to Foo.kt"

# Phase 2: Replace content (tracked as modification, not new file)
# Write the converted Kotlin content to Foo.kt
git commit -m "Convert Foo from Java to Kotlin"

如果项目将 Java 和 Kotlin 文件放在同一源代码根目录中（例如 src/main/java/），则在原位置重命名：

git mv src/main/java/com/example/Foo.java src/main/java/com/example/Foo.kt

如果项目不使用 Git，只需写入 .kt 文件并删除 .java 文件。

步骤 4：验证

转换后，使用 checklist.md 进行验证：

• 尝试编译转换后的文件
• 运行现有测试
• 检查注解目标
• 确认没有行为变化

批量转换

转换多个文件（一个目录或包）时：

1. 列出目标范围内的所有 .java 文件
2. 按依赖顺序排序 — 先转换叶子依赖（不导入转换范围内其他文件的文件），然后逐步处理依赖它们的文件
3. 一次转换一个文件 — 对每个文件应用完整工作流（步骤 0-4）
4. 跟踪进度 — 报告已完成和待处理的文件
5. 处理交叉引用 — 转换文件后，根据需要更新其他 Java 文件中的导入（例如，类更改了包）

对于大批量转换，可考虑按包转换（从叶子包开始，自下而上进行）。

常见陷阱

请参阅 KNOWN-ISSUES.md，了解：

• Kotlin 关键字冲突（when、in、is、object）
• SAM 转换歧义
• Java 互操作产生的平台类型
• @JvmStatic / @JvmField / @JvmOverloads 的用法
• 受检异常和 @Throws
• 通配符泛型 → Kotlin 型变