基于Jetpack MVVM的Android快速开发框架设计与落地复盘

刚把团队项目的 Android 端整个架构翻新了一遍，从原来Activity 里塞一切的老写法，迁到了基于 Jetpack + MVVM 的一套管式开发框架上。这套东西不是简单抄一个开源项目改改包名，而是结合我们自己三年线上产品踩坑、业务迭代、人员流动之后沉淀下来的。整理这篇内容，既是给外面想搭类似框架的朋友一个参考，也是对我们自己这套方案的完整复盘。你先别急着找代码模板下载，先搞清楚它到底解决了什么问题，你才知道照着怎么改。

1. 设计这套框架前，我先把这些问题想清楚了

1.1 不是MVVM不够好，而是落地姿势不统一

很多团队的问题不是没上 MVVM，而是每个人写的 MVVM 都不一样。有人把网络请求写进 Activity，有人把业务逻辑堆在 Fragment，有人用 LiveData 有人用 RxJava，换个模块就要重新读一遍代码。表面上大家都在说 MVVM，其实内部比谁拼的盘还乱。在一线写过几年业务后我特别明显的感受：架构本身不是银弹，统一约定才是。

所以我在搭这套"快速开发框架"时，核心目标不是发明新的架构理论，而是做一套约束。用 Jetpack 官方的组件作为骨架，用 MVVM 作为分层逻辑，把每个页面要走的路径、每个数据要流的通道、每个异步任务要挂的作用域全部定死。新同事进来不需要看设计文档，看着 base 类的封装和已有模块的样例，就知道新页面该怎么写。

1.2 快速开发不等于不做架构

有人一听"快速开发框架"，就以为是为了少写代码，用反射、用注解、用动态代理把所有东西自动掉。我见过不少项目框架化过度，自定义注解满天飞，调试一个问题要翻三层拦截器。实际上快速开发的本质，是让开发者在正确的轨道上走得快，而不是让他无障碍地乱跑。这套框架里的"快"，体现在三件事上：

• 大部分页面的 ViewModel、布局绑定、生命周期收集代码，都被 base 类吸收掉了。
• 列表页、详情页、表单页这些高频页面类型，都有预设的可复用骨架。
• 网络请求、缓存、错误处理这些横切关注点，框架替你兜底，业务开发者只需要关心业务本身。

1.3 选型清单：哪些 Jetpack 组件进框架，哪些不进

Jetpack 是个大杂烩，不是每个组件都适合纳入快速开发框架。我在选型时坚持一个原则：只选那些能明确解决一类问题、且长期维护稳定的组件。最终进入框架核心的组件有这些：

另外像 Paging3、WorkManager、Hilt 这些组件，我摘出来放在"可选引入"清单里。不是它们不好，而是它们在快速开发框架的语境下，往往需要配合特定的业务形态。比如 Paging3，如果你主要是简单的分页列表，自己封装一个几十行的分页加载器反而更好用；Hilt 适合大型多模块项目，但小团队上手成本并不低。后面我会单独讲什么时候该引入它们。

2. 架构分层：让 MVVM 真正落地的关键

2.1 分层模型：UI层、ViewModel层、仓库层、数据层

这套框架沿用了经典的四层结构。数据从最底层往上流，事件从上往下发，每一层的职责边界非常清楚。

数据层是纯粹的来源管理，包含网络 API、Room 数据库、DataStore、文件缓存。它不关心数据给谁用，只负责提供数据。仓库层是唯一被 ViewModel 依赖的入口，它决定数据从网络拿还是从缓存拿，决定了缓存策略和更新策略。ViewModel 层不直接访问任何数据源，所有的数据请求都通过仓库接口。UI 层只负责渲染状态、转发用户事件，不做任何业务决策。

这个分层听起来是常识，但实际上很多快速开发框架的问题恰恰出在分层不彻底。举个例子，有些人图省事，在 ViewModel 里直接调用 Retrofit 接口，仓库层改成了透传层。第一版确实快，可一旦你要在多个 ViewModel 里复用同一份数据，或者要加缓存，就会到处改代码。真正能称得上"快速开发框架"的，不是省掉仓库层，而是把仓库层设计得让开发者几乎不怎么需要写重复逻辑。

