Kotlin 持久化集合库 0.5.x…

当项目使用 kotlinx.collections.immutable 0.3.x/0.4.x 需要升级到 0.5.x，或出现「Use adding() instead」等弃用警告时，用编译器驱动的方式完成方法重命名迁移。

适用场景

解决思路

1. 先确认当前版本：0.3.x 或 0.4.x 才需要迁移；已在 0.5.x 但非最新则只把版本号改到最新 0.5.x 即可（同一线内重命名相同，无需重新编译）；已在最新 0.5.x 或 0.6.x 及以上则无需操作。
2. 找到构建命令：查看 README.md、CLAUDE.md、AGENTS.md，若未写明则从构建文件推断（Gradle 用 ./gradlew，Maven 用 mvn 或 ./mvnw，Bazel 用 bazel 包装脚本，或自定义脚本），记录编译命令和测试命令；多模块项目只需编译使用该库的模块及被改动的模块，不必全仓库构建。
3. 先做基线编译：在当前版本上编译并确认通过，否则无法区分迁移后的错误与原有错误。
4. 升级到最新 0.5.x：用 grep -rn kotlinx-collections-immutable 在构建文件（version catalog、build 脚本、gradle.properties、pom.xml 等）中找到版本固定处，改为 Maven Central 上的最新 0.5.x（-beta 也可以）；若构建固定了构件哈希（如 gradle/verification-metadata.xml），也要更新——最省事的做法是从依赖校验失败信息中直接复制新构件的校验和，只添加那一条，而不是重新生成整个元数据文件。该升级是二进制兼容的，旧代码仍能编译但会有警告。若依赖解析失败并报 Kotlin metadata 版本错误，说明项目 Kotlin 版本太旧，需先升级 Kotlin。
5. 重新编译并修复警告：每个被重命名的方法都带 @Deprecated(WARNING, ReplaceWith(...))，编译器会为每个调用点输出一条警告并指明替代名（如「Use removingAll() instead」），按警告提示重命名；重复「编译→修复」直到不再有 kotlinx.collections.immutable 的弃用警告。多平台项目编译一个目标即可暴露共享调用点；原有的工厂方法弃用（如 immutableListOf → persistentListOf）也会以同样方式出现，一并处理。升级后立即编译失败通常就是这些弃用（加上固定哈希时的一次性依赖校验错误），继续按警告重命名即可，不要反复运行依赖解析或元数据重新生成命令。
6. 信任编译器，绝不要按名字做查找替换：MutableList/MutableMap/MutableSet 以及 .Builder 类型上存在同名方法，它们是原地修改且未被弃用；只有编译器标记的（接收者静态类型为 Persistent*）才重命名，没被标记的就不要动。
7. 重命名后出现 Unresolved reference 说明该接收者上没有分词形式的新名字，即重命名只做了一半：重命名只有在声明和所有调用点一起改时才能编译。库本身已为 kotlinx 类型做了声明侧改动，所以改其调用点即可；但对其他仅同名的情况不成立。分两种情况：接收者与本库无关（Mutable*、.Builder、其他类型的同名方法）说明改错了，回退该处；接收者是项目自身正在迁移的类型（实现了 Persistent*，或是项目自己的包装类且方法名与之呼应）说明改对了但只做了一半，需同时重命名声明和其他调用者。判断依据是接收者的声明类型，而不是方法名——名为 Persistent* 的字段可能持有其他类型。
8. Java 调用方：重新编译只有在构建开启 javac 弃用警告（-Xlint:deprecation，通常默认关闭）时才会标记它们；若未开启，则 grep 导入该库的 .java 文件中的旧方法名，重命名接收者为 Persistent* 类型的调用。
9. 重命名完成后，编译器可能报告某些 @Suppress("DEPRECATION") 已无效果，删除它们（先重新阅读该区域，确认它是否还覆盖其他内容）。
10. 处理自定义实现类：若项目有类实现 PersistentList/PersistentMap/PersistentSet/PersistentCollection，其被弃用的 override 也需迁移。用 grep -rnE --include='*.kt' '(class|object|interface)\s+\w[^:]*:\s*[^{]*\b(PersistentList|PersistentMap|PersistentSet|PersistentCollection)\s*<' . 查找；Windows PowerShell 用 Get-ChildItem -Recurse -Filter *.kt | Select-String '...'。确认匹配项确实把该接口列为父类型，而非仅字段类型或类型参数。对每个实现，把实现移入新的分词方法，让被弃用的 override 委托给它：override fun adding(element: E): MyList<E> = /* 真实实现 */，然后 @Suppress("OVERRIDE_DEPRECATION") override fun add(element: E): MyList<E> = adding(element)。若分词方法之间互相调用，应通过分词兄弟方法调用，而不是弃用名。仅当 override 方法体本身仍调用弃用成员时才把 "DEPRECATION" 加入 suppress。现在就做很重要：0.6.0 时旧名会变成编译错误，0.7.0 时被移除。
11. 在重命名编译干净之后，再执行项目文档中记录的后续步骤（这样即使时间不够，调用点工作也已完成）。有些项目记录了编译器不会提示的依赖变更后步骤，最常见的是重新生成依赖校验元数据（第 3 步的 gradle/verification-metadata.xml 哈希）。通常第 3 步的单条修复就够了；只有当那一条不够时，才回退到项目文档（README.md/CONTRIBUTING.md/CLAUDE.md/AGENTS.md）中的完整重新生成流程。只运行一次——完整的 --write-verification-metadata /「解析所有依赖」会重新解析整个依赖图，很慢，且重复运行很少改变结果。之后再次确认构建干净。
12. 重命名对照表：PersistentCollection —— add→adding、addAll→addingAll、remove→removing、removeAll→removingAll、retainAll→retainingAll、clear→cleared；PersistentList（含上述全部，另加）—— add(i, e)→addingAt、addAll(i, c)→addingAllAt、set(i, e)→replacingAt、removeAt→removingAt；PersistentMap —— put→putting、putAll→puttingAll、remove(k)→removing、remove(k, v)→removing、clear→cleared。Builder（PersistentList.Builder 等）不重命名——它们原地修改，命令式名字保留。

适用边界 · 注意事项

• 项目已在使用最新 0.5.x，或已升级到 0.6.x 及以上时无需迁移。
• 不要对 MutableList/MutableMap/MutableSet 或 .Builder 类型上的同名方法做重命名，它们未被弃用且是原地修改。
• 不要用按名字的全局查找替换来迁移，只改编译器标记的调用点；也不要为清除编译失败而反复运行依赖解析或元数据重新生成命令。