Mavericks 完整版本演进史:从 MvRx 0.5.0 到 Mavericks 3.1.1 的核心变更与升级指南

原创2026-10-09 10:50:421,682 阅读
文章标签:移动开发原生移动

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

  • 所有 mvrx artifact 名称改为 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 的扩展函数,旧的 viewModelScope import 将变为未使用。
  • 状态存储迁移到 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)的第一手资料。

登录后查看全文
mavericks