2.2 单向数据流与状态建模

状态管理是 MVVM 里最容易出问题的地方，因为它决定了 UI 和 ViewModel 之间的通信方式。我用一句话概括这套框架里的数据流：UI 不修改数据，只发射意图；ViewModel 处理意图，产出新状态；UI 收集状态，完成渲染。

每个 ViewModel 必须暴露一个不可变的 UI 状态对象，我统一使用 data class 承载。比如一个订单详情页，状态是这样的：

data class OrderDetailUiState( val loading: Boolean = false, val orderInfo: OrderInfo? = null, val errorMessage: String? = null, val refreshing: Boolean = false )

禁止在页面里直接创建状态对象，也禁止 ViewModel 暴露 Mutable 类型给 UI。UI 拿到的是 StateFlow，是只读的。这样做的意义不是逼你写一堆范式代码，而是在事件来源变多的时候（下拉刷新、点击重试、外部通知更新），状态依然有唯一真源，不会出现多个地方各改各的导致 UI 错乱。

2.3 ViewModel 生命周期与协程作用域

ViewModel 的生命周期绑定是这套框架的安全底线。所有异步任务，只要是在 ViewModel 里发起的，统一走 viewModelScope。ViewModel 销毁时，协程自动取消，不会因为任务完成了才回来更新一个不存在的界面而崩溃。

这里特别需要说明的是协程作用域的嵌套问题。我见过很多框架把网络请求放在一个自定义的 CoroutineScope 里，然后手动管理取消时机，这是很危险的。比如你在一个 long-running 请求途中用户退出了页面，如果 Scope 没被取消，请求返回后就会更新状态，然后 UI 观察者收到通知，试图操作销毁的 View。viewModelScope 自动解决了 90% 的这类问题，剩下 10% 是你在普通类里发的协程，建议也尽量用 CoroutineScope() + SupervisorJob() 手动管理，而不是放任不管。

3. 核心封装：Base 类与状态处理就是生产力的来源

3.1 BaseViewModel 的设计：状态、事件、Loading 的标准化

BaseViewModel 是框架的心脏。所有业务 ViewModel 都继承它，它可以保证每个页面都有统一的响应式数据出口。我重点封装了三类基础设施：

• 界面状态 StateFlow：一个MutableStateFlow，配合统一的 UiState 约束。
• 一次性事件 SharedFlow：用于发送 Toast、跳转、滚动到顶部这类不该被重复消费的事件，replay 设为 0，防止配置变更后事件重放。
• 错误消息标准化：网络层抛出的任何异常都被框架捕获成一个ErrorEntity，带错误码、错误信息、是否可重试标记。

abstract class BaseViewModel<UiState> : ViewModel() { private val _uiState = MutableStateFlow(initialUiState()) val uiState: StateFlow<UiState> = _uiState.asStateFlow() private val _uiEvent = MutableSharedFlow<UiEvent>(extraBufferCapacity = 8) val uiEvent: SharedFlow<UiEvent> = _uiEvent.asSharedFlow() protected fun updateState(reduce: (UiState) -> UiState) { _uiState.update(reduce) } protected fun sendEvent(event: UiEvent) { _uiEvent.emit(event) } }

这套封装看起来朴素，但是省掉了很多重复代码。以前每个页面要手写两个 LiveData，一个管数据一个管事件，还要头痛粘性事件。现在全部统一走这两条流，新页面的 ViewModel 模板基本只有业务逻辑。

3.2 BaseActivity 与 BaseFragment：ViewBinding 和状态收集的标准姿势

ViewBinding 默认开启以后，每个布局都会生成一个 Binding 类。如果你不在 base 类里统一处理，很容易写出binding = ActivityXxxBinding.inflate(layoutInflater)这种每个页面重复的代码。我在 BaseActivity 里定义了抽象方法inflateBinding()，子类只需要返回 binding 实例，其余 setContentView 全部由父类完成。Fragment 也同理。

