kotlinx.collections.immutable 0.5.x 方法全改名？kotlin-agent-skills 的编译器驱动迁移完全教程

【免费下载链接】kotlin-agent-skillsA collection of AI agent skills useful for projects using Kotlin language项目地址https://gitcode.com/gh_mirrors/ko/kotlin-agent-skills点击查看免费下载kotlin-agent-skills是 JetBrains 维护的一套面向 Kotlin 项目的 AI Agent 技能集合其中kotlin-tooling-immutable-collections-0-5-x-migration技能专门解决一个让很多开发者头疼的问题kotlinx.collections.immutable 从 0.3.x / 0.4.x 升级到 0.5.x 时所有返回副本的方法全部改名add→adding、put→putting……。这篇文章将带你用编译器驱动的思路完成迁移升版本、重新编译、按警告逐个改名全程机械且可验证。为什么 0.5.x 要把所有方法改名 先搞清楚背景。按照 Kotlin 官方命名规范提案KEEP-0459返回新集合副本的操作应使用分词形式participial form命名以和MutableList这类原地修改的操作区分开集合类型旧方法名0.5.x 新名字PersistentCollectionadd/addAlladding/addingAllPersistentCollectionremove/removeAllremoving/removingAllPersistentCollectionretainAll/clearretainingAll/clearedPersistentListadd(i, e)/addAll(i, c)addingAt/addingAllAtPersistentListset/removeAtreplacingAt/removingAtPersistentMapput/putAllputting/puttingAllPersistentMapremove(k)/clearremoving/cleared好消息是这次改名是二进制兼容、语义不变的纯调用点重命名——参数、顺序、返回类型完全一样只有方法名变了。而且旧名字只是被标记为WARNING级别的Deprecated并附带ReplaceWith提示编译器会直接告诉你该换成什么。⚠️ 一个时间线要记住0.6.0 中旧名字会变成编译错误0.7.0 中彻底移除。所以如果你的项目自定义实现了这些接口趁 0.5.x 迁移是最佳时机。认识 kotlin-agent-skills 和这个迁移技能skills/ 目录下按kotlin-分类-功能名的约定组织技能分类定义在 CATEGORIES 中目前有backend和tooling两类。本次主角位于skills/kotlin-tooling-immutable-collections-0-5-x-migration/SKILL.md它的核心方法论只有一句话Trust the compiler — never find/replace by name信任编译器绝不按名字查找替换。因为MutableList/MutableMap/MutableSet以及.Builder类型上存在同名方法它们不会被弃用——盲改会破坏这些调用点。迁移前先判断你需要做什么技能给出的判断标准非常简洁当前是 0.3.x 或 0.4.x任何 0.5.0 之前的版本→ 执行下面 6 步迁移已在 0.5.x 但不是最新版→ 直接把版本升到最新 0.5.x 即可0.5.x 系列共享同一套改名线内升级不会再新增弃用警告已是最新 0.5.x 或 0.6.x→ 什么都不用做。编译器驱动迁移完整 6 步流程第 1 步找到构建命令先看项目的README.md、CLAUDE.md或AGENTS.md里有没有写明构建方式没写就从构建文件推断——Gradle 用./gradlew、Maven 用mvn或./mvnw、Bazel 用对应 wrapper。多模块项目只需编译用到该库的模块不必全仓构建。第 2 步基线编译在当前版本上先编译一次确认是绿的。如果现在都编译不过迁移后你就分不清哪些错误是历史遗留、哪些是改名引入的。第 3 步升级到最新 0.5.x用类似grep -rn kotlinx-collections-immutable定位版本声明处version catalog、build 脚本、gradle.properties、pom.xml都可能改成 Maven Central 上的最新 0.5.x。两个易踩的坑锁定了构件哈希如gradle/verification-metadata.xml把依赖校验失败信息里给出的新校验和复制过来只补那一条记录即可别急着全量重新生成元数据报 Kotlin metadata 版本解析错误说明项目的 Kotlin 版本太旧先升 Kotlin。第 4 步重新编译按警告逐个改名核心循环每个被改名的方法都带Deprecated(WARNING, ReplaceWith(...))编译器会在每个调用点输出一条警告并直接给出替代方法名例如Use removingAll() instead。你只需照着警告改名重复编译 → 修警告直到没有kotlinx.collections.immutable的弃用警告为止。 几个关键细节遇到Unresolved reference说明改名被拆开了——同一个改名必须让声明和所有调用点一起迁移。如果接收者receiver根本不属于这个库比如是Mutable*或.Builder说明改错了回滚这个调用点按接收者的声明类型判断而不是方法名一个字段叫Persistent*不代表它真的是该库的类型Java 调用方默认不会被编译警告暴露javac 的-Xlint:deprecation通常关闭需要 grep 导入了该库的.java文件对接收者为Persistent*的调用改名改名后编译器可能提示某些Suppress(DEPRECATION)已无效果——删掉它们删前先重读一下上下文确认它没有顺带压住别的东西。第 5 步迁移自定义实现类如果项目里有类自己实现了PersistentList/PersistentMap/PersistentSet/PersistentCollection它们的被弃用 override 也要迁移把真实实现移到新的分词方法里旧 override 改为委托新实现并加Suppress(OVERRIDE_DEPRECATION)。技能文档中给出了完整的检索命令grep/ PowerShellSelect-String两套可直接复制使用见 SKILL.md 第 5 节。第 6 步执行项目文档中的收尾步骤在改名编译通过之后再做如果项目在文档里写了依赖变更后需执行的步骤最常见的是重新生成依赖校验元数据照做一次即可——全量--write-verification-metadata很慢跑一遍就够不必反复执行。最后再确认构建干净。常见误区速查 误区正确做法全局查找替换旧方法名只改编译器标红的调用点Mutable*和.Builder上的同名方法不动升级后编译失败就反复重跑依赖解析/元数据生成失败恰恰是因为这些弃用未修完继续按警告改名看到Unresolved reference就怀疑库的问题先检查接收者的声明类型多半是改名没迁移完整只迁 Kotlin 代码Java 调用方需单独 grep 检查如何安装并使用 kotlin-agent-skills 按 README.md 的说明仓库提供三种安装方式# 方式一skills CLI npx skills add Kotlin/kotlin-agent-skills # 方式二Claude Code 插件市场 claude plugin marketplace add Kotlin/kotlin-agent-skills claude plugin install kotlin-agent-skillsKotlin # 方式三手动复制单个技能到 agent 的技能目录 cp -r skills/kotlin-tooling-immutable-collections-0-5-x-migration .claude/skills/当你在对话中提到 kotlinx.collections.immutable 0.5.x、Use adding() instead 这类弃用警告或KEEP-0459等关键词时AI Agent 会自动加载这个技能并按上述流程执行迁移。仓库同时提供 plugins/ 目录用于插件形式分发贡献规范见 CONTRIBUTING.md。顺带看看仓库里的其他技能kotlin-agent-skills 不只覆盖这一个场景skills/ 下还有kotlin-backend-jpa-entity-mappingJPA 实体映射最佳实践kotlin-tooling-agp9-migrationAndroid Gradle Plugin 9 迁移指南kotlin-tooling-cocoapods-spm-migrationCocoaPods 到 SPM 迁移kotlin-tooling-java-to-kotlinJava 转 Kotlin附带 Spring、Dagger/Hilt、Mockito 等 12 个框架的专项参考总结✨ kotlinx.collections.immutable 0.5.x 的迁移没有想象中可怕改名是机械的、二进制兼容的而编译器就是最可靠的改名清单。kotlin-agent-skills 的这套技能把升级版本 → 基线编译 → 按警告改名 → 处理实现类和 Java 调用方固化成标准流程配合 SKILL.md 里的完整改名对照表无论是人工执行还是交给 AI Agent 执行都能在编译通过的前提下干净地完成升级。赞分享【免费下载链接】kotlin-agent-skillsA collection of AI agent skills useful for projects using Kotlin language项目地址https://gitcode.com/gh_mirrors/ko/kotlin-agent-skills点击查看免费下载相关推荐Monolog 2.x/3.x/4.x 升级迁移完全指南API 变更、代码迁移与实战改造Monolog 2.x/3.x/4.x 升级迁移完全指南API 变更、代码迁移与实战改造 导读 本文基于 Monolog 仓库中的 UPGRADE.md ht后端Actix Web 0.x 版本迁移完全指南从 0.5 到 0.7.15 的 API 演进与升级实践Actix Web 0.x 版本迁移完全指南从 0.5 到 0.7.15 的 API 演进与升级实践 本文以 actix web/MIGRATION 0.x.后端Web框架Kotlin 2.2 JVM默认方法兼容性与迁移策略完全指南Kotlin 2.2 JVM默认方法兼容性与迁移策略完全指南 Kotlin 2.2版本带来了重要的JVM默认方法改进默认启用 Xjvm defaultal编程语言编译器标准库语言运行时创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考