把 Java 源码迁移为地道 Kotlin 时…

当需要将 .java 文件转换为 .kt 文件（j2k）时，用一套 4 步转换法 + 5 项不变量校验，并按所用框架加载对应指南。

适用场景

解决思路

1. Step 0 扫描并检测框架：转换前先扫描 Java 文件的 import 语句，判断使用了哪些框架，只加载匹配的框架参考文件以保持上下文聚焦。检测表：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.*，再根据其他 import 判断是 Dagger/Hilt 还是 Guice；无法确定时两个指南都加载。
2. Step 1 转换：按 CONVERSION-METHODOLOGY.md 执行 4 步思维链：①忠实 1:1 翻译，保持语义完全一致；②空安全与可变性审计，确定 val/var 与可空类型；③集合类型转换，把 Java 可变集合改为 Kotlin 类型；④地道化改写，使用属性、字符串模板、lambda。每步之后检查 5 项不变量，任一不变量被破坏就回退到上一步重做。在第 4 步应用已加载的框架专属指导。
3. Step 2 写出结果：把转换后的 Kotlin 代码写入与原 Java 文件同名、同目录的 .kt 文件。
4. Step 3 保留 Git 历史：用两阶段方式保留 git blame 历史。阶段一重命名以建立重命名追踪：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"；阶段二替换内容（会被记录为修改而非新文件）：把转换后的 Kotlin 内容写入 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 文件。
5. Step 4 验证：按 assets/checklist.md 验证：尝试编译转换后的文件、运行现有测试、检查注解目标位置（annotation site targets）、确认没有行为变化。
6. 批量转换：①列出目标范围内所有 .java 文件；②按依赖顺序排序，先转换叶子依赖（不 import 转换集合内其他文件的文件），再向上处理依赖它们的文件；③一次只转换一个文件，每个文件都走完整流程（步骤 0-4）；④跟踪进度，报告已完成和剩余文件；⑤处理交叉引用，转换完一个文件后按需更新其他 Java 文件中的 import（例如类换了包）。大批量时可按包自底向上从叶子包开始转换。
7. 常见坑参考 KNOWN-ISSUES.md：Kotlin 关键字冲突（when、in、is、object）、SAM 转换歧义、Java 互操作产生的平台类型、@JvmStatic / @JvmField / @JvmOverloads 的用法、受检异常与 @Throws、通配符泛型到 Kotlin 型变的映射。

适用边界 · 注意事项

• 目标不是 Java 转 Kotlin（如 Kotlin 转 Java、其他语言迁移）时不适用。
• 项目不使用 Git 时，Step 3 的两阶段重命名提交做法不适用，直接写 .kt 并删除 .java 即可。
• 无法编译或运行测试来验证转换结果时，Step 4 的验证环节无法完整执行。