状态收集这里有个重要细节：不建议在 onCreate 里直接collect，也不建议用launchWhenStarted。正确姿势是用repeatOnLifecycle(Lifecycle.State.STARTED)：

override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) lifecycleScope.launch { repeatOnLifecycle(Lifecycle.State.STARTED) { viewModel.uiState.collect { state -> renderState(state) } } } }

repeatOnLifecycle会在页面进入 STARTED 时开启收集，进入 STOPPED 时取消收集，从而避免后台时界面收到状态更新还去做耗时操作。这和launchWhenStarted有本质区别，前者是真正的取消，后者只是挂起。在快速开发框架里，我强制使用前者并把这规则写进了团队规范。

3.3 网络层统一处理：Loading、Error、Empty 三态分离

网络层是业务代码最密集也是重复代码最多的地方。每个页面请求接口，都要处理 loading、失败 toast、空数据展示。这套框架把这三个状态直接建模进 UiState 里，并且封装了一个通用的请求执行函数：

protected fun <T> executeRequest( block: suspend () -> ApiResponse<T>, onSuccess: (T) -> Unit, showLoading: Boolean = true ) { viewModelScope.launch { if (showLoading) updateState { it.copy(loading = true) } when (val result = safeApiCall(block)) { is ApiResult.Success -> onSuccess(result.data) is ApiResult.Error -> handleError(result.error) } updateState { it.copy(loading = false) } } }

safeApiCall内部封装了异常捕获和错误类型转换。连接超时、解析失败、HTTP 错误码、业务错误码，统一映射为 ErrorEntity。这样做有两个好处：其一，业务开发者再也不需要在 ViewModel 里写 try-catch；其二，错误处理策略全局可配，如果产品要求所有接口错误都弹统一提示，只需要改一处。

3.4 为什么用 StateFlow 而不是 LiveData

这个问题几乎每个用 Jetpack 的团队都会讨论。LiveData 有它的价值，但在这套框架里我选 StateFlow 有几个硬理由。

第一，生命周期感知。LiveData 的优势是自动感知生命周期，但这套框架已经用 repeatOnLifecycle 统一管理了收集，StateFlow 不会把事件分发给后台的 UI，这个优势其实被覆盖了。

第二，与协程生态融合。Retrofit 的 suspend 函数、Room 的 Flow 查询、Flow 的各种操作符（map、filter、transform），StateFlow 是天然的无缝衔接。LiveData 每次要转成 Flow 还要绕一道。

第三，数据一致性。StateFlow 的状态值独立于收集者，页面即使销毁重建，ViewModel 里的数据依然保留，新页面订阅时立刻拿到最新值。加上distinctUntilChanged的特性，重复值不会二次触发渲染，这在我们处理列表刷新时有奇效。

4. 快速开发的基础设施：高频页面类型的模板化

4.1 列表页通用化：一个 RecyclerView + 统一 Adapter 基类

列表页是移动端最普遍的页面类型。如果不做抽象，每个列表页要写 RecyclerView、Adapter、ViewHolder、ItemDecoration、分页加载，工作量巨大且容易出错。框架里我封装了 BaseListFragment 和 BaseListAdapter。

BaseListFragment 内置了：

• SwipeRefreshLayout 和 RecyclerView 的初始化。
• 上拉加载更多的触发逻辑。
• 空视图和错误视图的切换。
• 分页状态机管理，加载下一页中、没有更多数据、加载失败可重试。

BaseListAdapter 基于 ListAdapter 封装，需要实现 DiffUtil.ItemCallback。业务页面只需要告诉框架"我的 item 是什么、怎么绑"，其他全部走默认行为。在我之前某个数据列表模块上，以前一个列表页从零到交付要 3 到 4 天，用这套框架后基本半天搞定，剩下时间都花在真业务逻辑上。

