android-rxjava-to-coroutines-migration

Android RxJava 到 Coroutines 迁移

适用场景

• 当请求涉及以下内容时，使用此技能：Android 中从 RxJava 迁移到 Coroutines、Android 中从 Observable 迁移到 Flow、替换 Android 中的 CompositeDisposable。
• 主要目标：将 Android RxJava 代码迁移到 Kotlin Coroutines 和 Flow，并采用安全且感知生命周期的替代方案。
• 当代码库仍暴露 Single、Observable、调度器或 Disposable，且目标是迁移到 suspend、Flow、StateFlow 或 SharedFlow 时，使用此技能。
• 阅读 references/patterns.md，了解类型映射矩阵和操作符风险检查清单。
• 阅读 references/scenarios.md，了解分阶段迁移和优先盘点的工作流。
• 当范围扩大时，交接给以下技能：
• android-modernization-upgrade
• android-coroutines-flow

工作流

1. 在更改任何 API 表面之前，扫描代码库中的 RxJava 导入、基类型、Subject 和调度器用法。
2. 将每项用法归类为一次性任务、流式任务、热状态、热事件、回调桥接或对背压敏感的任务。
3. 先替换仓库层和领域层 API，再将 UI 层订阅迁移为感知生命周期的收集。
4. 将调度器和 Disposable 管理改写为 Dispatcher、作用域、结构化并发所有权，以及 repeatOnLifecycle 等感知生命周期的收集方式。
5. 对语义不明确的操作符或自定义桥接保留检查清单，不要假装每个链式调用都能安全地自动转换。

防护原则

• 一次性任务优先使用 suspend 函数，流优先使用 Flow；不要强行将所有内容都转换为 Flow。
• 替换 CompositeDisposable 和手动订阅链时，保留生命周期所有权。
• 指出需要人工审查的操作符语义，尤其是 flatMap、switchMap、重放和线程假设。
• 使用 StateFlow、SharedFlow、shareIn 或 stateIn 明确保留热状态和重放语义，不要假设冷 Flow 与之等价。
• 将迁移视为保持行为不变的重构，而不是重新设计无关业务逻辑的机会。

反模式

• 将所有 Rx 类型都转换为 Flow，即使 suspend 函数更合适。
• 迁移 Subject 时丢失重放、缓冲或热流语义。
• 迁移到 Dispatcher 后，未记录 observeOn 和 subscribeOn 的相关假设。
• 未分阶段验证，就一次性重写仓库层、ViewModel 层和 UI 层。

审查重点

• 类型映射：Single、Maybe、Completable、Observable、Flowable 和 Subject。
• 热流与冷流语义、重放行为及背压预期。
• Dispatcher 所有权、viewModelScope 和生命周期收集。
• 协程时序、取消和流断言方面的测试影响。

示例

理想场景

• 场景：扫描一个旧版 RxJava 示例，并为仓库层、ViewModel 和 UI 订阅生成迁移检查清单。
• 命令：bash skills/android-rxjava-to-coroutines-migration/scripts/run_examples.sh

边缘场景

• 场景：在转换状态或一次性事件之前，盘点 Subject、Disposable 和调度器用法。
• 命令：python3 skills/android-rxjava-to-coroutines-migration/scripts/scan_rxjava_usage.py examples/fixtures/rxjava-legacy-sample --json

失败恢复

• 场景：当链中的某些部分仍需人工审查操作符时，生成确定性的检查清单。
• 命令：python3 skills/android-rxjava-to-coroutines-migration/scripts/generate_migration_checklist.py examples/fixtures/rxjava-legacy-sample

完成检查清单

• 在提出代码更改之前，已盘点 RxJava 类型和操作符。
• 一次性 API、流、热状态和热事件已映射到合适的协程原语。
• 生命周期所有权和 Dispatcher 假设已明确说明。
• 语义不明确的操作符或桥接情形已记录为后续人工处理事项。

Official References

• https://developer.android.com/kotlin/coroutines
• https://developer.android.com/kotlin/flow
• https://developer.android.com/kotlin/coroutines/coroutines-best-practices
• https://developer.android.com/topic/libraries/architecture/coroutines
• https://developer.android.com/kotlin/flow/stateflow-and-sharedflow
• https://kotlinlang.org/docs/flow.html