Paging RemoteMediator 实战：建立离线优先的分页列表

只从网络分页，断网后页面就会失去内容；只从数据库读取，又需要自己处理拉取、缓存和翻页。当 UI 同时依赖网络与本地时会出现闪烁、缓存不一致甚至错误提示频繁弹出的情况，使使用者体验大打折扣。怎么说呢， 解决思路： 将界面始终观察 Room 的 PagingSource。由 RemoteMediator 在后台决定何时拉取并写入数据库。这使得“显示”完全由本地驱动，“同步”完全由后台完成。不过，下面以资讯列表为例，逐步实现可刷新、可续页、可离线浏览的完整方案。并解释最容易出错的一致性问题。

为什么让数据库成为唯一数据源？

• UI 始终订阅 Room PagingSource；老实说，
• 多源并发导致 UI 突然空白或错误提示！，
• RemoteMediator 决定何时拉取网络，并在事务中写入 Room；，
• Room 更新后自动使旧 PagingSource 无效，让 UI 获得最新快照；
• UI 永远只读本地快照，无需关心网络状态。
.

此方式避免了多源冲突，使离线与在线走同一方法。​ ​ ​ ​

💡 数据表不应仅存业务实体 如果没有 remote key，会导致无限循环或漏掉最终几条记录！⚠️ 注意，​︎​​︎​​︎​​︎​​︎​​︎​​︎​​︎​​︎​​​​⁠⁠⁠⁠⁠⁠⁠⁠⁠⁠⁠⁠ ⁠ ⁠ ⁠ ⁠ ⁠ ⁠ ⁠ ⁠ ⁠ ⁠ ​⁣⁣⁣⁣⁣⁣⁣⁣⁣⁣⁣⁩
‍‍‍‍‎‏‏‎‏‎‏‎‏‎‎‏‎ ‎ ‎ ‎ ‎ ‏‪​​​​‭‭‭‮‪‫‫‫‫‫ ‫‫ ‫‬‬‬‬‬‬‬‬‬‬‪‫‬ **Business entity table**

/// 存放真正展示的数据
@Entity
data class ArticleEntity(
@PrimaryKey val id : Long。val title : String,val summary : String,val publishedAt : Long )
**Remote key table**
/// 用来记录每条记录相邻页的位置，/// 它不是展示字段，但决定了翻页边界。@Entity
data class ArticleRemoteKey(
@PrimaryKeyval articleId : Long,var previousPage : Int?,var nextPage : Int?)
**⚙️ 使用者痛点②**
如果没有正确维护 remote key，就可能出现：

- APPEND 时认为已经到底而不发请求；‑ PREPEND 时不断重新拉取第一页；‑ 重复插入导致“跳跃”或“死循环”。请务必在事务里同时写入业务表和 remote key。---