列表分页我尤其要说一下。Paging3 官方组件适合比较复杂的列表场景，比如有 header/footer、需要多数据源。但如果只是简单的接口分页，Paging3 反而引入太多概念。框架里的分页是手动实现的，核心是一个状态机：

• 空闲时下拉或上滑触发加载。
• 加载中时屏蔽重复触发。
• 返回空列表则标记不再加载更多。
• 失败时保留旧数据，只提示错误并提供重试。

4.2 表单页与详情页的通用逻辑

表单页的痛点在于校验、提交、清空、加载初始数据。详情页的痛点在于传参、加载、错误重试、刷新。这两类页面在业务里出现频率极高，如果每个都从零开始写，只会让项目体量膨胀。

框架里做了一个BaseFormActivity，把所有 EditText 的校验逻辑收敛到统一的表单条目模型里，每一项记录值、校验规则、错误提示。提交时自动遍历校验，失败则定位到第一个错误项并聚焦。开发一个新增/编辑页时，只需要定义条目列表和提交时如何组装请求体。

详情页则复用 BaseDetailFragment，它自带进入页面时自动加载数据、加载失败时全屏错误和重试按钮、下拉刷新重置状态。业务上只需要实现loadDetail()返回数据并将它渲染出来。

4.3 Navigation + 单 Activity 架构的取舍

框架默认采用单 Activity 多 Fragment 架构，页面跳转使用 Navigation Component。有人会问为什么还要用 Navigation，我自己手动管理 Fragment 事务不就行了？手动管理的问题在于，返回栈的层级状态、Fragment 重建、动画、深链都需要自己照顾，而 Navigation 把这些全部标准化了。

更重要的是 Navigation 搭配 Fragment 的 ViewModel 作用域：navGraphViewModels()可以让一个业务流程里的多个 Fragment 共享同一个 ViewModel。这在多步骤表单、商品购买流程里非常好用，状态在页面跳转中不会丢失，页面间不用通过 arguments 传一堆复杂的临时数据。

Navigation 的坑也不是没有。最明显的是它丢失了 Fragment 原有的灵活返回逻辑，比如有些页面返回时不想 pop，而是想弹个 Dialog。所以我封装了一个统一的导航治理函数：跳转前明确指定 popUpTo 和 launchSingleTop 参数，避免栈里积压重复页面。

4.4 依赖注入：Hilt 进不进框架

依赖注入是绕不开的话题。有人迷信 Hilt，有人完全手写。我最终的判断是：框架核心不嵌入 Hilt，但预留接入点。这不是说 Hilt 不好，而是考虑到快速开发框架的目标是降低接入成本。Hilt 的引入意味着 APT 处理、模块改造、编译时间增加，对小项目初期负担偏大。

框架里用更轻量的方式实现了"借接口造依赖"的容器，就是一个简单的 ServiceLocator。它不像 Hilt 那样做编译期检查，但对于大部分业务场景足够了。比如网络层、数据库、配置存储这些全局单例，通过 ServiceLocator 提供，业务模块只需要请求接口，不关心具体实现。

如果项目体量真的到了几十个模块、几百个页面，再迁移 Hilt 也不迟，因为这套框架的仓库层接口风格已经准备好了，迁移主要工作量在替换构造入口，而不是重写业务代码。

5. 从零搭建这套框架的实操复盘

5.1 工程结构与模块划分

框架的工程结构不是把代码全堆在一个 app 模块里，而是采用多模块。我按依赖方向把模块拆成三层：

最底层是core-common和core-data-source，存放基础工具、网络层、数据库、DataStore，不依赖任何业务。中间层是core-model和core-repository，定义业务数据模型和仓库接口，依赖数据层。最上层是各个业务模块，比如feature-home、feature-order、feature-profile，依赖中间层。

每个 feature 模块内部再按 MVVM 分包：

feature-order/ ├── data/ # 本模块的仓库实现 ├── model/ # 本模块的 UI 模型 ├── ui/ # Fragment、Adapter、Binding ├── vmm/ # ViewModel └── navigation/ # 模块内路由

