简介这是一款面向Kotlin迁移场景的辅助工具专为需要将Java代码转换为Kotlin、同时希望保留Git提交历史的开发者设计。它通过重命名与两次提交的巧妙机制让转换后的文件在版本库中延续原有历史记录并支持多仓库的VCS映射适合中高级开发者处理遗留项目迁移。资源包共24个文件包含8个jar依赖如JGit、slf4j、jansi等、10个xml配置、3个kt源码及iml、mf、md等辅助文件压缩包约3.82MB结构紧凑开箱即可通过命令行运行。目前已有225人学习下载。借助该脚本读者可掌握Java转Kotlin过程中历史保留的完整思路理解空运行模式与脏工作目录下的提交策略并参考其源码与依赖组织方式快速应用到实际项目迁移中。1. 从一次代码迁移事故说起为什么 Java 转 Kotlin 需要保留提交历史去年帮一个团队做 Android 模块的 Kotlin 迁移代码转完了编译也过了结果 code review 的时候所有人都傻了——Git 历史里原本清晰的「修复登录超时」「重构网络层」这些提交记录全被压成了一条「Convert Java to Kotlin」。出了问题想回溯是哪个改动引入的只能靠人肉 diff那感觉就像把黑匣子扔了再去找事故原因。这就是 j2kt-commiter 要解决的事。它不是一个简单的语法转换工具而是在 Java 转 Kotlin 的过程中把每一次文件级的转换动作映射成独立的 Git 提交让迁移前后的历史记录能对得上。适合谁用正在做存量 Java 项目 Kotlin 化、又不想丢掉 blame 和 bisect 能力的团队。如果你只是想把几个工具类转成 Kotlin手动改改就行但如果是几十万行的老项目这个工具的价值就出来了。2. 项目定位与技术选型它到底怎么把转换过程拆成提交2.1 核心思路文件级映射而非整库重写j2kt-commiter 的工作方式不是「一把梭」把整个 Java 源码树转成 Kotlin而是按文件粒度逐个处理。每转换一个.java文件就生成对应的.kt文件然后立即执行一次git addgit commit提交信息里带上原文件路径和转换状态。这样做的好处是迁移过程中的每一步都是可回退的。如果某个文件转换后编译不过你可以单独 revert 那一条提交不影响其他已经转好的文件。常见做法是配合一个转换清单文件manifest记录哪些文件已处理、哪些待处理、哪些需要人工介入。从技术选型上看这个项目大概率是围绕 JetBrains 的 j2kt 转换器做了一层封装。j2kt 本身负责语法层面的 Java→Kotlin 转换而 j2kt-commiter 负责的是工程层面的编排调用转换器、处理输出、管理 Git 操作、维护转换状态。这种分层设计让转换逻辑和版本控制逻辑解耦后续想换转换引擎也不会伤筋动骨。2.2 目录结构推演虽然没有拿到完整的源码包但按这类工具的常见组织方式目录结构大致会是这样j2kt-commiter/ ├── src/ │ ├── main/ │ │ ├── java/ # 工具自身的 Java 源码有点自举的意思 │ │ └── kotlin/ # 工具自身的 Kotlin 源码 │ └── test/ │ ├── fixtures/ # 测试用的 Java 样本文件 │ └── kotlin/ # 测试用例 ├── build.gradle.kts # Gradle 构建脚本 ├── settings.gradle.kts └── README.md关键目录是src/test/fixtures/里面会放各种「刁钻」的 Java 文件——泛型嵌套、匿名内部类、静态初始化块——用来验证转换器在不同语法结构下的行为。如果你要二次开发这个目录是你最先要看的地方它决定了工具能覆盖多少真实场景。2.3 转换流程的四个阶段整个转换过程可以拆成四个阶段每个阶段都有对应的代码模块阶段一扫描与过滤。遍历源码目录找出所有.java文件根据配置排除掉不需要转换的包比如自动生成的代码、第三方库的拷贝。阶段二转换执行。对每个文件调用 j2kt 转换器拿到 Kotlin 输出。这一步是最容易翻车的地方因为 j2kt 对某些 Java 语法特性的支持并不完整。阶段三Git 提交。把转换结果写入新文件删除原 Java 文件或保留取决于配置然后执行提交。提交信息通常格式为j2kt: convert com/example/Foo.java。阶段四状态记录。更新 manifest 文件标记该文件已转换。如果转换失败记录失败原因跳过该文件继续处理下一个。# 典型的调用方式推演 ./gradlew run --args--source-dir ./app/src/main/java \ --output-dir ./app/src/main/kotlin \ --manifest ./migration-manifest.json \ --commit-per-file参数说明--source-dir指定 Java 源码根目录--output-dir指定 Kotlin 输出目录--manifest指定状态文件路径用于断点续转--commit-per-file开启逐文件提交模式关掉的话就只生成文件不提交。注意逐文件提交会产生大量 commit建议在独立分支上操作转完后再 squash 或保留原样看团队规范。3. 跑起来环境准备与首次转换实操3.1 环境依赖与构建这个项目基于 Gradle 构建需要 JDK 17 或以上j2kt 对 JDK 版本有要求。Kotlin 插件版本建议用 1.9 系列太老的版本可能不兼容 j2kt 的输出。# 克隆项目后先确认 JDK 版本 java -version # 输出应为 openjdk 17.x 或更高 # 构建项目 ./gradlew build -x test # 如果构建失败先清理再试 ./gradlew clean build -x test构建过程中如果卡在依赖下载检查build.gradle.kts里的仓库配置。常见做法是加上mavenCentral()和google()两个仓库源。国内网络环境下可能需要配置镜像但那是另一个话题了。3.2 准备待转换的 Java 项目不要一上来就拿生产项目试。先找一个小的 Java 模块最好满足这几个条件代码量在 50 个文件以内、没有复杂的注解处理器、没有用到 Java 特有的反射逻辑。# 在你的 Java 项目里创建一个迁移分支 git checkout -b kotlin-migration # 确认工作区干净 git status # 如果有未提交的改动先 stash 或 commit工作区干净这一点很重要。j2kt-commiter 会在转换过程中自动提交如果工作区本身有未提交的改动Git 操作会变得混乱到时候分不清哪些是工具提交的、哪些是你自己的改动。3.3 执行首次转换# 回到 j2kt-commiter 项目目录执行转换 ./gradlew run --args--source-dir /path/to/your-java-project/src/main/java \ --output-dir /path/to/your-java-project/src/main/kotlin \ --manifest ./migration-manifest.json \ --commit-per-file \ --exclude **/generated/**--exclude参数用来跳过自动生成的代码目录。很多项目里build/generated下面有大量自动生成的 Java 文件这些不需要转换转反而会出问题。转换完成后去你的 Java 项目里执行git log --oneline应该能看到一串j2kt: convert ...的提交记录。每一条对应一个文件的转换。3.4 验证转换结果转换完不代表就完事了。你需要验证两件事一是 Kotlin 代码能不能编译通过二是转换后的行为是否和原来一致。# 在 Java 项目里尝试编译 ./gradlew compileKotlin # 如果编译失败查看具体是哪个文件报错 ./gradlew compileKotlin 21 | grep error:编译报错是常态尤其是第一次跑。常见的错误类型包括空安全推断失败、泛型型变不匹配、Java 静态成员访问方式差异。这些错误需要人工修复j2kt-commiter 不负责语义层面的修正。提示建议在转换后立即跑一遍单元测试。如果测试覆盖率不够至少把核心业务逻辑的手动测试用例过一遍。4. 核心模块拆解转换器封装与 Git 操作链路4.1 转换器封装层j2kt-commiter 对 j2kt 的调用不是直接裸调而是包了一层。这层封装做了几件事参数标准化、异常捕获、输出后处理。// 推演的转换器封装代码 class J2ktConverter( private val j2ktClasspath: String, private val outputCharset: Charset Charsets.UTF_8 ) { fun convert(javaFile: File): ConversionResult { return try { // 调用 j2kt 转换器传入源文件和 classpath val kotlinSource J2ktInvoker.invoke( sourceFile javaFile, classpath j2ktClasspath ) // 后处理修正 j2kt 输出中的已知问题 val cleaned postProcess(kotlinSource) ConversionResult.Success(cleaned) } catch (e: J2ktConversionException) { // 转换失败不中断整个流程记录原因后继续 ConversionResult.Failure(javaFile, e.message) } } private fun postProcess(source: String): String { // 常见后处理移除多余的 import、修正缩进 return source.lines() .filterNot { it.startsWith(import java.lang.) } .joinToString(\n) } }这段代码的关键在于ConversionResult这个密封类。成功时携带转换后的 Kotlin 源码失败时携带原文件引用和错误信息。调用方根据结果类型决定是写文件加提交还是记录到失败清单里跳过。这种设计让单个文件的转换失败不会阻塞整个迁移流程对于大项目来说很实用。postProcess方法里做的事情看起来不起眼但实际用起来能省不少事。j2kt 的输出有时候会带上一些冗余的 import或者缩进风格和项目规范不一致统一在这里处理比事后手动改要高效得多。4.2 Git 操作模块Git 操作是 j2kt-commiter 区别于普通转换工具的核心。它需要精确控制提交的粒度和时机。// 推演的 Git 操作封装 class GitCommitter(private val repoRoot: File) { fun commitConversion( javaFile: File, kotlinFile: File, commitMessage: String ): Boolean { return try { // 1. 暂存新生成的 Kotlin 文件 runGit(add, kotlinFile.relativeTo(repoRoot).path) // 2. 暂存被删除的 Java 文件如果配置为删除原文件 runGit(rm, --cached, javaFile.relativeTo(repoRoot).path) // 3. 执行提交 runGit(commit, -m, commitMessage) true } catch (e: GitOperationException) { // 提交失败时回滚暂存区避免污染下一次提交 runGit(reset, HEAD) false } } private fun runGit(vararg args: String): String { val process ProcessBuilder(git, *args) .directory(repoRoot) .redirectErrorStream(true) .start() val output process.inputStream.bufferedReader().readText() if (process.waitFor() ! 0) { throw GitOperationException(git ${args.joinToString( )} failed: $output) } return output } }这里有几个细节值得注意。第一提交前先git add新文件再git rm --cached旧文件顺序不能反否则 Git 会认为你只是删了个文件。第二提交失败时执行git reset HEAD回滚暂存区这是血泪经验——如果不回滚下一次提交会把上一次的残留内容一起带进去历史记录就乱了。第三用ProcessBuilder而不是 JGit 库虽然 JGit 更「Java 风格」但直接调命令行更透明出问题的时候容易排查。4.3 状态管理与断点续转大项目转换不可能一次跑完中途可能因为编译错误、人工介入、甚至机器重启而中断。manifest 文件就是用来解决这个问题的。{ version: 1.0, sourceRoot: /path/to/java/src, outputRoot: /path/to/kotlin/src, files: { com/example/LoginActivity.java: { status: converted, commitHash: a1b2c3d, convertedAt: 2025-01-15T10:30:00Z }, com/example/NetworkClient.java: { status: failed, error: Unsupported syntax: anonymous class with generic method, attemptedAt: 2025-01-15T10:31:00Z }, com/example/Utils.java: { status: pending } } }每次启动转换时工具先读 manifest跳过converted的文件重试failed的文件或者根据配置跳过只处理pending的。这样即使中断了重新跑一遍也不会重复提交已经转好的文件。commitHash字段记录转换对应的提交哈希方便后续追溯。如果某个文件转换后发现问题需要回退直接根据这个哈希找到对应的提交做 revert 就行。4.4 失败处理策略转换失败的文件怎么处理这个策略需要根据项目情况来定。j2kt-commiter 通常提供三种模式模式行为适用场景skip记录失败原因跳过继续大批量转换先跑通大部分halt立即停止整个转换流程小批量转换要求每个都成功retry失败后自动重试指定次数偶发性转换错误我一般会先用skip模式跑一遍全量看看失败率有多高。如果失败文件占比超过 20%说明项目里有大量 j2kt 不支持的语法结构这时候需要先做一轮人工预处理把那些「硬骨头」挑出来单独处理。如果失败率在 5% 以下那就直接用skip模式跑完最后集中处理失败清单。5. 避坑与常见问题排查5.1 提交历史出现「空提交」现象git log里出现一些没有任何文件变更的提交提交信息是j2kt: convert ...但 diff 是空的。原因转换后的 Kotlin 文件和原 Java 文件内容完全一致比如一个空接口或纯常量类Git 认为没有实际变更但工具仍然执行了 commit。解决在提交前检查暂存区是否有实际变更。可以在GitCommitter里加一个判断执行git diff --cached --quiet如果返回 0 说明没有变更跳过提交。5.2 转换后编译报「未解析的引用」现象Kotlin 文件里大量标红提示找不到某个类或方法。原因j2kt 转换时没有正确处理 Java 的静态导入或通配符导入导致 Kotlin 文件缺少必要的 import。解决在postProcess阶段扫描 Kotlin 源码中使用的符号和原 Java 文件的 import 列表做比对补上缺失的 import。更稳妥的做法是转换后跑一遍ktlint或 IDE 的自动 import 优化。5.3 Git 提交作者信息不对现象转换产生的提交author 显示的是运行工具的机器账户而不是实际开发者。原因ProcessBuilder调用 git 时继承了当前 shell 的 Git 配置如果是在 CI 环境或别人的机器上跑author 信息就不对。解决在runGit方法里显式设置环境变量GIT_AUTHOR_NAME、GIT_AUTHOR_EMAIL、GIT_COMMITTER_NAME、GIT_COMMITTER_EMAIL从配置文件读取而不是依赖全局设置。5.4 大文件转换导致内存溢出现象转换某个超大 Java 文件时JVM 抛出OutOfMemoryError。原因j2kt 转换器在解析大型文件时会构建完整的 AST文件越大内存占用越高。解决调大 Gradle 运行时的堆内存在gradle.properties里设置org.gradle.jvmargs-Xmx4g。如果还是不行考虑把超大文件拆分成多个小文件再转换。5.5 转换顺序影响结果现象同样的代码不同的转换顺序产生的 Kotlin 代码有差异。原因某些 Java 文件之间存在继承或依赖关系j2kt 在转换时会参考已转换的 Kotlin 文件来推断类型顺序不同推断结果可能不同。解决在 manifest 里记录文件的依赖关系按拓扑排序的顺序执行转换。被依赖的文件先转依赖方后转。这个逻辑需要在扫描阶段就建立好依赖图。6. 二次开发自定义转换规则与增量迁移策略拿到这个项目之后最值得改的地方是转换规则的可配置化。默认的 j2kt 转换策略是「一刀切」的但实际项目里总有一些文件需要特殊处理——比如某个类必须保留 Java 实现因为用了 Kotlin 不支持的字节码操作或者某个包需要跳过转换。我一般会加一个.j2ktcommiter.yml配置文件放在项目根目录# 自定义转换规则配置 rules: - pattern: **/legacy/** action: skip reason: 遗留模块暂不迁移 - pattern: **/api/** action: convert options: preserveAnnotations: true # 保留 Java 注解 generateDeprecated: true # 生成 Deprecated 标记 - pattern: **/internal/** action: convert options: visibility: internal # 转换后可见性改为 internal然后在转换器封装层里读取这个配置根据文件路径匹配对应的规则。skip的直接跳过convert的按 options 调整转换参数。这样不同模块可以用不同的迁移策略不用改代码。增量迁移是另一个值得投入的方向。全量转换的风险太大更好的做法是按包或按模块逐步迁移。具体实现上可以在 manifest 里增加一个module字段记录每个文件属于哪个模块然后提供一个--module参数只转换指定模块的文件。# 只转换 network 模块 ./gradlew run --args--source-dir ./src/main/java \ --module network \ --manifest ./migration-manifest.json这样你可以先迁一个模块跑一段时间没问题了再迁下一个。每个模块迁移完成后在 CI 里加一条检查确保该模块下没有新增的.java文件。有的话就说明有人还在往旧模块里加 Java 代码需要及时纠正。验证迁移效果的方法也很直接对比迁移前后的单元测试覆盖率。如果迁移后覆盖率明显下降说明有些测试用例没有跟着转过来或者转换后的代码行为发生了变化导致测试失败。我习惯在迁移分支上跑一遍完整的测试套件把失败的用例单独拉一个清单逐个确认是转换问题还是测试本身需要适配。从那以后我每次做代码迁移都强制要求先在一个小模块上跑通完整流程——转换、编译、测试、review——再推广到全量。这个习惯帮我省了至少两次大规模回滚的麻烦。希望帮到你。本文还有配套的精品资源点击获取