@Dao interface ArticleDao {
// 排序一定要稳定，否则翻页期间顺序抖动
@Query(
\"\"\"
SELECT * FROM articles
ORDER BY publishedAt DESC。id DESC
\"\"\")
fun pagingSource : PagingSource
 @Insert
suspend fun upsertAll
@Query
suspend fun clearAll


}

@Dao interface ArticleRemoteKeyDao {
@Query
suspend fun remoteKeyById : ArticleRemoteKey?
 @Insert
suspend fun insertAll
@Query
suspend fun clearAll


}


📦 数据库层须提供事务支持
@Database
abstract class AppDatabase : RoomDatabase{
abstract fun articleDao : ArticleDao
abstract fun keyDao : ArticleRemoteKeyDao
}



负载类型说明：


{@link LoadType#REFRESH}: 首次加载或手动下拉刷新的时候触发;

{@link LoadType#PREPEND}: 尝试向头部追加（此接口一般无前置翻页，可直接结束);

{@link LoadType#APPEND}: 向尾部追加，根据上一次成功返回的 nextPage 来确定下一批请求。
APPEND 时若当前列表为空却立即标记 endOfPaginationReached=true，将永远不再尝试抓取新内容！请返回 false 并等待实际查询完成再做判断。
@OptIn
class ArticlesRemoteMediator(
private val api : ArticlesApi,private val database : AppDatabase ) :
RemoteMediator
{
private val dao = database.articleDao
private val keyDao = database.keyDao
 override suspend fun load(loadType: LoadType。state:PagingState
) =
try {
// ---------- 确定请求哪一页 -----------------
var page:Int?= when{
LoadType.REFRESH -> STARTING_PAGE
LoadType.PREPEND -> return MediatorResult.Success
else -> { // APPEND
state.lastItemOrNull?老实说，.let {last->
keyDao.remoteKeyById?.nextPage
}，说起来，的观点是。return MediatorResult.Success
}
}
// ---------- 拉取 ---------------------------------
var response = api.getArticles
// ---------- 写入 ---------------------------------
database.withTransaction{
if{keyDao.clearAll;dao.clearAll}
// 每条记录都插入对应键值对
response.items.map{dto->dto.toEntity}.let{entities->
dao.upsertAll
keyRepoFromEntities.let{keys->
keyRepo.insertAll
}
}
}
MediatorResult.Success
}catch{MediatoResult.Error}catch{MediatoResult.Error}


}
fun ArticlesDto.toEntity:ArticleEntity={..}
private const STARTING_PAGE=1
fun keyRepoFromEntities:List{..}






刷新时需要清理旧键+旧数据+插入新键+插入新实体，一旦任意一步失败就会留下“有键无值”或“有值无键”的脏态。

若把写操作拆成多步。
即便最终成功也可能在半途中被挂起，从而造成临时空白屏幕或部分更新。

常用方法先完成 API 调用 + 本地 DTO 转换。接下来在同一次 database.withTransaction{} 内执行全部 DB 操作，只要整个事务成功才算一次完整更新。




class ArticlesRepository{
companion object{const const PAGE_SIZE=20}
 @OptIn
internal operator fun invoke: Flow =
Pager(
config=PagingConfig(pageSize=PAGE_SIZE。prefetchDistance=,enablePlaceholders=false),remoteMediator=ArticlesRemoter,pagingSourceFactory={dbAppDb.article.pagingSrc}
).flow



pageSize 必须与服务器分页大小保持一致，否则每次触发都会多余一次请求或者漏掉部分内容。

prefetchDistance 太大容易提前消耗流量。也太小则可能滑到底部还未触发，再也没机会抓到下一批。

placeholders 若服务端能提供总数，可开启占位符；否则建议关闭简化逻辑，





使用 CombinedLoadStates 可以分别查看 local source 与 mediator 状态，以便做出更细粒度 UI 展示：

lifecycleScope.launchWhenStarted{
viewModel.items.collectLatest
}
lifecycleScope.launchWhenStarted{
adapter.loadStateFlow.collectLatest {states->
// 当 mediator 正在 loading 且无任何 item 时显示全屏进度条
binding.progress.isVisible =
states.mediator?.refresh is LoadState.Loading && adapter.itemCount==0 

 binding.swipeRefresh.isRefreshing =
states.mediator?.refresh is LoadState.Loading && adapter.itemCount>0
binding.errorGroup.isVisible =
states.mediator?.refresh is LoadState.Error && adapter.itemCount==0
binding.offlineHint.isVisible =
states.mediator?.refresh is LoadState.Error && adapter.itemCount>0
}


}
adapter.setFooter)
binding.recyclerView.adapter=adapter.withLoadStateFooter


注意：* 当有缓存但 network 错误发生。只保留已有列表并轻量提示即可，不必切换至全屏错误页；只有完全无缓存且 refresh 错误才弹全屏报错。*




默认每次 new Pager 都会执行 REFRESH。如果想短时间内复用已存在缓存，可覆盖 initialize

html


// …override suspend fun initialize: InitializeAction {
return cacheMeta.lastUpdated?.let{ last->
if-last
// 将更新时间写进同一次 transaction 中，以保证 “成功写入 + 更新时间” 原子一致。cacheMeta.updateTime)


根据业务类型调整超时时间。例如价格信息可以短于一分钟，而新闻文章可以长达数小时。






步骤
检查项
常见原因




服务端排序
是否使用固定字段
新增/删除影响位置


主键信息
是否真唯一？其实，
重复 ID 会覆盖


nextPage 写法
是否末尾正确设为 null？怎么说呢，
没设置 → 无限递归


空响应判定
是否识别为空数组为结束？
忽略 →
请求


刷新流程
是否同时清理 keys + entity？
留下脏 Key 或 Data


DAO 排序
与服务器是否保持一致？
翻页顺序错乱




若支持分类/关键词，请为 query 参数生成独立 query_key 并作为 composite primary key：
kotlin
@Entity
data class QueryAwareLocal
@Entity
data class QueryAwareRemotekey

否则切换筛选条件可能拿到上一种条件下遗留的 paging 状态。




使用内存 Room + mock API 可以覆盖以支：

1️⃣ 首次 REFRESH 写入 business & keys
- 验证两张表都有记录且数量匹配
- 验证 order 与预期相符 

2️⃣ REFRESH 替换旧缓存
- 确认 old keys/data 已被删除 

3️⃣ APPEND 正确获取 nextPage 并写回 keys 

4️⃣ 接口返回空数组 → endOfPaginationReached=true 

5️⃣ 网络异常 → 保留旧缓存且未提交 transaction 

6️⃣ 同 ID 重复调用 -> UPDATE 而非 INSERT 

7️⃣ 多个查询参数互不污染 

测试不仅检查 MediatorResult，还应直接查询 DB 验证最终状态。按理说，



🚦🛑🟢🟣🟧🟥🟨🟪⬛⬜ ➜ ⬆️ ⬇️ ➜ ❗️❗️❗️⚙️🏁📱🚀✈️🤖🔒🔐🔥🌐💡📊🔍🎯🔎⛔️🏅🍎🍓🍇🥭🥕🌽🍚🍱🥗🍔🥪☕🍺🍸🥂🎉👨‍💻🚧💬🙌🛒🏆💸🎉📦✉️📞😱🙃😂👍🏾👏🏼🤝🏿❓😕💭👀🙏💭↩️➕➖✖️➗∑⌛⌚⏰⏱〰〱〴〵⊂⊃⊄⊅⊇⊈⊉≦≧≤≥∈∋∩∪⋂⋃∀∃≈≡≅≤≥⇔⇔↔↕↨↩↪⇧⇩⌈⌉⌊⌋⎮⎴⎸⎹┐╭╯▹◀▶◤◥▿│█▢▣▤▥▦▋⑴⑵⑶⑷⑸⑹⑺⓵⓶⓷⓸⓹⓺ⒶⒷⒸⒹⒺⒻⒼⒽ⓫㊀㊁㊂㊃㊄㊅㊆㊇㊈㊉①②③④⑤⑥⑦⑧⑨⑩㈱㈲㈳㈴㈵㈶㈷㈸㈹ⅰⅱⅲⅳⅴⅵⅶⅷⅸⅹᴀʙᴄᴅᴇꜰɢʜɪʤᴋʟᴍɴᴏᴘǫɾˢʈᴜᴠʏᴢᴀʙａｂｃｄｅｆｇｈｉｊＫＭＮＯＰＱＲＳＴＵＶＷＸＹＺＡＢＣＤＥＦＧＨＩＪＫＬＭＮＯＰＡＢＣＤＥＦＧＳＴＵVWSXYYZZ𐌀𐌀𐌀𐌀𐌀𐌀𐌀𐌀𐌀𐌀》《▼▲◆◇○◎△▽☆★♯♭♪♬♩♪♫♭♮♯♫♪﹄﹄﹄﹄﹄﹄﹚﹛﹜﹝﹞︰︱︲︳︴︵︶︷︸︹︺︻︼〉〈※‼‼‼‼‼‼‼‼‽‾〜〓〘〖〝〞〟‥『』〖』「」『」』「」《》〈〉《》『』「」『」『』「」 《》《〉〈〉《》〈〈〈〈〈 』』