这样拆的好处是编译隔离清晰，改动一个业务模块不会导致全项目重编译，依赖方向清晰后也不会出现环依赖。对新入职的同事来说，一眼就能看出一个功能包含哪些代码。

5.2 关键配置与基础依赖清单

构建这套框架，基础依赖是版本统一管理的。我把各个 Jetpack 组件的版本放在 Gradle version catalog 里，避免出现升级不同步的问题。核心依赖大致如下：

implementation(platform("org.jetbrains.kotlinx:kotlinx-coroutines-bom:5.0.1")) implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android") implementation("androidx.core:core-ktx:8.0.1") implementation("androidx.lifecycle:lifecycle-viewmodel-ktx:4.0.1") implementation("androidx.lifecycle:lifecycle-runtime-ktx:4.0.1") implementation("androidx.navigation:navigation-fragment-ktx:3.4.3") implementation("androidx.navigation:navigation-ui-ktx:3.4.3") implementation("androidx.room:room-ktx:8.2.2") implementation("androidx.datastore:datastore-preferences:5.0.1") implementation("androidx.activity:activity-ktx:5.3.1") implementation("androidx.fragment:fragment-ktx:4.5.1")

Retrofit 和 OkHttp 是网络层标配，配合 kotlinx-serialization 做 JSON 解析。日志拦截器只在 debug 环境开启，release 环境关闭，避免敏感信息暴露。同时给 OkHttp 设置了统一的超时时间（连接 10s、读 30s、写 30s），这是线上运营多轮以后调出来的经验值，太短容易误判弱网，太长用户等待太久。

5.3 一个业务页面的完整落盘样例

我拿一个"公告列表页"来演示这套框架的新页面开发路径。首先定义 UI 状态，继承 BaseViewModel 写业务逻辑：

class AnnouncementViewModel : BaseViewModel<AnnouncementUiState>() { private val repository: AnnouncementRepository = ServiceLocator.get() override fun initialUiState(): AnnouncementUiState = AnnouncementUiState() fun loadAnnouncements(forceRefresh: Boolean = false) { executeRequest( showLoading = true, block = { repository.getAnnouncements(forceRefresh) } ) { list -> updateState { it.copy(items = list, hasMore = list.isNotEmpty()) } } } fun onItemClick(item: AnnouncementItem) { sendEvent(AnnouncementEvent.OpenDetail(item.id)) } }

然后 Fragment 继承 BaseListFragment，实现渲染与点击事件：

class AnnouncementFragment : BaseListFragment<AnnouncementItem, AnnouncementViewModel>() { override fun renderItems(items: List<AnnouncementItem>) { adapter.submitList(items) } override fun onItemClick(item: AnnouncementItem, position: Int) { viewModel.onItemClick(item) } }

没有网络请求配置、没有列表适配器初始化、没有生命周期收集代码。整个页面从 ux 稿到可调试状态，理论上一个熟悉框架的开发者可以在 30 分钟内完成。我第一次演示给团队看的时候，好几个同事都觉得我开了什么代码生成工具，其实就是框架把标准化结构吸收了。

6. 常见问题与排查技巧实录

6.1 状态流重复触发异步请求

这是框架用起来之后遇到的第一个高频问题。场景是这样的：页面从 A 跳到 B，再返回 A，发现 A 又重新请求了一次网络。原因在于，界面重新进入 STARTED 状态后，repeatOnLifecycle 重新收集 StateFlow，ViewModel 里的状态被重新获取，然后界面因为状态里的某个字段变化（比如 loading 从 true 变成了 false），触发了按数据请求的逻辑。

解决思路明确：数据展示和动作触发要解耦。框架规定，页面加载数据只能发生在 init 阶段，通过onFirstEnter标识只请求一次。后续从后台回到前台或从其他页面返回时，展示旧数据而不重新请求。如果确实需要下拉刷新，由用户主动触发，而不是状态变化自动触发。这个约定一开始就要写进开发规范，不然后面每个人都踩一遍。

