SuperAPI AI 工具集

cometchat-android-v6-migration

编程与开发

查看项目

更新于 10-21 20:55

技能介绍

用途

该技能用于把 Android 应用从 CometChat v5 UI Kit(Java、XML Views)升级到 v6(Kotlin,XML Views 或 Jetpack Compose)。它定位为版本协调(reconciliation),而非初次接入(onboarding),因此出现 version_conflict 是预期情况,解决它正是该技能的工作。

主要能力

  • 提供 v5→v6 的破坏性变更映射表,覆盖语言、模块、导入根、CometChatUIKit、UIKitSettings、状态、架构、事件、主题、样式、ViewModel 访问、列表操作、Repository、minSdk 等维度。
  • 明确组件重命名:仅 CometChatThreadedMessagesHeader → CometChatThreadHeader 一处;其余组件(CometChatConversations、CometChatUsers、CometChatGroups、CometChatMessageHeader、CometChatMessageList、CometChatMessageComposer、CometChatIncomingCall、CometChatOutgoingCall、CometChatCallButtons、CometChatCallLogs、CometChatGroupMembers)保留名称,仅迁移包路径。
  • 给出按顺序执行的迁移步骤(codemod / steps),包括选择 XML Views 或 Compose 队列、提升 minSdk、替换依赖、重写导入、迁移初始化、事件、状态、样式主题、Compose 重建界面、构建与运行。
  • 提供 before → after 代码模式示例(导入、初始化、事件收集)。
  • 列出常见陷阱与验证方法。

使用方式

  1. 先阅读配套技能 cometchat-android-v6-core,了解 v6 安装、凭据(assets/cometchat-settings.json)、initFromSettings → login → render 的黄金路径。迁移最终以 core 的黄金路径为终点。
  2. 迁移前确认当前构件与版本、应用可构建、minSdk。v6 要求 minSdk 28(v5 允许 24),若目标更低需先作为产品决策提出。
  3. 处理两个构建阻塞:在 gradle.properties 设置 android.useAndroidX=true 与 android.enableJetifier=true(Chat SDK 仍拉取 pre-AndroidX 传递依赖,导致 Duplicate class android.support.v4.*),并保留 configurations.all { exclude(group = "org.jetbrains", module = "annotations-java5") }。同时提升下限:minSdk 28、Kotlin 2.1、AGP 8.9.1。
  4. 选择队列:继续使用 XML Views(chatuikit-kotlin-android,差异最小)或迁移到 Compose(chatuikit-compose-android,聊天界面需重写)。需询问用户,不要假设,且不要同时发布两者。
  5. 将 minSdk 提升到 28,确认 Kotlin/AGP/JVM 11 就绪。
  6. 替换依赖为所选队列的 6.x 构件(并添加 CometChat Maven 仓库,见 core §Install)。彻底移除 v5 构件——在构建文件中 grep com.cometchat:chat-uikit-android(这是 v5 的 id),残留的 v5 依赖会导致 duplicate-class/version_conflict 失败。
  7. 重写导入(差异主体,机械性操作):
    • com.cometchat.chatuikit.shared.cometchatuikit.CometChatUIKit → com.cometchat.uikit.core.CometChatUIKit(UIKitSettings 同理)。
    • com.cometchat.chatuikit.<area>.<Component> → com.cometchat.uikit.kotlin.presentation.<area>.ui.<Component>(XML Views)或 …uikit.compose.presentation.<area>.ui.<Component>(Compose)。
    • grep 目标:com.cometchat.chatuikit.(任何命中都是 v5)与 CometChatThreadedMessagesHeader(唯一重命名)。
  8. 迁移初始化到 v6:v6 默认使用 CometChatUIKit.initFromSettings(context, callback) 读取 app/src/main/assets/cometchat-settings.json,然后在 onSuccess 中登录(见 core)。同时把凭据移出源码。
  9. 事件:将每个 addListener/removeListener 对替换为在 lifecycleScope(Views)或 LaunchedEffect(Compose)中 CometChatEvents.<domain>Events.collect { }。无需手动移除(见 cometchat-android-v6-events)。
  10. 状态:LiveData.observe(...) → 在生命周期感知作用域中收集 StateFlow。
  11. 样式/主题:样式对象 → 主题属性(themes.xml 继承 CometChatTheme.DayNight)或 Compose 样式数据类(见 cometchat-android-v6-{kotlin,compose}-customization)。
  12. 仅 Compose:将聊天界面重建为 composable(core 的黄金路径 / cometchat-android-v6-{kotlin,compose}-placement 配方)——承载 kit 视图的 XML 布局不会直接迁移。
  13. 构建后运行,按组件使用文档页的 “Component-by-Component Migration” 部分修复(获取:/ui-kit/android/upgrading-from-v5.md)。

适用场景

当用户提出以下需求时使用:"upgrade our Android UI Kit from v5 to v6"、"we're on the Java UI Kit, move us to Kotlin/Compose"、"what breaks in v6?"、"fix these v5 imports"。

限制

  • 迁移前必须确认当前构件与版本、应用可构建、minSdk;v6 要求 minSdk 28,若应用目标更低,需先作为产品决策提出,可能阻塞整个迁移。
  • 不能同时发布 XML Views 与 Compose 两个队列。
  • 必须彻底移除 v5 构件,否则会出现 duplicate-class/version_conflict 失败。
  • 必须处理 AndroidX/Jetifier 与 annotations-java5 排除,否则构建阻塞。
  • 任何在 v5 中存在但 v6 无对应能力的功能,必须报告给用户,不能静默丢弃(见 COVERAGE.md)。
  • 验证要求:源码中 com.cometchat.chatuikit. 与 CometChatThreadedMessagesHeader 零匹配;仅一个 cometchat UI-Kit 构件解析(./gradlew :app:dependencies);fence gate 编译通过(./gradlew :app:assembleDebug,在用户应用中;npm run verify:fences:android-v6 是 pack-repo gate)。设备上:init + login 成功,conversations → messages 可用,threads/search 往返正常,事件只触发一次,主题仍匹配品牌,calls/push(若使用)仍可用。