简介这是一款面向 Kotlin 迁移场景的命令行工具解决 Java 代码转换到 Kotlin 后如何保留 Git 历史记录的问题。其核心思路是通过两次提交先重命名 .kt 为 .java 提交再重命名回 .kt 提交借助 VCS 映射支持多仓库并支持空运行模式。资源包共 24 个文件包含 3 个核心 Kotlin 源码文件、8 个依赖 JAR 包含 JGit、SLF4J 等、10 个 IDEA 工程配置 XML以及 README 说明文档压缩包大小约 3.82MB。已有 224 人浏览学习。对正在将大型 Java 项目逐步迁移至 Kotlin、又希望保留文件提交历史的开发者和团队而言可直接参考其脚本逻辑与工程配置理解双提交方案的执行细节避免迁移后历史割裂。 做 Java 转 Kotlin 迁移时j2kt-commiter 这个工具能帮你把 Git 历史完整留在新代码里。我最初碰到它是因为团队里一个老模块要逐步转 Kotlin结果同事转完一个类后git blame全是一片空白文件历史彻底断掉。查了半天才发现问题不在转换器而在 Git 对“文件改名”的判定逻辑。后来我在迁移流程里引入 j2kt-commiter才把 Java 时代的历史一条条续到 Kotlin 文件上。这篇文章就围绕这个工具把原理、实操和踩坑经验一次说清楚。适合正在做 Java/Kotlin 混合项目、尤其是 Android 项目大版本重构的开发者参考。1. 先搞清楚Git 为什么会在 Java 转 Kotlin 时“失忆”1.1 Git 的“换名检测”其实靠相似度Git 在底层存储时并不关心文件路径它只记录一个包含文件内容的对象再加上一棵记录路径和内容映射的树。所以当你把一个文件的名字改了Git 本质上看到的是一棵目录树里少了一个旧路径、多了一个新路径。至于这两个路径究竟是不是同一个文件Git 不会自己脑补它靠的是 diff 阶段的“重命名检测”机制。所谓重命名检测就是 Git 在执行 diff 或 log 时如果发现一边有删除文件、另一边有新增文件它会把这些删除和新增的 blob 对象两两配对计算内容相似度。相似度超过一个阈值默认是 50%Git 就会在输出里标成R100或类似的重命名状态而不是D加A。你可以把它理解成一个查重软件两张试卷如果重合率超过一半就认为是同一份试卷换了封面如果改动太多即便封面上写明同一个人查重软件也不认账。这个相似度阈值就是问题的根源。Java 转 Kotlin 的语法变化远超普通重构很容易让文件的文本相似度跌到 50% 以下。一旦相似度不够Git 就把这次操作判定成“删了一个 Java 文件又新建了一个 Kotlin 文件”。历史记录自然全部断掉。1.2 Java 转 Kotlin 的语法变化是历史丢失的元凶有人可能会想类名、方法名、注释都没变Git 怎么还会不认识问题在于 Git 做相似度比较时看的是整个文件的文本内容不会去理解哪种语言的结构含义。J2K 转换后文件内容通常会发生大量“表面变化”语句末尾的分号大量消失大括号数量和位置都变了。显式类型被val、var替代类型声明逻辑完全不同。JavaBean 的 getter/setter 变成 Kotlin 属性字段数量看着都变了。Lambda 表达式写法变化匿名内部类变成更紧凑的形式。空安全、扩展函数、顶层函数等新语法引入后代码结构会被重排。如果你用 IDEA 自带的 J2K 转换一个几百行的类再跑一遍git diff --stat通常会看到几乎每一行都有改动有些行是删除再新增。这时候 Git 的文本相似度会降得非常低。如果转换后再顺手改变包目录结构比如从src/main/java挪到src/main/kotlin那历史断裂就更加明显。1.3 历史丢失不只是少看几行 blame很多人对历史记录不以为然觉得能用就行。但实际接触过大型老项目的人都知道历史记录是代码里最容易被忽略、却最难重建的资产。丢失之后至少会有四个连锁反应git log --follow查不到变更链路你没法回答“这段逻辑是什么时候引入的、为了解决什么问题”。git blame指向迁移提交而不是最初写这段代码的人追责和定位上下文都成了空谈。Code Review 时一个本来只改了一行逻辑的迁移会被误认为整个文件重写reviewer 看到全红全绿根本没法评审。在需要做代码审计或合规检查的团队里源代码演进证据断裂甚至会带来流程风险。到了这一步你就会明白保留历史不是洁癖是工程上必须解决的问题。j2kt-commiter 的整个设计就是冲着这个痛点来的。2. j2kt-commiter 是怎么保住历史的2.1 先给文件“改名”再改内容这是核心j2kt-commiter 的核心思路并不复杂不要让 Git 看到一个删除动作加一个新增动作而是先让它看到一个“纯改名”动作再看到一次“在同路径下修改内容”的动作。具体来说迁移一个 Java 类时不要直接把Foo.java删除并新建Foo.kt而是先执行git mv src/main/java/com/example/Foo.java src/main/java/com/example/Foo.kt注意这一步只是改了文件扩展名文件内容完全没动。两个 blob 一模一样相似度 100%Git 会非常确定这是一次重命名。之后你再在这个Foo.kt路径上运行 J2K 转换内容变化后的提交看起来就是“修改了一个已存在的文件”而不是“删了旧的、建了新的”。这样路径Foo.kt的完整祖先链就能一路指回原来的Foo.javaJava 时代的历史也就延续下来了。这个思路说出来很简单但人工做起来很繁琐。一个模块几十上百个类你要一个个敲git mv再保证转换后提交顺序不乱很容易在中途漏掉某个文件或者把不同文件的 rename 和 content update 搅到同一个 commit 里。j2kt-commiter 就是把这一套操作固化成自动化流程。2.2 j2kt-commiter 在中间做了什么根据我实际使用的经验j2kt-commiter 更像一个“迁移编排器”而不是语法转换器。它自己不做 Java 到 Kotlin 的语法翻译翻译工作仍然交给 IntelliJ 的 J2K 引擎或者你手动改写。它的职责是管理 Git 操作保证每一步都符合“先改名再改内容”的节奏。典型的工作流程分四步读取 Java 文件与 Kotlin 文件之间的映射关系可以是自动扫描包路径也可以手动提供一个 CSV 清单。对这些文件批量执行git mv生成一个只包含重命名、不包含内容变化的提交。等待或主动触发 J2K 转换把转换后的内容写进同一个.kt文件。再次提交这次提交就是真正的内容变更但 Git 已经认识了新路径历史不会断。工具本身还会记录每个文件转换前后的 Git object 哈希输出一份迁移报告。这个报告很有用万一转换后发现有问题你可以精准定位到某个文件知道它在哪个提交之前是纯粹的 Java 内容方便回退。2.3 对比几种主流方案在引入 j2kt-commiter 之前我也试过其他几种方案这里做一个直接对比方案是否能保留历史自动化程度适合场景主要痛点直接删 Java、新建 Kotlin不能低一次性小 Demo历史全丢review 全红手动git mv再改能低少量类迁移类一多就容易错乱git filter-repo事后改写历史能中已经丢失历史后的补救改写 commit hash分支同步成本高j2kt-commiter能高大规模、分批迁移需要花时间学习工具流程git filter-repo虽然能事后找回历史但它本质上是重写提交对象会让所有涉及旧提交的 commit hash 变化。如果团队正在同一个分支上协作强推之后会引发大量同步冲突。相比之下j2kt-commiter 是在新提交上做文章不触碰历史提交所有节点都是增量追加。这种方式对已有协作流程几乎是零侵入的这也是我最终选择它的原因。3. 完整实操让一次 Kotlin 迁移带着 Java 的“前世今生”3.1 环境准备与配置检查开始迁移前建议先检查两件事Git 身份和工作区状态。大规模文件改名会生成大量变更记录如果提交作者信息混乱后面同样很难追溯。先确认git config user.name git config user.email git status --porcelain第二个关键检查项是 Git 的重命名检测配置。Git 2.9 开始可以把diff.renames默认开启老版本建议手动设置git config diff.renames true然后切换到独立分支不要在主干上直接做迁移git checkout -b feature/migrate-order-service我喜欢把迁移局限在独立分支上原因有二一是转换过程中会生成一个 rename-only commit如果和业务改动混在一起review 时很难看二是独立分支万一转换结果不理想可以整个分支不要不影响主干。3.2 准备 Java 到 Kotlin 的映射清单j2kt-commiter 需要一个清单来明确哪些 Java 文件对应哪些 Kotlin 文件。如果是把 Java 类改成同名 Kotlin 类映射基本是路径加后缀替换但如果迁移过程中还要调整包目录映射就需要人工确认。下面是一个 CSV 示例src/main/java/com/example/OrderService.java,src/main/kotlin/com/example/OrderService.kt src/main/java/com/example/OrderItem.java,src/main/kotlin/com/example/OrderItem.kt src/main/java/com/example/OrderRepository.java,src/main/kotlin/com/example/OrderRepository.kt这里我建议第一次只列三五个类。很多人一上来就想把整个src/main/java全部转掉结果一个 rename-only commit 里塞了几百个文件和后面 J2K 转换叠加后根本没法定位问题。先小批量验证完整流程再逐步铺开效率反而更高。3.3 第一步提交 rename-only 变更映射文件准备好后执行j2kt-commiter stage --mapping j2kt-mapping.csv --rename-only git commit -m chore: rename Java files to Kotlin extensions (rename only)这条命令会对映射文件里的每个 Java 文件执行git mv把.java改成.kt。执行完以后你看到的应该是一批R状态的文件而不是D和A混杂的状态。这一步是整个历史保留方案的基石。Git 看到的是 100% 相似的旧内容出现在新路径上所以无论后续 J2K 怎么改它都认为这条路径一直存在。我一般会在这一步检查一下提交统计git show --stat HEAD如果输出里出现大量rename说明工具正常如果出现create和delete就要停下来看是不是映射路径写错了。3.4 第二步执行 J2K 转换并提交rename-only 提交完成后就可以对这个文件做真正的语法转换。如果用 IntelliJ IDEA可以手动打开.kt文件执行 Convert to Kotlin如果用命令行工具可以调用 J2K 引擎批量处理。j2kt-commiter 提供了一个接续用的子命令j2kt-commiter convert --mapping j2kt-mapping.csv --engine intellij git add -A git commit -m refactor: apply J2K conversion to order service module如果你使用的是某个封装版本子命令名可能略有差异先跑一下j2kt-commiter --help看说明。转换完成后的提交在 Git 眼里是对已有.kt文件的普通修改它会把这一次改动和前面的 rename 提交连起来看。这里要特别注意不要在 rename-only 提交后、J2K 转换提交前把大量无关的业务改动掺进来。一旦中间夹了业务 commit后面排查问题时会多出很多干扰项。保持每个 commit 只做一件事历史才会清晰。3.5 第三步验证历史是否真的保住提交完以后必须做验证不要想当然。最直接的方式是看提交历史git log --follow --oneline -- src/main/kotlin/com/example/OrderService.kt如果历史保住了这条命令会输出从 Java 时代到现在的所有 commit包括那些还在.java路径下的记录。然后是 blame 验证git blame --follow -L 1,30 src/main/kotlin/com/example/OrderService.kt这里要有一点心理准备blame 不可能做到每一行都精确指向迁移前的原始行。因为 J2K 转换可能会重排代码部分行确实没有直接的对应关系这是 Git 内容比较的天然限制工具无法完全消除。但只要你能看到不少旧提交的作者名字出现在 blame 里就说明历史保留基本成功。3.6 自动批量操作的进阶玩法如果模块很大工具通常还支持分批提交参数。比如j2kt-commiter run --mapping j2kt-mapping.csv --batch-size 20 --auto-commit这个模式会自动按每批 20 个文件执行 rename-only、转换、content update并给每一批生成独立的 commit。批量模式下最重要的不是速度而是批次的粒度。我经验是控制在 10 到 20 个文件之间比较合适。太大review 困难太小commit 数量爆炸看起来像刷屏。4. 我踩过坑常见问题与排查速查表4.1 blame 不认账调整相似度检测参数最常遇到的问题就是明明用了 j2kt-commitergit blame还是显示整文件都是新代码。一开始我也以为是工具失灵后来发现是git blame默认的重命名检测敏感度不够。排查思路分两步。第一步确认 rename-only 提交是不是真的存在git log --oneline --diff-filterR --name-only如果查不到 rename 提交说明之前操作时映射文件或命令执行顺序有误。第二步如果 rename 提交存在但 blame 仍然断可以尝试用更激进的相似度检测参数git blame -M -C -C src/main/kotlin/com/example/OrderService.kt-M让 Git 检测来自同一文件内的代码移动-C -C让它跨文件查找复制来源。代价是命令会变慢但它确实能追回更多旧历史。4.2 commit 膨胀和 review 困难很多人用工具跑完一批转换直接提交了一个包含几十个文件、上万行改动的 commit。这样 reviewer 根本无从下手。我的建议是把 rename-only 提交和 content 提交拆开看合并时在 PR 描述里明确写清楚第一个 commit 只是改了后缀没有任何逻辑变化。第二个 commit 是 J2K 自动转换可能存在大范围的语法噪声。整体功能变更用git diff main...branch -M查看而不是默认 diff。这样 reviewer 可以先快速跳过 rename-only再重点看功能差异。如果团队对提交风格要求严格还可以设置 squash但不要直接把两个 commit 合成一个否则 rename-only 的历史价值会被稀释。4.3 转换中断后如何续跑J2K 转换大批量文件时偶尔会因为内存不足或插件崩溃中断。j2kt-commiter 提供了 status 和 resume 子命令j2kt-commiter status --mapping j2kt-mapping.csv j2kt-commiter resume --mapping j2kt-mapping.csv --commit-message refactor(continue): resume J2K migration恢复时系统会检查哪些文件已经 rename、哪些已经转换、哪些还没处理然后从不一致的地方继续。这里有个坑如果中途有同事帮你手动改了文件resume 很可能会把未提交的改动当作迁移产物。所以在中断后先跑git status看工作区情况再决定是否手动 commit。4.4 路径迁移和目录搬家的特殊处理如果只是把src/main/java/com/example/Foo.java改名为src/main/kotlin/com/example/Foo.kt映射文件很容易写。但如果整个包目录要从src/main/java挪到src/main/kotlin而且目录里还混着很多暂时不转的 Java 文件就要小心了。直接逐文件 rename 会因为目录散落大量未迁移文件导致 Git 在 diff 时产生很多删除和新增记录影响重命名检测效果。更稳妥的做法是先把整个目录一次性移动git mv src/main/java/com/example src/main/kotlin/com/example这样所有文件先完成一次整体“搬家”之后再进行单文件的 J2K 转换。你会发现 Git 能更可靠地把历史绑定到新路径上blame 的断链率也会低很多。4.5 别忘了.gitattributes和 diff 驱动最后一个细节是团队协作体验。.kt文件默认可能被 Git 当成普通文本diff 时没有语法高亮也没有针对 Java 语义的差异优化。可以在仓库根目录的.gitattributes里加一行*.kt diffjava这样 Git 会用 Java 的 diff 驱动来处理 Kotlin 文件。虽然 Kotlin 和 Java 不完全一样但毕竟同属 JVM 语言在大多数场景下这已经能让 diff 变得友好很多。最后说点个人心得。用 j2kt-commiter 跑了两个多月最大的体会是工具本身不复杂真正的复杂度在于你有没有把迁移节奏控制好。每接一个 Java 模块我都会先列映射清单小批量的 rename-only 提交先行再跑 J2K转换后立刻验证 blame。这个过程已经成了肌肉记忆。保留历史这件事平时没人感受到它的存在但等你某天要查一个线上问题的上下文、追一个边界条件是谁加的就会发现当初多花的那几分钟完全值得。如果你也在做 Java/Kotlin 混合项目迁移建议先拿一两个小类试一下完整流程看到 blame 里出现旧提交后再铺开心里就有底了。本文还有配套的精品资源点击获取