6.2 协程取消不生效，问题出在 try-catch

有一个典型的排查案例：用户快速退出页面，日志里依然看到网络请求发出去并完成了。检查发现，开发者在 executeRequest 的 block 里写了 try-catch，catch 了所有异常并打日志。问题在于协程取消时抛的是 CancellationException，它是协程机制的一部分。如果 catch 了它却没有重新抛出，协程就无法真正进入取消状态，后续的挂起点会继续执行。

标准做法是异常捕获时单独处理 CancellationException：

catch (e: CancellationException) { throw e } catch (e: Exception) { handleError(e) }

我把这条规则直接写进了 safeApiCall 的实现里，后续业务代码里不会再出现这种坑。

6.3 界面状态更新了，但 UI 不动

StateFlow 的distinctUntilChanged特性决定了相同值不会触发收集。状态里如果只修改了一个布尔值，主界面结构不变，UI 可能不重新渲染，这是正常的。但有人曾经遇到，列表数据明明变了，recyclerView 却不更新。最后定位是 adapter 的submitList依赖 DiffUtil，而 DiffUtil 判定两个 item 是否相同是基于 id，业务上 id 没变但内容变了，导致同一个 item 不为 changed。

解决方式是在 item 的 areContentsTheSame 方法里比较全量字段，或者至少比较那些要展示的字段。这个坑在快速复用列表框架时特别容易出现，因为框架把 DiffUtil 生命周期藏起来了。

6.4 进程被杀后页面数据全没了

StateFlow 天然只存在于内存，进程一旦被系统回收，所有状态丢失。恢复是靠 SavedStateHandle 实现的。我在 BaseViewModel 里预留了handleSavedState的入口，让每个 ViewModel 把重建页面所需的最小字段（通常是列表的页码、详情页的 ID、表单已填内容）写入 SavedStateHandle，重建时优先从它恢复，再决定是否需要重新请求。

这在多任务切换时尤其重要，安卓系统在内存压力下经常回收后台 Activity，如果没有 SavedStateHandle 兜底，用户回来后看到的就是一个重新 loading 的页面，体验很差。

6.5 共享 ViewModel 状态被多个页面污染

Navigation + navGraphViewModels 共享 ViewModel 是方便，但也容易踩坑。比如 A 页面加载数据后，把列表塞进共享 ViewModel，跳到 B 页面也去更新同一个状态，返回 A 页面时状态被 B 覆盖了。

这里我给出的原则是：共享 ViewModel 只保存业务流程所需的中间状态，不保存整个页面的最终展示状态。每个页面自己的 UI 状态还是放在自己的 ViewModel 里。如果遇到跨页面复用同一份数据，框架里提供了独立的 Repository 缓存来共享数据，而不是共享 ViewModel。

7. 框架的边界与后续扩展

最后说几个我踩过坑之后的个人体会。这套框架不是万能的，它适合常规的页面与数据流。如果你要做高实时性场景（比如直播弹幕、股票行情），StateFlow 的背压和类似的状态合并需要慎重设计，可能要引入更底层的 Channel 或者独立的事件总线。如果你要做复杂的多级嵌套数据展示，通用 Adapter 也会捉襟见肘，那就需要基于 RecyclerView 做更深的定制。

团队在推广这套框架时也要注意节奏。别指望一次把所有老代码全迁完，我们的做法是"新页面必须用新架构，旧页面路过时顺手迁移"。三个月后，新页面占比超过一半，框架优势就很明显了。开发效率确实肉眼可见地提升，更重要的是，代码风格统一了，互相 review 时讨论的都是业务逻辑而不是又有人违反某个约定。

我给这套框架定的一个原则是：它能解决 80% 页面的 80% 常规需求就够了，剩下 20% 的复杂页面允许按场景局部扩展。框架不是牢笼，而是地基，地基稳了，盖多高的楼都是你自己的事。