Mavericks 完整版本演进史:从 MvRx 0.5.0 到 Mavericks 3.1.1 的核心变更与升级指南
Mavericks 完整版本演进史:从 MvRx 0.5.0 到 Mavericks 3.1.1 的核心变更与升级指南
本文以仓库根目录的 CHANGELOG.md 为主体脉络,结合 mvrx-common、mvrx、mvrx-mocking、mvrx-hilt 等模块源码,系统梳理 Mavericks(前身 MvRx)自 2018 年开源以来所有版本的关键变更、破坏性更新与新增能力。读完本文,你将掌握 Mavericks 从 RxJava 时代走向 Kotlin 协程时代、从 Android 绑定走向纯 Kotlin 抽象(MavericksRepository)、以及测试与 Mock 工具链不断强化的完整技术路线,并能在升级时对照各版本的迁移清单逐项操作。
一、版本演进总览:Mavericks 的四个发展阶段
从 CHANGELOG.md 可以清晰看到项目经历了四次大的阶段跨越:
| 阶段 | 版本区间 | 核心主题 |
|---|---|---|
| MvRx 1.x 及之前 | 0.5.0 ~ 1.5.1 | RxJava 时代的 MVP,依赖 Jetpack ViewModel,状态保存基于 SavedStateRegistry |
| Mavericks 2.x | 2.0.0 ~ 2.7.0 | 基于协程的全新重写,核心库移除 RxJava 2 依赖,扩展 mavericks-compose、mavericks-navigation |
| Mavericks 3.x | 3.0.0 ~ 3.1.1 | 实验性纯 Kotlin 模块 mvrx-common,引入 MavericksRepository 抽象 |
| 持续维护 | 当前仓库状态 | Thread-safe 测试状态存储、Mock 工具增强 |
其中 2.0.0 与 3.0.0 属于“地面重写”式的里程碑版本,CHANGELOG 分别给出了详细的 Breaking Changes 清单;而 2.1 ~ 2.7、3.0.1 ~ 3.1.1 则是围绕里程碑版本做的增量修复与新特性补充。仓库中 docs/new-2x.md 与 docs/new-3x.md 分别是对这两次大版本的专门说明文档,可与 CHANGELOG 对照阅读。
二、版本 2.0.0:基于协程的全面重写
Mavericks 2.0 是项目的分水岭。CHANGELOG 明确说明:MvRx 最初构建于 2017 年,当时几乎不可能不用 RxJava 构建复杂应用;而到了 2.0,核心库被完全用 Kotlin 协程重写,并移除了对 RxJava 2 的依赖。所有核心 API 都改为协程风格(详见 docs/new-2x.md)。
2.1 命名变更:MvRx → Mavericks
- 所有
mvrxartifact 名称改为mavericks。 - 仍在使用 RxJava 的既有用户需要引入
mavericks-rxjava2以保持向后兼容;仅使用协程的新用户直接使用mavericks即可。
2.2 核心 API 变更对照表
以下是 2.0 的 API 替换关系(来自 docs/new-2x.md,CHANGELOG 亦引用同一文档):
| MvRx 1.x | Mavericks 2.x |
|---|---|
subscribe(...): Disposable |
onEach(...): Job |
selectSubscribe(stateProp, action): Disposable(含多属性重载) |
onEach(stateProp, action: suspend (T) -> Unit): Job(含多属性重载) |
asyncSubscribe(stateProp, onFail, onSuccess): Disposable |
onAsync(stateProp, onFail: suspend (Throwable) -> Unit, onSuccess: suspend (T) -> Unit): Job |
execute 是 Observable<T>/Single<T>/Completable 的扩展 |
execute 是 Flow<T>/suspend () -> T/Deferred<T> 的扩展 |
| 无对应 | Flow<T>.setOnEach(dispatcher, reducer): Job |
| 无对应 | ViewModel<S>.stateFlow: Flow<S> |
| 无对应 | suspend ViewModel<S>.awaitState(): S |
值得注意的是,所有接收挂起 lambda 的订阅 API 都具备“上一个未完成即取消”的语义,行为类似 Flow<T>.mapLatest:当新值发出而旧 action 尚未完成时,旧 action 会被自动取消。
2.3 底层实现变化
- MavericksViewModel 不再继承 Jetpack ViewModel。它只是一个普通 Kotlin 类,在底层被包裹进一个 Jetpack ViewModel(相关封装见 MavericksViewModelWrapper.kt)。
viewModelScope和onCleared()仍然存在以匹配原有 API,但viewModelScope现在是MavericksViewModel自身的属性,而非 Jetpack 的扩展函数,旧的viewModelScopeimport 将变为未使用。 - 状态存储迁移到 SharedFlow:CHANGELOG 提到
CoroutinesStateStore迁移至 SharedFlow(#469),这为stateFlow、awaitState等协程 API 提供了底层基础。 execute支持保留值(retainValue):2.0 新增了在后续Loading与Fail状态下保留此前成功数据的能力(详见 docs/async.md)。
2.4 从 MvRx 1.x 升级的关键步骤
① 初始化方式改变:1.x 需要把 debugMode 传入 BaseMvRxViewModel 父类构造器;2.0 改为在 Application.onCreate() 中一次性调用 Mavericks.initialize(this)(实现见 Mavericks.kt)。由于 debugMode 不再逐个 ViewModel 传入,甚至不再需要自定义 Base ViewModel 类。
② Fragment 基类变化:1.x 要求 Fragment 继承 BaseMvRxFragment;2.0 只需实现 MavericksView 接口。mavericks-rxjava2 仍随附 BaseMvRxFragment,但已废弃。
③ 测试变化:1.x 的 MvRxTestRule 会把全局 RxJava Scheduler 设为同步(trampoline),而协程版本不再需要这种隐式行为;如果测试依赖了此行为,需要自行编写 RxRule。
④ 嵌套状态执行顺序修正:CHANGELOG 特别给出了嵌套 withState/setState 的执行顺序变化。旧版按嵌套层级优先级执行,会得到 [W1, S1, W2, S2, S3];新版修正为符合原始意图的 [W1, S1, S2, S3, W2]——即 setState 会在同一层级内先于外层 withState 完成。
⑤ 其他破坏性细节:
- 若
MavericksView/Fragment 不使用任何 ViewModel,invalidate()不再在onStart()中被调用(需要在 Base Fragment 中自行调用postInvalidate()以保持旧行为)。 - 所有受限制的内部 API 均已重命名,并统一以
@InternalMavericksApi标记(见 InternalMavericksApi.kt)。
2.5 2.x 系列的新功能与修复(2.1 ~ 2.7)
| 版本 | 关键内容 |
|---|---|
| 2.1.0 | 升级 Kotlin 1.4.30;移除 @RestrictTo 改用 @InternalMavericksApi;发布首个 mavericks-compose 版本。破坏性:ActivityViewModelContext 与 MavericksViewModelFactory 改用 ComponentActivity(FragmentActivity 的父类)以提升 Compose 互操作 |
| 2.2.0 | 修复 subscriptionLifecycleOwner 在 Fragment 的 onCreateView 中使用 viewLifecycleOwner(#533);移除 createUnsafe 且不在后台线程自动订阅(#525);修复 Lifecycle 2.3.0 下 MavericksLauncherActivity 抛 IllegalStateException(#523) |
| 2.3.0 | 错误处理增强(#540);Compose 升级至 beta07(#549)。注意此阶段 Compose 支持仍是实验性的,mvrx-compose 为 2.1.0-alpha02 |
| 2.4.0 | 协变重建支持(#565);为自定义 Flow 操作暴露唯一订阅处理(#560);支持恢复最初由父类中 companion factory 创建的 ViewModel(#566) |
| 2.5.0 | 修复 LocalContext 非 Activity 问题(#582);升级 Compose 1.0.4、Kotlin 1.5.31、Koin 3.1.3(#586);加载潜在可 Mock 类时忽略 VerifyError(#590) |
| 2.5.1 | 支持向 composable viewModel factory 手动传参(#595);修复 Compose 中 Fragment arguments 未正确传入状态初始化(#595);mavericks-compose 与其他 artifact 统一版本号 |
| 2.6.0 | 新增 mvrx-hilt artifact 预配置 Hilt(#598);支持 JUnit 5(#600);不再在 viewModel 返回类型中暴露 lifecycleAwareLazy(#603) |
| 2.6.1 | 暴露状态恢复函数(#611);尽可能使用传入的 scope 作为 fragment(#618) |
| 2.7.0 | MockBuilder 新增 mockEightViewModels 与 mockNineViewModels(#633) |
三、版本 3.0.0:纯 Kotlin 的 MavericksRepository
3.0 引入了实验性模块 mvrx-common(在 3.0.0 首发时曾因发布缺失在 3.0.1 修复),其核心是新的抽象 MavericksRepository。该模块是纯 Kotlin、没有任何 Android 依赖,目标是为纯 Kotlin 模块提供与 MavericksViewModel 完全相同的 API 与行为(详见 docs/new-3x.md)。
3.1 唯一破坏性变更:MavericksBlockExecutions
MavericksViewModelConfig.BlockExecutions 被抽取为顶层类 MavericksBlockExecutions(源码见 MavericksBlockExecutions.kt)。迁移方式就是把所有 MavericksViewModelConfig.BlockExecutions 引用替换为 MavericksBlockExecutions。该枚举有三个取值,直接控制 execute 的测试行为:
No:正常执行。Completely:完全阻止 execute 生效。WithLoading:阻止实际执行,但会执行一次状态回调,把 Async 属性置为 Loading,模拟调用正在进行。
3.2 MavericksRepository 的使用方式
实验性 API 需要显式 opt-in(-opt-in=com.airbnb.mvrx.InternalMavericksApi 编译参数)。构造有两种方式,其一是通过构造参数:
class WeatherForecastRepository(
scope: CoroutineScope,
private val api: WeatherApi,
) : MavericksRepository<WeatherForecastState>(
initialState = WeatherForecastState(),
coroutineScope = scope,
performCorrectnessValidations = BuildConfig.DEBUG,
) {
init {
suspend { api.getForecasts() }.execute { copy(forecasts = it) }
}
fun refresh() {
suspend { api.getForecasts() }.execute { copy(forecasts = it) }
}
}
其二是通过 MavericksRepositoryConfig(源码见 MavericksRepositoryConfig.kt),它提供四个关键配置项:
| 配置项 | 含义 |
|---|---|
performCorrectnessValidations |
是否执行正确性校验(含 reducer 纯度检查、状态不可变性校验)。只应在 debug 构建开启,生产环境关闭以避免反射开销 |
stateStore |
控制仓库状态的 MavericksStateStore 实例 |
coroutineScope |
仓库使用的协程作用域 |
subscriptionCoroutineContextOverride |
订阅(如 onEach)所用协程上下文的覆盖项,默认 EmptyCoroutineContext |
onExecute |
每次 execute 调用时回调,返回 MavericksBlockExecutions 决定是否跳过执行,主要用于测试 Mock |
3.3 底层架构:MavericksViewModel 内部即 MavericksRepository
从源码看(MavericksRepository.kt),MavericksViewModel 底层正是用 MavericksRepository 来管理状态。仓库类提供的核心能力包括:
setState(reducer: S.() -> S):异步执行 reducer;开启校验时会调用 reducer 两次以检测“不纯”的 reducer(两次结果不一致会抛出带属性名的IllegalArgumentException)。这也印证了 CHANGELOG 1.0.1 中“improve the error message for impure reducers”的演进(#229)。withState/awaitState():awaitState挂起直到所有挂起的 setState reducer 执行完并返回最新状态。stateFlow:暴露当前状态及后续更新的 Flow(刻意不用 StateFlow,以避免对状态做同步访问)。execute(对Deferred<T>、suspend () -> T、Flow<T>的重载)与setOnEach、onEach(1~7 属性重载)、onAsync等订阅 API。resolveSubscription(#560 “Exposing unique subscription handling for custom flow operations”的落地):用collectLatest实现订阅,保证并发时旧订阅被取消。
3.4 3.0 系列其他修复
| 版本 | 关键内容 |
|---|---|
| 3.0.1 | 修复 mavericks-common 模块在 3.0.0 未发布到 Maven 的问题 |
| 3.0.2 | 用 whenStarted 包裹订阅 action(#665);更新内嵌 Proguard/r8 规则以兼容 R8 full mode(#658) |
| 3.0.3 | 改变 flowWhenStarted 在 flow 协程上下文上发射值的行为(#678) |
| 3.0.9 | 修复状态恢复中含 32 的倍数个字段时崩溃的问题(#707) |
| 3.1.0 | mavericks-mocking 工具与 Setter DSL 改用 Java reflection 替代 Kotlin reflection,减少使用场景限制 |
| 3.1.1 | 使 SynchronousMavericksStateStore 与 MockableMavericksStateStore 线程安全,测试中的并发 setState 不再互相丢弃更新(#739) |
四、Mock 工具链的持续强化(贯穿 1.x ~ 3.x)
Mock 是 Mavericks 测试体验的重要组成,CHANGELOG 多次提到其演进:
- 1.0.1:
MvRxTestRule可禁用订阅的生命周期检查(#235)。 - 1.2.0:增加 inter-view-model 订阅支持(#287)。
- 2.0.0:Mocking 框架 API 扩充(#475/#477)。
- 2.7.0:
MockBuilder新增mockEightViewModels、mockNineViewModels(#633)。 - 3.1.0:Mock 工具与 Setter DSL 全面改用 Java reflection。
- 3.1.1:
SynchronousMavericksStateStore与MockableMavericksStateStore线程安全化(#739)。
其中 3.1.1 的线程安全修复在源码中有直接体现:SynchronousMavericksStateStore(SynchronousMavericksStateStore.kt)的 set 方法在 synchronized(lock) 内同时完成状态更新与 tryEmit,保证 Flow 收到的状态顺序与写入顺序一致、最新值始终是当前状态,从而允许多线程并发 setState 而不互相覆盖。仓库中还配套了并发场景的测试(SynchronousMavericksStateStoreTest.kt)。
Mock 框架本身位于 mvrx-mocking/src/main/kotlin/com/airbnb/mvrx/mocking,核心组件包括 MockBuilder、MockableMavericksStateStore、ViewMocker、DataClassSetDsl 以及位于 printer/ 子目录的 MavericksMockPrinter(用于自动生成 mock 代码,其独立脚本见 mock_generation/MavericksMockPrinter.kts)。
五、1.x 时代的关键里程碑(0.5.0 ~ 1.5.1)
在 2.0 重写之前,1.x 系列奠定了 MvRx 的早期架构基础:
| 版本 | 关键内容 |
|---|---|
| 0.5.0 | 首次开源发布 |
| 0.6.0 | 增加停止→启动过渡时不再重发最近状态值的选项(#113);ScriptableStateStore 接口用于 UI 测试(#88);状态不可变性 debug 校验(#90);selectSubscribe 支持 4~7 个属性(#125);修复多个 setState 在 withState 中的执行顺序(#89) |
| 0.7.0 | 破坏性:MvRxViewModelFactory 类型签名从 MvRxFactory<S> 改为 MvRxFactory<VM, S>;create 改为接收 ViewModelContext 并返回 VM?,引入 FragmentViewModelContext 以支持依赖注入;新增 initialState(viewModelContext);@JvmStatic 不再必需;新增 MvRxTestRule(mvrx-testing artifact)与 Completable#execute(#170);@PersistState 保存/重建提速(#159) |
| 0.7.1 | ViewModelFactoryContext 新增 app()(#179);修复私有状态属性导致 debug 检查崩溃(#178) |
| 0.7.2 | 修复 mvrx-testing artifact 的 group 名(#184) |
| 0.8.0 | 破坏性:BaseMvRxViewModel 必须显式传入 debug 标志(#196) |
| 1.0.0 | MvRx 要求 androidx;防止 onCreate 之后的重复订阅(#210);uniqueOnly 在配置变更间保持(#207);移除状态合并(state coalescing,#206);所有 MvRxViewModel 必须提供 debugMode(#196) |
| 1.0.2 | 同步并优化 Kotlin 缓存预热(#244);flushQueues 改为 tailrec 提升性能(#252);升级 RxJava 2.1.1 / RxAndroid 2.2.8(#233) |
| 1.1.0 | 新增 parentFragmentViewModel() 与 targetFragmentViewModel() 委托作用域(#247);禁止在 state 中放函数(#250);debug 模式下记录 execute 错误(#260) |
| 1.2.0 | companion factory 查找更健壮(#283);修复 state store 队列冲刷时的线程泄漏(#302);inter-view-model 订阅(#287) |
| 1.3.0 | 破坏性:状态保存全面改用 Jetpack SavedStateRegistry(#254),删除 MvRxViewModelStoreOwner 与 BaseMvRxActivity;改为直接继承 AppCompatActivity,状态保存完全自动化 |
| 1.4.0 | 彻底移除 Kotlin-Reflect(#334)与多余 proguard 依赖(#310) |
| 1.5.0 | 所有 Async 类增加可选的 nullable value(#383);升级依赖。注意 MvRx 此时要求 Java/Kotlin target 1.8,需要配置 kotlinOptions.jvmTarget = JavaVersion.VERSION_1_8.toString() |
| 1.5.1 | 修复属性为 internal 可见性时 data class 断言误失败的问题 |
1.3.0 的 SavedStateRegistry 改造(#254)是 1.x 最重要的架构变更:它移除了手工管理 mvrxViewModelStore 的必要性,状态保存与恢复完全自动完成,这一设计在后续 PersistState.kt 与 MavericksStateFactory 中持续沿用。
六、迁移速查:两份官方迁移指南
针对两次最大的版本跃迁,仓库在 docs/new-2x.md(2.0 迁移)与 docs/new-3x.md(3.0 迁移)中提供了专门说明。快速对照:
- 1.x → 2.x:换 artifact 名(
mvrx→mavericks,RxJava 用户用mavericks-rxjava2);Mavericks.initialize(this)一次性初始化;Fragment 实现MavericksView;订阅 API 从subscribe/selectSubscribe/asyncSubscribe换成onEach/onAsync;execute从 Rx 类型扩展改为 Flow/suspend/Deferred 扩展。 - 2.x → 3.x:唯一破坏性变更是
MavericksViewModelConfig.BlockExecutions→MavericksBlockExecutions;新增实验性的mvrx-common模块与MavericksRepository,需要-opt-in=com.airbnb.mvrx.InternalMavericksApi编译参数才能使用。
七、结论
纵观 CHANGELOG.md,Mavericks 的演进主线清晰:MvRx 1.x 时期完成状态保存自动化与工厂 API 灵活化(0.7.0、1.3.0 是当时的关键节点),2.0 以协程重写完成技术栈现代化(API 全部协程化、移除 RxJava 依赖),3.0 通过 MavericksRepository 把状态管理抽象下沉到纯 Kotlin 层,而 3.1.x 则聚焦于测试基础设施的可靠性与 Mock 工具的可移植性(Java reflection、线程安全)。对开发者而言,这份 CHANGELOG 既是升级手册,也是理解 Mavericks 设计取舍(为何用协程、为何 stateFlow 不是 StateFlow、为何 performCorrectnessValidations 只开 debug)的第一手资料。