kotlin-tooling-java-to-kotlin

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Java to Kotlin Conversion

Java 转 Kotlin 代码转换

Convert Java source files to idiomatic Kotlin using a disciplined 4-step conversion methodology with 5 invariants checked at each step. Supports framework-aware conversion that handles annotation site targets, library idioms, and API preservation.

采用包含5项不变量检查的四步转换方法论，将Java源文件转换为符合Kotlin语言习惯的代码。支持框架感知转换，可处理注解位置、库语言习惯及API保留。

Workflow

工作流程

dot

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"];
}

dot

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"];
}

Step 0: Scan & Detect Frameworks

步骤0：扫描与检测框架

Before converting, scan the Java file's import statements to detect which frameworks are in use. Load ONLY the matching framework reference files to keep context focused.

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

Framework Detection Table

框架检测表

Import prefix	Framework guide
`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.*

is detected, check for Dagger/Hilt vs Guice by looking for other imports from those frameworks. If ambiguous, load both guides.

导入前缀	框架指南
`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。若存在歧义，则加载两个框架的指南。

Step 1: Convert

步骤1：转换

Apply the conversion methodology from CONVERSION-METHODOLOGY.md.

This is a 4-step chain-of-thought process:

Faithful 1:1 translation — exact semantics preserved
Nullability & mutability audit — val/var, nullable types
Collection type conversion — Java mutable → Kotlin types
Idiomatic transformations — properties, string templates, lambdas

Five invariants are checked after each step. If any invariant is violated, revert to the previous step and redo.

Apply any loaded framework-specific guidance during step 4 (idiomatic transformations).

应用CONVERSION-METHODOLOGY.md中的转换方法论。

这是一个四步链式思考流程：

忠实1:1翻译 —— 完全保留语义
空安全性与可变性检查 —— val/var、可空类型
集合类型转换 —— Java可变集合 → Kotlin类型
符合语言习惯的转换 —— 属性、字符串模板、Lambda表达式

每一步转换后都会检查5项不变量。若任何一项不变量被违反，则回滚到上一步并重试。

在第4步（符合语言习惯的转换）中应用已加载的框架特定指南。

Step 2: Write Output

步骤2：输出写入

Write the converted Kotlin code to a

.kt

file with the same name as the original Java file, in the same directory.

将转换后的Kotlin代码写入与原Java文件同名的

.kt

文件中，保存到同一目录。

Step 3: Preserve Git History

步骤3：保留Git历史

To preserve

git blame

history, use a two-phase approach:

bash

undefined

为保留

git blame

历史，采用两步法：

bash

undefined

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"


If the project keeps Java and Kotlin in the same source root (e.g., `src/main/java/`),
rename in place:

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

If the project does not use Git, simply write the

.kt

file and delete the

.java

file.

git commit -m "Convert Foo from Java to Kotlin"


如果项目将Java和Kotlin文件放在同一源码根目录下（例如`src/main/java/`），则直接原地重命名：

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

如果项目未使用Git，则直接写入

.kt

文件并删除原

.java

文件即可。

Step 4: Verify

步骤4：验证

After conversion, verify using checklist.md:

Attempt to compile the converted file
Run existing tests
Check annotation site targets
Confirm no behavioral changes

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

尝试编译转换后的文件
运行现有测试
检查注解位置
确认无行为变更

Batch Conversion

批量转换

When converting multiple files (a directory or package):

List all
.java
files in the target scope
Sort by dependency order — convert leaf dependencies first (files that don't import other files in the conversion set), then work up to files that depend on them
Convert one file at a time — apply the full workflow (steps 0-4) for each
Track progress — report which files are done, which remain
Handle cross-references — after converting a file, update imports in other Java files if needed (e.g., if a class moved packages)

For large batches, consider converting in packages (bottom-up from leaf packages).

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

列出目标范围内所有
.java
文件
按依赖顺序排序 —— 先转换叶子依赖文件（不导入转换集中其他文件的文件），再处理依赖这些文件的上层文件
逐个转换文件 —— 对每个文件应用完整工作流程（步骤0-4）
跟踪进度 —— 报告已完成和待处理的文件
处理交叉引用 —— 转换完成一个文件后，若需要则更新其他Java文件中的导入（例如类移动了包路径的情况）

对于大规模批量转换，建议按包进行转换（从叶子包自底向上处理）。

Common Pitfalls

常见陷阱

See KNOWN-ISSUES.md for:

Kotlin keyword conflicts (
```
when
```
,
```
in
```
,
```
is
```
,
```
object
```
)
SAM conversion ambiguity
Platform types from Java interop
```
@JvmStatic
```
/
```
@JvmField
```
/
```
@JvmOverloads
```
usage
Checked exceptions and
```
@Throws
```
Wildcard generics → Kotlin variance

参考KNOWN-ISSUES.md了解以下内容：

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