罗罗编程学习记录
本页内容 展开查看

07.1.1.6.2 Navigation、WorkManager 与 DataStore

所属:全栈开发面试题库 / 07 端侧与桌面开发 / 07.1 原生移动开发 / 07.1.1 Android / 07.1.1.6 Jetpack 基础与架构

本节要解决的问题

本节覆盖三类 Jetpack 能力:Navigation 负责页面目的地、返回栈与类型安全跳转;WorkManager 负责可延迟、可重试、受约束的后台任务调度;DataStore 负责替代 SharedPreferences 的协程化键值存储。版本基线:Android 14 / compileSdk 34、Kotlin 2.x、Jetpack 最新稳定版;版本敏感行为标「待确认」并写明验证点。

07.1.1.6.2-001 Navigation 组件相比手工 Intent 跳转解决了什么问题?

一句话结论

Navigation 把页面跳转、返回栈管理、参数传递、转场动画与深层链接收敛到统一的导航图与控制器,降低手工 Intent、FragmentTransaction 与回栈标记带来的不一致与崩溃。

概念解释

手工跳转需要自行管理 Fragment 事务、回栈 Flag、参数校验与动画;Navigation 以目的地和动作描述导航关系,由 NavController 维护返回栈。

原理流程

导航图声明目的地与动作
  → NavController.navigate(...)
    → 维护回栈、转场、参数与深链匹配

代码或图示

navController.navigate(R.id.action_list_to_detail)

常见误区

  • 认为 Navigation 只能用于 Fragment;Compose、Activity 也可作为目的地。
  • 用它替代业务路由的全部能力,跨模块深链仍需自行约定。

追问

  • 导航图存哪里?答:XML 资源或 Compose DSL 声明,目的地与动作集中管理。
  • 旧项目迁移路径?答:先在新页面接入 NavHost,旧页面以 Activity/Fragment 目的地包裹,逐步收敛。

07.1.1.6.2-002 导航图中的目的地、动作和参数分别是什么?

一句话结论

目的地(destination)是可到达的页面节点;动作(action)描述从当前目的地出发的跳转关系;参数(argument)定义目的地接收的入参与类型、默认值、是否可空。

概念解释

导航图是一棵节点树:目的地持有布局/Compose 描述与参数声明,动作指向目标目的地并可配置回栈行为与动画。

原理流程

<navigation>
  <destination id="list">
    <action id="to_detail" destination="detail"/>
  </destination>
  <destination id="detail">
    <argument name="id" argType="long" nullable="false"/>
  </destination>
</navigation>

代码或图示

<fragment android:id="@+id/detail" android:name=".DetailFragment">
    <argument android:name="itemId" app:argType="long" android:defaultValue="0L"/>
</fragment>

常见误区

  • 参数只在跳转处传,不在目的地声明,类型校验与默认值缺失。
  • 动作和直接 route 跳转混用,回栈策略不一致。

追问

  • 嵌套图怎么组织?答:<navigation> 可嵌套,子图拥有自己的启动目的地与作用域。
  • 未使用的动作会被校验吗?答:Lint 与导航校验会提示未注册目的地、参数类型不匹配等问题。

07.1.1.6.2-003 NavHost 与 NavController 是什么关系?

一句话结论

NavHost 是承载当前目的地内容的容器(Fragment 容器或 Compose 宿主);NavController 是持有返回栈、当前条目与导航状态的控制器,Host 按 Controller 的当前条目渲染页面。

概念解释

Controller 负责「去哪、回栈怎么变」,Host 负责「把当前条目显示出来」;二者绑定同一导航图。

原理流程

NavController 维护 back stack entries
  → NavHost 观察 currentBackStackEntry
    → 渲染对应目的地内容

代码或图示

val navController = rememberNavController()
NavHost(navController = navController, startDestination = "list") { /* 目的地 */ }

常见误区

  • 在多个地方各自创建 Controller,回栈状态不一致。
  • 把 Controller 当全局单例跨 NavHost 复用。

追问

  • Controller 生命周期跟谁?答:绑定所属 Host/Activity,随宿主销毁释放。
  • 如何拿到当前条目?答:currentBackStackEntryFlow 或 currentBackStackEntry。

07.1.1.6.2-004 目的地支持哪些类型?

一句话结论

支持 Fragment、Compose 页面、Activity 以及嵌套导航图;每种目的地在导航图中声明对应的实现类/路由与参数,Controller 跳转时按类型实例化或切换。

概念解释

混合栈场景常见:老页面是 Fragment/Activity 目的地,新页面是 Compose 目的地;嵌套图作为逻辑分组与图级作用域边界。

原理流程

目的地类型
  ├─ fragment → Fragment 实例
  ├─ activity → Intent 启动
  ├─ composable → Compose 页面
  └─ navigation → 嵌套子图

代码或图示

composable("detail/{itemId}") { backStackEntry ->
    DetailScreen(backStackEntry.arguments?.getString("itemId"))
}

常见误区

  • Activity 目的地返回时回栈行为与 Fragment 不一致,未显式处理。
  • 把整段业务塞进嵌套图却没设独立启动目的地。

追问

  • 外部 Activity 能作为目的地吗?答:可以声明 Activity 目的地,跨应用跳转仍走 Intent/deep link。
  • 嵌套图能否独立导航?答:图内动作只在图回栈范围内生效。

07.1.1.6.2-005 Safe Args 如何实现类型安全的参数传递?

一句话结论

Safe Args 根据导航图参数声明生成 Directions 与 Args 类,跳转时通过生成类传参,目的地从生成的 Args 对象读取,编译期检查类型与必填性。

概念解释

普通 Bundle 传参靠字符串键与强转,易拼写错、类型错;生成类把键和类型固化为代码字段,减少运行时崩溃。

原理流程

导航图声明 argument
  → 编译器生成 Directions/Args 类
    → navigate(方向对象);目的地解析 Args

代码或图示

val action = ListFragmentDirections.toDetail(itemId = 7L)
navController.navigate(action)

// 目的地侧
val args = DetailFragmentArgs.fromSavedStateHandle(savedStateHandle)
args.itemId

常见误区

  • 引入插件后仍手写 Bundle 键,失去类型安全收益。
  • 改了参数名却没重新生成,方向类字段对不上。

追问

  • Safe Args 适用 Fragment/Activity 图吗?答:适用;Compose 场景可用类型安全路由或生成参数解析(方案待按版本确认)。
  • 插件坐标是什么?答:导航 Safe Args Gradle 插件,具体版本与 BOM 对齐官方文档(待确认)。

07.1.1.6.2-006 导航参数的类型、默认值与可空性如何声明?

一句话结论

参数可声明基础类型、String、Parcelable、Serializable、枚举等;可为不可空并给默认值,也可标记 nullable;类型不匹配或缺必填参数会在校验/运行时暴露问题。

概念解释

声明决定生成类字段的类型与可空性;深链场景中 URL 片段默认是 String,需要显式转 long/int 并校验。

原理流程

argument: name + argType + nullable + defaultValue
  → 生成字段类型;深链未提供值时用默认值

代码或图示

<argument android:name="itemId" app:argType="long" android:defaultValue="-1L"/>
<argument android:name="title" app:argType="string" android:nullable="true"/>

常见误区

  • 深链传入字符串数字,目的地直接强转 long 崩溃。
  • Parcelable 字段类加载版本不兼容,恢复时反序列化失败。

追问

  • 集合类型怎么传?答:基础集合可作为参数或放进 Bundle;复杂对象优先传 ID 再加载。
  • 参数能存大图/大列表吗?答:不能,Bundle 受事务大小限制。

07.1.1.6.2-007 用 Safe Args 和直接读 Bundle 怎么取舍?

一句话结论

页面内参数解析首选 Safe Args 生成类获得编译期类型检查;跨模块或动态路由场景可保留 Bundle 读取,但必须集中做类型校验与默认值兜底。

概念解释

生成类依赖导航图与插件,适合稳定的模块内导航;动态深链、跨模块约定路由更灵活,但校验责任回到业务代码。

原理流程

模块内稳定导航 → Safe Args
动态 / 跨模块路由 → Bundle + 校验 + 默认值

代码或图示

// 直接读取时显式校验
val id = backStackEntry.arguments?.getString("itemId")?.toLongOrNull()
    ?: run { navController.popBackStack(); return }

常见误区

  • 直接 getLong("id") 不判空,键缺失返回默认 0 被当成合法 ID。
  • 两边各写一套参数键,重构时漏改。

追问

  • 类型安全路由新方案是什么?答:基于 Kotlin Serialization 的路由定义,API 与稳定性以官方文档为准(待确认)。
  • 参数集中解析放哪?答:ViewModel 构造时从 SavedStateHandle 读取并校验。

07.1.1.6.2-008 Navigation 的返回栈模型是怎样的?

一句话结论

Controller 维护一个回栈条目列表:前进压入新条目,返回弹出顶部条目;每个条目保存目的地状态、参数与自身作用域,栈底为启动目的地或任务根。

概念解释

回栈与系统任务栈对应但由导航图管理;弹出动作可一次回退多个目的地,popUpTo 控制回退到哪个节点。

原理流程

navigate(A) → [A]
navigate(B) → [A, B]
navigate(C) → [A, B, C]
返回        → [A, B]

代码或图示

// 回到栈底
navController.popBackStack()

常见误区

  • 以为导航回栈和 Activity 任务栈完全等价,混合 Activity 目的地时行为需实测。
  • 重复压入同一页面形成冗余栈层级。

追问

  • 条目状态在回栈中保留吗?答:目的地 ViewModel 与视图状态按作用域保留;弹出销毁后清除。
  • 栈空了再返回会怎样?答:按系统返回行为退出宿主或回调 OnBackPressed。

07.1.1.6.2-009 有哪些导航跳转方式?

一句话结论

可按动作 ID、目的地 ID、route 字符串或 deep link 跳转;Fragment 图常用 action/id,Compose 常用 route 声明式导航,深链通过 URI 匹配目的地。

概念解释

每种方式最终都交给 Controller 压入回栈;route 方式把参数嵌在路径模板里,action 方式由生成方向对象携带参数。

原理流程

navigate(action) / navigate(id) / navigate(route) / navigate(deepLinkUri)
  → 解析目的地 → 压栈

代码或图示

navController.navigate("detail/7")
navController.navigate("profile?tab=orders")

常见误区

  • route 字符串散落各处,未集中定义路由常量。
  • 跳转前不判断当前目的地,重复点击压入多层。

追问

  • 动作 ID 与 route 能混用吗?答:同一图内可并存,但回栈策略要统一约定。
  • 跨模块 route 如何约定?答:在公共模块定义路由常量与参数契约。

07.1.1.6.2-010 popUpTo 与 popUpToInclusive 如何控制回退?

一句话结论

popUpTo 让跳转时回退到指定目的地;inclusive=true 连该目的地一并弹出,false 保留它作为新栈底;常用于登录后清掉登录栈、主页只保留一个实例。

概念解释

跳转动作携带回栈配置:目标压入前先弹出目标区间条目;inclusive 决定边界节点是否保留。

原理流程

[A, B, C] → navigate(D, popUpTo=A, inclusive=false) → [A, D]
[A, B, C] → navigate(D, popUpTo=A, inclusive=true)  → [D]

代码或图示

navController.navigate("home") {
    popUpTo("login") { inclusive = true }
}

常见误区

  • inclusive 漏写,登录页残留在栈底,返回时又回到登录。
  • popUpTo 指向不存在的 route,回栈行为异常。

追问

  • 清栈到启动目的地怎么写?答:popUpTo(startDestination) { inclusive = true } 按业务需要决定是否保留根。
  • popUpTo 与 launchSingleTop 能组合吗?答:可以,分别控制回退与顶部去重。

07.1.1.6.2-011 launchSingleTop 在什么场景使用?

一句话结论

目标目的地已在回栈顶部时,launchSingleTop 复用顶部条目而不是再压一个相同页面;适合列表点进详情、重复打开同一主页等场景。

概念解释

它只判断栈顶是否为同一目的地,不清理栈中其他同名条目;与 popUpTo 配合可实现「单实例主页」。

原理流程

[A, Detail] → 再进 Detail
  singleTop=true → 复用 [A, Detail]
  singleTop=false → [A, Detail, Detail]

代码或图示

navController.navigate("detail/7") {
    launchSingleTop = true
}

常见误区

  • 以为 singleTop 保证全局只有一个实例,栈中下层同名页面仍会保留。
  • 重复点击时只靠 singleTop,未做防抖,快速连点仍可能在首帧前压入多条。

追问

  • 与 Activity 的 singleTop 启动模式对应吗?答:语义相近,作用域是导航回栈;Activity 目的地仍受其启动模式影响。
  • 新参数到达复用条目时如何刷新?答:观察条目参数/状态流,或在目的地重新加载。

07.1.1.6.2-012 startDestination 如何决定回栈根?

一句话结论

嵌套图的 startDestination 是进入该图时默认压入的第一个条目;宿主图的启动目的地构成应用回栈根,深链进入时可按配置重建包含根条目的栈。

概念解释

启动目的地不是「唯一能返回的根」,而是图入口;多图嵌套时每层都有自己的 startDestination。

原理流程

进入图 → 压入 startDestination
  → 后续动作在图内导航
    → 弹出图时回到父图条目

代码或图示

<navigation app:startDestination="list">
    <fragment android:id="@+id/list"/>
    <fragment android:id="@+id/detail"/>
</navigation>

常见误区

  • 深链直达深层页面却没配置回到根的栈,返回时直接退出。
  • 子图 startDestination 与父图动作指向不一致。

追问

  • 启动目的地能动态改吗?答:可按登录状态在宿主导航组装时选择不同起始 route。
  • 进程恢复后 startDestination 如何还原?答:按保存的回栈状态重建,未保存部分按深链配置恢复。

07.1.1.6.2-013 嵌套导航图解决什么问题?

一句话结论

嵌套图把一组相关目的地分组,拥有独立启动目的地、动作与图级 ViewModel 作用域;便于模块化导航、隔离返回栈范围与复用业务流程。

概念解释

子图对外只暴露入口,内部目的地不被父图直接引用;进入子图后回退在子图内进行,弹出子图回到父图。

原理流程

宿主图
  └─ 子图 orders(startDestination=orderList)
       ├─ orderList
       └─ orderDetail

代码或图示

navigation(startDestination = "orders", route = "orders_graph") {
    composable("orderList") { }
    composable("orderDetail/{id}") { }
}

常见误区

  • 子图内目的地被父图动作直接跳转,破坏分组边界。
  • 图级共享状态乱放图级 ViewModel,跨图残留。

追问

  • 子图能单独导出复用吗?答:可在公共模块定义,宿主挂载;参数与深链契约一并暴露。
  • 图级作用域何时清除?答:子图条目弹出宿主时。

一句话结论

在目的地声明 navDeepLink,配置 URI 模板、动作与类别;外部 Intent 匹配模板时 Controller 可直接到达该目的地,并按参数占位解析入参。

概念解释

深链把外部链接、通知、快捷方式映射到内部目的地;URI 中的 {placeholder} 对应导航参数,未匹配默认值按声明处理。

原理流程

外部 URI https://host/detail/7
  → 匹配 navDeepLink 模板 detail/{id}
    → 解析 id → 压入对应目的地

代码或图示

<deepLink app:uri="https://example.com/detail/{itemId}"/>

常见误区

  • 只配导航深链没在 Manifest 声明 intent-filter,应用外 Intent 无法到达。
  • URI 参数类型未校验,数字段收到非数字崩溃。

追问

  • 深链能重建上游栈吗?答:可通过导航回栈配置或 app:defaultNavDeepLink 行为指定;具体栈重建规则以文档为准(待确认)。
  • 模板支持查询参数吗?答:支持 query 参数映射到 argument,语法以导航文档为准。

07.1.1.6.2-015 深链参数占位与默认值如何配合?

一句话结论

URI 模板中的占位符在匹配时填入对应参数;未出现在链接中的参数使用声明默认值或可空;必填参数缺失时应在目的地做兜底,不能假设链接一定完整。

概念解释

深链来源不可控(邮件、推送、浏览器),参数可能缺、可能格式错;目的地入口必须校验并回退到安全页面。

原理流程

URI → 模板匹配 → 占位符取值
  → 缺省参数用默认值
    → 目的地校验失败 → 回退/空态

代码或图示

val id = backStackEntry.arguments?.getString("itemId")?.toLongOrNull()
if (id == null) { navController.popBackStack(); return }

常见误区

  • 占位符参数声明不可空,但深链可能不带,导致解析失败。
  • 把查询参数当路径占位符读取,键取不到。

追问

  • 编码后的中文参数怎么解?答:URI 解码由框架/系统处理,业务侧按字符串读取再校验。
  • 深链携带令牌类敏感参数注意什么?答:避免出现在日志、截图与历史栈中。

07.1.1.6.2-016 转场动画如何配置?

一句话结论

动作可配置进入、退出、弹出与恢复四个动画,作用于目的地切换;Fragment 目的地用资源动画,Compose 目的地可用动画过渡 API 按条目状态切换。

概念解释

动画与导航动作绑定,不同跳转可配不同过渡;返回时使用弹出/恢复动画,方向与前进相反。

原理流程

navigate → enterAnim(新进入)+ exitAnim(旧退出)
返回 → popEnterAnim(恢复)+ popExitAnim(弹出)

代码或图示

<action android:id="@+id/to_detail" app:destination="@id/detail">
    <anim app:enterAnim="@anim/slide_in_right"/>
    <anim app:exitAnim="@anim/slide_out_left"/>
</action>

常见误区

  • 只配前进动画,返回时无过渡或方向反了。
  • Compose 页面仍引用 Fragment 动画资源,不生效。

追问

  • 共享元素过渡怎么接?答:Fragment 用 shared element transition;Compose 用共享元素动画 API,能力边界随版本演进(待确认)。
  • 动画时长影响性能吗?答:复杂移动/缩放动画在低端机可能掉帧,需压测。

07.1.1.6.2-017 NavController 的生命周期状态如何管理?

一句话结论

Controller 与宿主生命周期绑定,其回栈条目各自是 LifecycleOwner;导航切换时旧条目进入 STOPPED/DESTROYED,新条目进入 STARTED/RESUMED,观察者按条目生命周期订阅。

概念解释

不要在 Controller 销毁后保留其条目引用;条目状态流可观察导航切换,用于埋点、可见性统计。

原理流程

宿主 Lifecycle
  → 条目 A/B 各自 LifecycleOwner
    → 切换:A STOPPED,B RESUMED

代码或图示

navController.currentBackStackEntryFlow.collect { entry ->
    trackScreen(entry.destination.id)
}

常见误区

  • 跨页面持有旧条目 ViewModel 引用,条目销毁后仍访问。
  • 用 Controller 单例跨 Activity 共享回栈。

追问

  • 条目生命周期何时 DESTROYED?答:弹出回栈或宿主销毁时。
  • 如何监听页面可见性?答:订阅条目的 lifecycle 或 currentBackStackEntryFlow。

07.1.1.6.2-018 currentBackStackEntry 与 previousBackStackEntry 有什么区别?

一句话结论

currentBackStackEntry 是栈顶当前展示条目;previousBackStackEntry 是其下方相邻条目,常用于向返回目的地回传结果;两者都可能为 null。

概念解释

条目持有参数、保存状态与 ViewModelStore;结果回传可通过前一条目的 SavedStateHandle 或共享作用域,而不是直接持有页面实例。

原理流程

栈 [A, B]
  → current = B
  → previous = A
B 结束 → 写入 A 的结果 → 返回 A 观察

代码或图示

val savedStateHandle = previousBackStackEntry?.savedStateHandle
savedStateHandle?.set("result", payload)
navController.popBackStack()

常见误区

  • 直接强转前一个 Fragment/Activity 拿接口回调。
  • 结果写入后不清除,下次进入再次读到旧结果。

追问

  • 导航结果 API 推荐方式?答:条目 SavedStateHandle 或官方结果机制;具体 API 版本以文档为准(待确认)。
  • 观察前一条目结果绑谁的生命周期?答:A 重新成为 current 后订阅其视图 Owner。

07.1.1.6.2-019 跨目的地回传结果有哪些方式?

一句话结论

可通过前一条目 SavedStateHandle 写结果、导航结果 API、共同作用域 ViewModel 或仓库事件流;选择依据是结果生命周期与是否需要跨多个目的地。

概念解释

一次性页面结果用条目回传;需要共享的筛选/会话状态提升到图级或 Activity 作用域;持久结果落仓库。

原理流程

子页面产生结果
  → 写入前一条目 Handle / 共享 ViewModel / 仓库
    → 返回页面订阅更新

代码或图示

// 子页面
navController.previousBackStackEntry
    ?.savedStateHandle?.set("selected", option)
navController.popBackStack()

常见误区

  • 结果挂静态字段,再次进入残留。
  • 用 Activity 回调接口硬耦合子页面与宿主。

追问

  • 结果需要持久化吗?答:需要跨会话则写仓库/存储;一次性选择只在回栈内传递。
  • 多步流程结果怎么传?答:收敛到共同图级 ViewModel,各目的地读写状态。

07.1.1.6.2-020 Compose 版导航与 Fragment 版导航有什么差异?

一句话结论

Fragment 版在 XML 导航图中声明目的地与 action,事务由框架管理;Compose 版用 NavHost + route DSL 声明 composable 目的地,参数从 backStackEntry.arguments 读取,动画用 Compose 动画体系。

概念解释

两者共享 Controller 与回栈模型;差异主要在目的地声明方式、参数读取与转场实现,混合栈中可共存。

原理流程

Fragment:XML 图 + Directions/Args
Compose:route 字符串 DSL + arguments 解析
共同:NavController + 回栈条目 + 条目作用域

代码或图示

NavHost(navController, startDestination = "list") {
    composable("list") { ListScreen() }
    composable("detail/{id}") { entry -> DetailScreen(entry) }
}

常见误区

  • 在 Compose 目的地里找 Fragment Args 生成类。
  • 把 Fragment 动画资源直接套到 Compose 过渡。

追问

  • 混合导航如何过渡?答:Fragment 目的地可承载 Compose 视图,反之按宿主类型接入;动画分别实现。
  • 类型安全路由在 Compose 侧如何推进?答:基于序列化的路由对象替代字符串模板,API 稳定性待确认。

07.1.1.6.2-021 底部导航多 Tab 如何组织回栈?

一句话结论

每个 Tab 可保留独立回栈(多返回栈),切换 Tab 时不销毁其他 Tab 的栈与状态;Navigation 支持按 Tab 配置嵌套图与状态保存,避免切回首页重置页面。

概念解释

单栈方案切换 Tab 会弹出旧 Tab 层级,状态丢失;多返回栈为各 Tab 维护独立 entry 栈,符合底部导航习惯。

原理流程

Tab A 栈 [A1, A2]
Tab B 栈 [B1]
切换:展示对应栈,其他栈暂停不销毁

代码或图示

bottomNavigationBar.setOnItemSelectedListener { item ->
    navController.navigate(item.itemId) {
        popUpTo(navController.graph.findStartDestination().id) { saveState = true }
        launchSingleTop = true
        restoreState = true
    }
}

常见误区

  • saveState/restoreState 漏配,切 Tab 后状态被重置。
  • 各 Tab 共用同一图级 ViewModel,状态串台。

追问

  • 多返回栈有数量限制吗?答:受系统回栈与内存约束,过深层级需实测(待确认)。
  • Tab 内深层页面返回行为?答:先弹出该 Tab 栈,再回到 Tab 根。

07.1.1.6.2-022 进程死亡后导航回栈如何恢复?

一句话结论

Controller 保存回栈条目与参数,进程重建后按保存状态还原条目;目的地 ViewModel 重建,页面业务状态按 SavedStateHandle 与仓库/网络恢复,未持久化的内存状态丢失。

概念解释

导航框架负责栈结构与参数恢复,不保证页面内列表、草稿等内存快照;深链场景按入口参数重建页面。

原理流程

进程死亡 → 保存 back stack 状态
重建 → 还原条目与参数
  → ViewModel 重建 → Handle 还原小值 → 加载数据

代码或图示

// 重建后从条目参数恢复入口
val args = backStackEntry.savedStateHandle

常见误区

  • 以为回栈恢复会连带恢复各页面滚动位置与表单。
  • 条目参数含不可序列化对象,恢复后丢失。

追问

  • 回栈过深被裁剪怎么办?答:关键页面提供深链可重建路径,栈丢失后从根或深链恢复。
  • 如何验证?答:后台划灭进程后返回,检查栈层级与参数是否还原。

07.1.1.6.2-023 登录态校验如何接入导航守卫?

一句话结论

在导航组装或目的地入口判断登录状态:未登录跳转登录目的地,登录完成后回跳原始目标;守卫集中在路由层,页面本身不重复弹登录框。

概念解释

可通过起始 route 选择、导航拦截回调或目的地 ViewModel 校验实现;敏感目的地必须在入口与服务端双重校验。

原理流程

目标 route → 检查会话
  → 已登录 → 进入目的地
  → 未登录 → 存原始目标 → 登录 → 回跳

代码或图示

fun navigateToOrders() {
    if (session.isLoggedIn) navController.navigate("orders")
    else { pendingRoute = "orders"; navController.navigate("login") }
}

常见误区

  • 每个页面各自判断登录,跳转来源与回跳地址不一致。
  • 只在客户端校验,服务端不拦截越权访问。

追问

  • 登录成功后如何回到原目标?答:读取暂存 route/参数,登录后 navigate 并清栈到合理根。
  • 深链未登录怎么处理?答:保留原始深链参数,登录后按深链重建目的地。

07.1.1.6.2-024 action 声明与直接 navigate(route) 怎么取舍?

一句话结论

模块内稳定、需要动画与回栈配置的跳转用 action;动态、跨模块或 Compose 声明式导航用 route;无论哪种,跳转目标与策略集中定义,避免散落在业务代码里。

概念解释

action 把回栈配置、动画固化在图中;route 更轻量灵活,但回栈参数要在调用处显式给出。

原理流程

稳定流程 → action(图内配置策略)
动态路由 → route(调用处配置策略)

代码或图示

// action
navController.navigate(ListFragmentDirections.toDetail(id))
// route
navController.navigate("detail/$id") { launchSingleTop = true }

常见误区

  • 同一条流程两种方式混用,回栈行为不一致。
  • route 字符串与图中目的地拼写不一致,运行时找不到目的地。

追问

  • Lint 能检查未声明 route 吗?答:XML action/目的地校验较完善;字符串 route 需靠约定与测试覆盖。
  • 跨模块优先哪种?答:公共路由常量 + route 方式,避免反向依赖生成类。

07.1.1.6.2-025 目的地参数在深链与内部跳转时行为有何不同?

一句话结论

内部跳转由方向对象携带完整参数;深链参数来自 URI 模板与查询参数,缺省走默认值;两者最终都进入条目 arguments,但来源可控性不同,深链侧必须做格式与缺失校验。

概念解释

内部参数是编译期/调用期保证;深链参数来自外部不可信输入,类型、编码、缺失都可能异常,入口校验不可省略。

原理流程

内部:Directions 携带类型化参数
深链:URI 解析 → 字符串参数 → 转换校验

代码或图示

val raw = backStackEntry.arguments?.getString("itemId")
val id = raw?.toLongOrNull() ?: -1L

常见误区

  • 内部跳转没问题,开放深链后非数字链接崩溃。
  • 查询参数与路径参数键名冲突互相覆盖。

追问

  • 参数能在条目间保持不变吗?答:条目重建时从保存状态还原;未持久化的派生值重新计算。
  • 默认值与 null 如何区分?答:声明 nullable 时缺省为 null;基础类型缺省为声明默认值。

07.1.1.6.2-026 导航条目 ViewModel 在导航切换时何时保留、何时清除?

一句话结论

条目在回栈中保留时其 ViewModel 存活;条目弹出销毁、嵌套图弹出或宿主销毁时清除;切到其他 Tab 多返回栈下其他栈条目暂停但不清除。

概念解释

这是条目作用域在导航层的表现:保留栈 ≠ 可见,可见性由条目 lifecycle 控制,清除由条目销毁触发。

原理流程

条目保留在栈 → ViewModel 存活
条目弹出 → Store.clear → onCleared

代码或图示

val vm: DetailViewModel by navGraphViewModels(R.id.detail_graph)

常见误区

  • 以为切走页面 ViewModel 就清除,返回后状态丢失。
  • 条目弹出后仍持有其 ViewModel 引用。

追问

  • 图级 ViewModel 与条目 ViewModel 谁活得久?答:图级随子图条目,长于目的地条目。
  • 配置变更下条目 ViewModel 存活吗?答:回栈保留时随条目存活,重建后重新挂载。

07.1.1.6.2-027 XML 导航图与代码声明式导航各适合什么场景?

一句话结论

XML 图适合传统 Fragment/Activity 工程,可视化管理目的地、动作与深链;Compose 与新工程用代码 DSL 声明 route 目的地,路由表随代码版本管理。

概念解释

两者都产出 Controller 可识别的导航结构;团队选型看页面技术栈与是否需要图形化编辑,不强制新旧互斥。

原理流程

XML:res/navigation/*.xml → 加载到 NavController
DSL:NavHost { composable(route) {...} }

代码或图示

NavHost(navController, "list") {
    composable("list") { ListScreen() }
    composable("detail/{id}") { DetailScreen() }
}

常见误区

  • 在 Compose 工程里硬维护一套 XML 图,双份路由约定漂移。
  • DSL route 未集中常量管理,拼写散落。

追问

  • 老 XML 图能逐步迁 DSL 吗?答:可按页面类型分批,混合期间 Controller 配置保持一致。
  • 路由表能否放公共模块?答:可以,route 常量与参数契约集中,避免各页面重复定义。

07.1.1.6.2-028 类型安全的路由定义进展如何?

一句话结论

导航组件在推进基于 Kotlin Serialization 的类型安全路由:以可序列化对象作为路由参数载体,替代纯字符串模板;具体 API 形态、稳定版本与兼容范围需以官方文档为准,本项目不臆造。

概念解释

类型安全路由把路由与参数编译期绑定,减少字符串拼参与解析错误;与 Safe Args 面向 XML 图的生成类互补。

原理流程

@Serializable data class DetailRoute(val id: Long)
  → 路由声明绑定序列化器
    → 跳转传递 Route 对象,目的地反序列化

代码或图示

// 示意:最终 API 以官方稳定版为准(待确认)
@Serializable data class Detail(val itemId: Long)

常见误区

  • 把实验 API 直接用于核心流程,未评估版本升级成本。
  • 路由对象含不可序列化字段,恢复时失败。

追问

  • 当前生产项目用什么?答:稳定期优先 Safe Args 或 route 常量 + 显式校验;新方案先在隔离页面试点。
  • 待确认验证点?答:序列化路由在导航回栈恢复、深链解析中的兼容性。

07.1.1.6.2-029 页面不在回栈时执行返回会怎样?

一句话结论

popBackStack 栈空时返回 false,由宿主按系统返回逻辑处理(退出 Activity 或回调 OnBackPressed);对 Controller 操作前应确认条目存在,避免空条目读取参数。

概念解释

导航动作在条目缺失时不应假设目的地一定在栈上;深链直达、宿主销毁、配置恢复后都可能出现栈状态与预期不一致。

原理流程

popBackStack()
  → 栈非空:弹出顶部,返回 true
  → 栈空:返回 false,交由宿主返回处理

代码或图示

val popped = navController.popBackStack()
if (!popped) requireActivity().onBackPressedDispatcher.onBackPressed()

常见误区

  • 无条件 popBackStack() 后继续读取前一条目参数。
  • 在 Controller 已销毁的回调里执行导航。

追问

  • 如何判断当前能否返回?答:currentBackStackEntry 与回栈深度;事件回调里先查状态。
  • 双返回栈下栈空如何跨 Tab?答:按宿主返回策略在 Tab 栈间回退或退出。

07.1.1.6.2-030 快速重复点击导致连续跳转如何防重?

一句话结论

跳转前判断当前目的地与节流状态;配合 launchSingleTop 复用顶部条目;按钮防抖或在导航动作完成期间忽略重复点击,避免压入多层相同页面。

概念解释

单靠 singleTop 挡不住首帧前的快速连点;防抖在入口层,singleTop 在栈顶复用层,两者互补。

原理流程

点击 → 防抖/当前目的地判断
  → navigate + singleTop
    → 连续点击不产生多层栈

代码或图示

fun openDetail(id: Long) {
    if (navController.currentDestination?.route == "detail/$id") return
    navController.navigate("detail/$id") { launchSingleTop = true }
}

常见误区

  • 只在 UI 层设点击间隔,导航入口仍可能被其他事件重复触发。
  • 防抖状态放 ViewModel,页面重建后丢失判断。

追问

  • 动画期间能再次跳转吗?答:可以,但栈状态可能处于过渡中,需以 currentEntry 为准。
  • 列表多 item 快速进入不同详情?答:允许不同目标,仅对相同目的地去重。

07.1.1.6.2-031 跨模块导航如何保持模块边界?

一句话结论

公共模块定义路由常量、参数契约与目的地接口;feature 模块实现目的地,宿主组装图;feature 之间不直接依赖彼此的生成类或页面类,通过 route 与契约通信。

概念解释

跨模块导航破坏边界的典型是反向依赖、直接引用其他模块 Fragment 类;route 字符串与契约对象把依赖约束到公共定义层。

原理流程

:core-navigation 定义 route/参数契约
  → :feature-a、:feature-b 各自实现
    → :app 宿主组装 NavHost

代码或图示

// core-navigation
object Routes { const val DETAIL = "detail/{itemId}" }

常见误区

  • feature-a 直接 import feature-b 的 FragmentDirections。
  • 参数契约散落在各模块,字段名与类型漂移。

追问

  • 模块间传复杂对象怎么办?答:传标识(ID),目标模块自行加载;复杂结果经仓库或事件契约。
  • 导航图能否按模块注册?答:可由各模块提供目的地注册器,宿主聚合。

一句话结论

导航 deep link 定义应用内目的地与 URI 模板映射;App Links 是经域名验证、可让系统直接打开对应应用的 Web 链接,需要 Manifest 声明与数字资产验证,二者配合完成外部直达。

概念解释

未验证的链接可能弹出应用选择器;App Links 通过 assetlinks.json 验证域名归属,默认由本应用打开匹配链接。

原理流程

Web URI → 系统匹配 intent-filter + 域名验证
  → 打开应用 → Navigation 匹配模板 → 目的地

代码或图示

<intent-filter android:autoVerify="true">
    <data android:scheme="https" android:host="example.com"/>
</intent-filter>

常见误区

  • 只配 navDeepLink 不配 intent-filter,外部链接打不开。
  • 域名资产验证配置错误,链接回退到浏览器。

追问

  • 验证文件放哪里?答:域名 .well-known/assetlinks.json,与应用包名、签名指纹对应;具体配置以官方文档为准(待确认)。
  • 测试期间如何绕过验证?答:调试可用 adb 直接发 Intent 验证目的地匹配,不依赖域名验证。

07.1.1.6.2-033 如何导航到外部应用或浏览器?

一句话结论

外部目的地用显式 Intent 或 ACTION_VIEW URI 启动,不走内部回栈;返回应用时回到原任务栈,内部页面参数与外部跳转互不污染。

概念解释

内部 Navigation 管理应用内条目;跳出应用是系统 Intent 行为,需处理无接收应用的兜底(浏览器或应用商店)。

原理流程

内部目的地 → navController.navigate
外部链接 → Intent(ACTION_VIEW, uri).startActivity

代码或图示

val intent = Intent(Intent.ACTION_VIEW, Uri.parse(url))
startActivity(intent)

常见误区

  • 把外部 URI 当内部 route 压栈,找不到目的地崩溃。
  • 未判断是否有应用可接收 Intent,隐式 Intent 解析失败。

追问

  • 外部 Activity 目的地能声明在图里吗?答:可以声明 Activity 目的地,但跨应用仍需 Intent 解析。
  • 跳出后回栈保留吗?答:原任务栈保留,返回时回到跳出前页面。

07.1.1.6.2-034 底部 Tab 切换时如何保留各页面状态?

一句话结论

使用多返回栈并开启 saveState/restoreState,切走的 Tab 条目暂停但不销毁;页面状态由条目 ViewModel 与保存状态保留,回到 Tab 时恢复栈与视图。

概念解释

状态保留分两层:回栈结构由导航保存,页面内存状态由条目 ViewModel 持有;视图重建后从 ViewModel 恢复渲染。

原理流程

切走 Tab → 栈保存(saveState)
切回 Tab → restoreState 恢复栈 → 视图重新订阅 ViewModel

代码或图示

navController.navigate(itemId) {
    popUpTo(startDestId) { saveState = true }
    launchSingleTop = true
    restoreState = true
}

常见误区

  • 只 saveState 不 restoreState,切回仍是初始页。
  • 页面临时草稿未落盘,视图销毁后仍丢失。

追问

  • 状态保存有大小限制吗?答:受 Bundle/实例状态约束,大列表不落保存状态,回栈后重新加载。
  • 如何验证 Tab 状态?答:A 进入二级页 → 切 B → 回 A,确认层级与滚动/草稿仍在。

07.1.1.6.2-035 导航接入常见崩溃有哪些?

一句话结论

高频问题:目的地未注册、参数键缺失或类型不符、Controller 重复创建、深链模板不匹配、导航在宿主销毁后执行、回栈条目读取空参数;多数可通过 Lint、入口校验与状态判断规避。

概念解释

崩溃集中在「跳转时找不到目标」和「目的地读取参数时假设必然存在」两类;导航校验与单元/仪器测试可覆盖主要路径。

原理流程

跳转 → 校验目的地/参数
目的地 → 读取参数前判空与转换
回调 → 检查 Controller/条目仍存活

代码或图示

val id = backStackEntry.arguments?.getString("itemId")?.toLongOrNull()
    ?: error("非法 itemId")

常见误区

  • 依赖运行时日志才发现未注册 route。
  • 在销毁后的 LiveData/Flow 回调里 navigate。

追问

  • 如何提前发现?答:开启导航 Lint,补充各目的地与深链的仪器测试。
  • Controller 重复创建的典型场景?答:配置变更后旧实例引用未释放,新宿主又建一个。

07.1.1.6.2-036 导航如何做测试与目的地断言?

一句话结论

仪器测试中获取 NavController,断言当前目的地 ID/route、回栈条目数量与参数;跳转动作测试触发后校验目标目的地,深链测试用模拟 Intent 验证匹配与参数解析。

概念解释

单元测试侧重路由常量与参数契约;导航行为(栈变化、回退)需仪器测试或 Compose 测试环境运行 Controller。

原理流程

启动 Host → 取 Controller
  → 执行跳转 → 断言 currentDestination 与 arguments
    → 返回动作 → 断言回栈层级

代码或图示

onNodeWithText("详情").performClick()
assertThat(navController.currentDestination?.route).isEqualTo("detail/7")

常见误区

  • 只断言页面可见,不校验回栈层级与参数。
  • 测试中重复创建 Controller,状态与生产不一致。

追问

  • 深链测试怎么构造?答:用 Intent 模拟外部 URI 启动 Activity,检查目的地与参数。
  • 纯逻辑路由能否单测?答:路由常量、参数转换函数可脱离 Controller 单测。

07.1.1.6.2-037 导航组件的版本方向是什么?

一句话结论

Navigation 持续向 Compose 声明式导航与类型安全路由演进,Fragment 图仍受支持;具体废弃计划、API 稳定状态与版本边界以官方 release notes 为准,项目不凭记忆下结论。

概念解释

演进关注点:route 序列化、多返回栈、结果回传 API、与 Compose 生命周期集成;老 XML 图在可预见版本内保留兼容。

原理流程

当前稳定:XML 图 + Fragment/Compose 目的地
演进方向:类型安全路由对象 + 声明式 DSL

代码或图示

版本核对:developer.android.com/jetpack/androidx/releases/navigation

常见误区

  • 把实验 API 当稳定能力写进核心流程。
  • 升级导航版本后未回归回栈与深链行为。

追问

  • 待确认验证点?答:类型安全路由的稳定版本、结果回传新 API 的兼容范围。
  • 老工程如何跟踪?答:随 BOM 升级,保留 XML 图,新页面用 DSL 渐进接入。

07.1.1.6.2-038 多返回栈的 saveState 与 restoreState 如何配合?

一句话结论

saveState=true 在弹出 Tab 栈时保存条目状态与 ViewModel 快照;restoreState=true 再次切换时恢复上次栈;两者配对使用才能保留层级与状态,单独设置只完成一半行为。

概念解释

保存的是导航回栈状态,视图内持久数据仍需 ViewModel/存储配合;配置变更与进程死亡下恢复能力另受实例状态约束。

原理流程

切走 Tab:popUpTo(...) { saveState = true } 保存
切回 Tab:navigate(...) { restoreState = true } 恢复

代码或图示

navController.navigate(id) {
    popUpTo(startId) { saveState = true }
    launchSingleTop = true
    restoreState = true
}

常见误区

  • 只写 saveState,切回后栈被重置。
  • 以为保存状态包含大列表与位图,实际只存可序列化条目状态。

追问

  • 保存状态何时清除?答:对应栈被显式弹出或宿主销毁时;具体清理时机以实现版本为准(待确认)。
  • 多 Tab 状态错乱如何排查?答:打印 currentBackStackEntry 链,核对各 Tab 栈保存与恢复键。

07.1.1.6.2-039 导航图如何按登录态或特性开关条件组装?

一句话结论

在宿主组装 NavHost 时根据会话、功能开关选择起始 route 与注册目的地;敏感流程作为独立子图,未满足条件不注册或重定向,避免把条件判断散落在每个页面。

概念解释

条件组装影响「能到达哪些目的地」;运行时守卫影响「当前能否进入某目的地」,两层配合覆盖启动态与切换态。

原理流程

启动 → 读会话/开关
  → 注册对应子图 → 选 startDestination
运行时进入 → 守卫校验 → 通过或重定向

代码或图示

val start = if (session.isLoggedIn) "home" else "login"
NavHost(navController, startDestination = start) { /* 按条件注册 */ }

常见误区

  • 开关关闭后目的地仍可通过深链或旧栈到达。
  • 条件判断写在页面 ViewModel,导航回退不一致。

追问

  • 深链绕过客户端守卫怎么办?答:服务端按权限校验,客户端只做体验层重定向。
  • 开关灰度期间旧栈残留如何处理?答:进入时校验当前条件,不满足的栈条目弹出或回退。

07.1.1.6.2-040 global action 适合描述什么样的跳转?

一句话结论

全局动作挂在导航图根节点,描述多个目的地都可能触发的通用跳转(如回到主页、打开设置);避免在每个子目的地重复定义相同动作与回栈配置。

概念解释

global action 继承图作用域,回栈行为作用于根图;子图内私有流程仍应定义在子目的地或子图上。

原理流程

<navigation>
  <action id="global_home" destination="home" popUpTo="..."/>
</navigation>

代码或图示

<action android:id="@+id/action_global_home"
        app:destination="@id/home"
        app:popUpTo="@id/home" app:popUpToInclusive="false"/>

常见误区

  • 把只属于单个流程的动作提升为全局,扩大可达性。
  • 全局动作的 popUpTo 范围过大,误清其他 Tab 栈。

追问

  • 全局动作能指向子图入口吗?答:可以,目标为子图 startDestination 或子图 route。
  • 多个图同名动作会冲突吗?答:ID 在图作用域内解析,引用时注意所属图。

07.1.1.6.2-041 WorkManager 解决什么问题?

一句话结论

WorkManager 提供可延迟、可重试、受约束条件调度的后台任务能力,保证任务在合适时机执行(应用退出、设备重启后仍可排队),适合非即时的后台作业。

概念解释

它在底层按系统能力选择 JobScheduler、AlarmManager 或前台服务实现,对上暴露统一的任务提交、约束、观察与重试 API;不替代即时前台任务。

原理流程

提交 WorkRequest(约束 + 策略)
  → WorkManager 入队
    → 约束满足时调度执行 → 观察 WorkInfo 状态

代码或图示

val request = OneTimeWorkRequestBuilder<SyncWorker>().build()
WorkManager.getInstance(context).enqueue(request)

常见误区

  • 把需要秒级响应的即时操作交给 WorkManager,延迟不可控。
  • 以为它能保活进程或长期驻留后台。

追问

  • 任务多久执行?答:受约束、系统调度与版本后台限制影响,不保证即时;加急任务可提升优先级(见后续题)。
  • 与协程后台任务区别?答:协程跟随页面/进程生命周期;WorkManager 跨进程与重启保留排队。

07.1.1.6.2-042 哪些场景适合或不适合用 WorkManager?

一句话结论

适合:日志上报、离线数据同步、批量预下载、定期刷新等可延迟、需重试的任务;不适合:用户交互必须即时反馈、需要长连接/常驻播放、进程退出即无意义的任务。

概念解释

判断标准:任务是否允许延迟到约束满足时执行、应用退出后是否仍需完成;即时任务用前台服务/协程,实时长连接用专门驻留方案。

原理流程

可延迟 + 需保证 → WorkManager
即时反馈 → 前台协程 / 前台服务
常驻连接 → 专门连接方案(受后台限制约束)

代码或图示

适合:sync cache、upload logs、periodic refresh
不适合:点击立即播放、即时提交表单依赖当场结果

常见误区

  • 用 WorkManager 做页面离开后必须立刻完成的写库,结果被调度延迟。
  • 高频小任务周期提交,造成频繁唤醒与耗电。

追问

  • 表单提交失败重试归谁?答:可在仓库层重试;需要跨进程保证时入队 WorkManager,配合幂等。
  • 后台播放用 WorkManager 吗?答:不适合,应使用前台服务与音频焦点管理。

07.1.1.6.2-043 Constraints 可以约束哪些执行条件?

一句话结论

可约束网络类型(无网/Wi-Fi/计量网络)、是否充电、设备空闲、存储空间充足、电池不低电量等;条件不满足时任务排队等待,满足后再调度。

概念解释

约束是调度前置条件,不是任务内判断;组合多个条件时需全部满足,设备状态变化由系统重新评估。

原理流程

Constraints(networkType = UNMETERED, charging = true)
  → 任务排队 → 条件全满足 → 执行

代码或图示

val constraints = Constraints.Builder()
    .setRequiredNetworkType(NetworkType.UNMETERED)
    .setRequiresCharging(true)
    .build()

常见误区

  • 约束过严导致任务长期不执行,用户感知不到结果。
  • 任务内部不再兜底判断网络状态,边界条件变化时出错。

追问

  • 设备空闲约束何时生效?答:系统判断设备处于交互空闲区间;判定策略随版本变化(待确认)。
  • 约束能在任务运行中撤销吗?答:约束作用于调度时机,执行中网络变化需任务自行处理。

07.1.1.6.2-044 OneTimeWorkRequest 与 PeriodicWorkRequest 有什么区别?

一句话结论

一次性任务执行成功或终态结束后不再重复;周期任务按最小周期间隔重复执行,每次执行是新一轮 WorkInfo;两者构造方式与入队策略不同。

概念解释

一次性任务适合单次同步/上传;周期任务适合定期刷新、清理;周期任务不能携带链式依赖,重复节奏由系统调度对齐。

原理流程

OneTime:入队 → 执行 → SUCCEEDED/FAILED/终止
Periodic:入队 → 周期执行 → 每轮独立状态

代码或图示

val once = OneTimeWorkRequestBuilder<SyncWorker>().build()
val daily = PeriodicWorkRequestBuilder<RefreshWorker>(1, TimeUnit.DAYS).build()

常见误区

  • 用周期任务做「每次打开应用都同步」,实际节奏不受前台触发控制。
  • 周期任务期望精确到固定时刻执行。

追问

  • 周期任务间隔下限是多少?答:系统有最小周期限制,具体取值与版本以官方文档为准(待确认)。
  • 周期任务失败会怎样?答:按退避策略重试本轮;本轮终态后等待下一周期。

07.1.1.6.2-045 Worker 有哪几种实现类型?

一句话结论

CoroutineWorker 在协程中实现 doWork(),适合 Kotlin 协程任务;ListenableWorker 用于绑定异步回调/Java 代码;原生 Worker 在后台线程同步执行;优先 CoroutineWorker。

概念解释

Worker 由 WorkManager 在合适线程上调用;CoroutineWorker 用 suspend doWork,取消随协程响应;ListenableWorker 通过返回 ListenableFuture 对接异步体系。

原理流程

CoroutineWorker:suspend doWork → Result
ListenableWorker:startWork → ListenableFuture<Result>
Worker:doWork() 同步返回 Result

代码或图示

class SyncWorker(ctx: Context, params: WorkerParameters) : CoroutineWorker(ctx, params) {
    override suspend fun doWork(): Result {
        return runCatching { repository.sync() }
            .fold(onSuccess = { Result.success() }, onFailure = { Result.retry() })
    }
}

常见误区

  • 在 CoroutineWorker 的 suspend 方法里做阻塞同步 IO 且不切线程,阻塞调度线程。
  • 用原生 Worker 跑复杂异步回调,线程模型混乱。

追问

  • Worker 能访问 ViewModel 吗?答:不能直接持有界面 ViewModel;依赖通过工厂注入仓库或会话。
  • 取消时协程如何响应?答:挂起点响应取消,任务应检查 isActive 类取消状态。

07.1.1.6.2-046 doWork 返回的 Result 有哪些状态?

一句话结论

Result.success() 成功可带输出数据;Result.retry() 按退避策略重新排队;Result.failure() 终态失败不再自动重试;状态对应 WorkInfo 的 SUCCEEDED/FAILED/ENQUEUED/RUNNING 等。

概念解释

返回值决定任务走向:retry 不是立刻重跑,进入退避排队;failure 表示业务判定不可恢复,需上层决定是否重新入队。

原理流程

doWork() → success(数据) / retry() / failure(数据)
  → WorkManager 更新 WorkInfo 状态

代码或图示

override suspend fun doWork(): Result {
    val result = runCatching { upload() }
    return when {
        result.isSuccess -> Result.success()
        isRetryable(result.exception) -> Result.retry()
        else -> Result.failure()
    }
}

常见误区

  • 所有异常都 retry,不可恢复错误无限重试耗电。
  • failure 后期望任务自动恢复,实际已是终态。

追问

  • 输出数据放哪里?答:Result.success(Data),由观察 WorkInfo 的 outputData 读取。
  • 如何区分可重试异常?答:按网络/限流/服务端错误分类,业务自定义判定。

07.1.1.6.2-047 ExistingWorkPolicy 四种策略如何选择?

一句话结论

KEEP 保留已存在任务;REPLACE 替换旧任务;APPEND 新旧串联,旧完成后执行新任务;APPEND_OR_REPLACE 旧任务完成后追加新任务,旧为终态则直接运行新任务。用于唯一命名任务的去重与更新。

概念解释

策略作用于同名唯一任务:避免重复入队,同时决定是覆盖、排队还是追加;周期任务适用策略与一次性任务不同。

原理流程

enqueueUniqueWork(name, policy, request)
  → 存在同名任务?
    KEEP=不动 / REPLACE=清旧换新 / APPEND=串联

代码或图示

WorkManager.getInstance(ctx)
    .enqueueUniqueWork("sync", ExistingWorkPolicy.KEEP, request)

常见误区

  • 刷新场景用 KEEP,旧任务卡住时新请求永远不执行。
  • 对周期任务误用 APPEND 语义,行为不符合预期。

追问

  • 周期任务用什么策略?答:通常 REPLACE/KEEP;APPEND 类串联策略不适用周期任务(细节以文档为准,待确认)。
  • 如何查看旧任务状态?答:按 name 观察 getWorkInfosForUniqueWorkFlow。

07.1.1.6.2-048 退避策略 BackoffPolicy 如何配置?

一句话结论

retry 任务按退避间隔与策略(指数/线性)重新排队,初始间隔有下限,指数退避每次翻倍;可在请求上配置退避时间与策略,减少持续失败时的频繁唤醒。

概念解释

退避是调度层重试节奏,不替代业务幂等;失败越频繁等待越久,配合约束条件在合适网络/充电状态再执行。

原理流程

retry → 等待 backoffDelay
  → 再次失败 → 间隔按策略增长

代码或图示

OneTimeWorkRequestBuilder<SyncWorker>()
    .setBackoffCriteria(BackoffPolicy.EXPONENTIAL, 30, TimeUnit.SECONDS)
    .build()

常见误区

  • 退避间隔设得过小,失败时反复唤醒耗电。
  • 以为 retry 立即重跑,忽略排队等待窗口。

追问

  • 退避间隔最小值是多少?答:系统有下限,具体毫秒数以官方文档为准(待确认)。
  • 指数退避上限会封顶吗?答:增长到一定程度由系统限制,实现细节待确认。

07.1.1.6.2-049 任务链与并行任务如何编排?

一句话结论

一次性任务可用 then 串联顺序执行,with 组合并行任务;链式任务前序输出可作为后序输入,某一环失败决定整条链走向;周期任务不支持链式编排。

概念解释

链式编排声明 DAG 依赖:并行分支全部完成后再进入后继;输入数据沿链传递,适合「先下载再解析再上传」流程。

原理流程

A + B(并行)→ C(后继)
workManager.beginWith(A, B).then(C).enqueue()

代码或图示

val cache = OneTimeWorkRequestBuilder<CacheWorker>().build()
val report = OneTimeWorkRequestBuilder<ReportWorker>().build()
WorkManager.getInstance(ctx).beginWith(cache).then(report).enqueue()

常见误区

  • 把需要并行的任务写成串行,拉长总耗时。
  • 前序失败后仍期待后序执行,未检查链状态。

追问

  • 分支失败如何影响后继?答:默认链按任务结果传播终态;具体跳过规则以文档为准(待确认)。
  • 任务间传大数据可行吗?答:Data 键值有大小限制,大对象走存储/仓库。

07.1.1.6.2-050 任务输入输出 Data 有哪些类型与限制?

一句话结论

Data 以键值保存基础类型及其数组、少量 Parcelable/Serializable 集合;体积受 Binder/事务约束,不适合传大列表、位图或复杂对象,大对象应传 ID 由 Worker 从仓库读取。

概念解释

Data 是任务间轻量参数载体;超过大小限制会在入队或传递时失败,设计任务时按「标识 + 存储」而非「对象拷贝」传递。

原理流程

inputData: key → 基础值/小集合
Worker 读参数 → 从仓库/数据库取真实数据
输出:Result.success(Data) 回传轻量结果

代码或图示

val input = Data.Builder().putLong("itemId", 7L).build()
val output = Data.Builder().putString("status", "done").build()

常见误区

  • 在 Data 里塞整张列表或位图。
  • 跨进程写入自定义未序列化对象,恢复时失败。

追问

  • Data 大小上限?答:受系统事务限制,具体阈值以官方文档与实测为准(待确认)。
  • 复杂结果如何回传?答:写数据库/仓库,WorkInfo 只回传状态与标识。

07.1.1.6.2-051 唯一任务名如何用于去重?

一句话结论

按业务域给任务起唯一命名,用 enqueueUniqueWork 提交;同名任务受 ExistingWorkPolicy 控制,避免重复入队多个相同同步任务;可按名查询与取消整组任务。

概念解释

名字是逻辑去重键,不依赖 Worker 类;同一业务多个任务可用名字分组,便于观察、取消与状态汇总。

原理流程

业务触发 → enqueueUniqueWork("upload_daily", KEEP, request)
  → 同名已存在 → 按策略处理

代码或图示

WorkManager.getInstance(ctx)
    .enqueueUniqueWork("log_upload", ExistingWorkPolicy.KEEP, request)

常见误区

  • 每次请求用随机名,失去去重能力,重复任务堆积。
  • 名字不含业务维度,不同用途任务互相覆盖。

追问

  • 同名任务能有多个并行实例吗?答:唯一语义下按策略合并;需要并行的不同任务应使用不同名或普通入队。
  • 如何取消唯一任务?答:cancelUniqueWork(name)。

07.1.1.6.2-052 周期任务的最小间隔有什么限制?

一句话结论

周期任务不能按任意高频间隔调度,系统规定最小周期窗口,任务执行时长也占用周期;间隔过短会被系统对齐或拒绝,具体下限随平台版本以官方文档为准(待确认)。

概念解释

周期设计面向「每天/每几小时」级别的后台刷新,不适合分钟级轮询;高频需求应重新评估是否为前台场景或推送驱动。

原理流程

PeriodicWorkRequest(interval)
  → 间隔 >= 系统最小周期
    → 执行结束后等待下一周期

代码或图示

PeriodicWorkRequestBuilder<RefreshWorker>(6, TimeUnit.HOURS).build()

常见误区

  • 设 15 分钟以内周期,实际不按预期频率执行。
  • 用周期任务做实时性要求高的状态同步。

追问

  • 任务执行超时怎么办?答:Worker 有执行时限,超时按取消/失败处理;具体时限随版本(待确认)。
  • 想在特定时刻触发?答:周期任务不保证精准时刻,可结合约束与前台触发。

07.1.1.6.2-053 如何观察任务状态?

一句话结论

通过 getWorkInfoByIdFlow、getWorkInfosByTagFlow 或 getWorkInfosForUniqueWorkFlow 观察 WorkInfo:状态、进度、输出数据与重试次数;界面按状态展示进度或结果。

概念解释

WorkInfo 状态包括 ENQUEUED、RUNNING、SUCCEEDED、FAILED、RETRYING、CANCELLED 等;Flow 在生命周期内收集,离开页面停止订阅。

原理流程

入队得到 workId
  → observe WorkInfo flow
    → 状态/进度 → 界面渲染

代码或图示

WorkManager.getInstance(ctx).getWorkInfoByIdFlow(request.id)
    .collect { info -> binding.render(info.state, info.progress) }

常见误区

  • 用一次性回调轮询状态,错过重试与进度更新。
  • 观察时不绑生命周期,后台持续收集。

追问

  • 进度如何上报?答:Worker 用 setProgress(Data) 更新,WorkInfo.progress 读取。
  • 标签(tag)有什么用?答:按标签批量查询与取消任务,适合一组同类作业。

07.1.1.6.2-054 约束不满足时任务处于什么状态?

一句话结论

任务保持 ENQUEUED(排队)状态等待约束满足,不占用执行;设备状态变化后系统重新评估,满足条件再进入 RUNNING;约束长期不满足任务一直排队。

概念解释

排队不是失败:用户离线、未充电等场景下任务等待;观察状态可区分「等待条件」与「执行失败」。

原理流程

入队 → ENQUEUED(等待约束)
  → 约束满足 → RUNNING
  → 约束失败场景 → retry 回排队

代码或图示

when (info.state) {
    WorkInfo.State.ENQUEUED -> showWaiting()
    WorkInfo.State.RUNNING -> showProgress()
    WorkInfo.State.FAILED -> showError()
    else -> Unit
}

常见误区

  • 任务长时间未执行被误判为丢失,实际在等网络/充电约束。
  • 界面只显示执行中,不暴露等待原因。

追问

  • 如何调试排队原因?答:结合约束条件、设备网络/充电状态与 WorkInfo 状态判断;系统调度细节不对外完全透明。
  • 约束能动态修改吗?答:已入队任务约束固定,需替换任务(REPLACE)更新。

07.1.1.6.2-055 新版本后台限制下任务行为有什么变化?

一句话结论

高版本对后台启动、空闲时段、任务执行窗口限制更严;WorkManager 作为受管调度通道按系统能力适配,但任务仍可能延迟、受限速与省电策略影响,不能假设应用退出后立即执行。

概念解释

后台限制随 Android 版本收紧,前台服务启动条件、唤醒频率都受约束;任务设计要容忍延迟、保证幂等,并在前台提供合理反馈。

原理流程

入队 → 系统调度器在允许窗口执行
  → 后台限制:窗口收窄、批量对齐、省电延后

代码或图示

版本核对:developer.android.com 后台执行限制与 WorkManager 行为说明

常见误区

  • 沿用旧版本「退出即执行」预期,线上延迟率偏高。
  • 任务不幂等,延迟重试导致重复副作用。

追问

  • 待确认验证点?答:目标 minSdk/targetSdk 下各类约束的实际调度窗口与加急任务行为。
  • 如何降低延迟感知?答:前台可触发即时同步,后台任务做兜底与批量补齐。

07.1.1.6.2-056 setExpedited 加急任务是什么,前台信息如何提供?

一句话结论

加急(expedited)任务提升执行优先级,接近即时执行,但在高版本可能需要以前台服务形式运行;Worker 通过 getForegroundInfo() 提供通知与前台服务类型,用户可见通知。

概念解释

加急用于不能延迟的短任务(如登录后提交关键数据);它受前台服务权限与通知约束,不是无限制后台启动。

原理流程

request.setExpedited(OutOfQuotaPolicy.RUN_AS_NON_EXPEDITED_WORK_REQUEST)
  → Worker.getForegroundInfo() → 通知 + 类型
    → 加急执行,不足配额时回退普通调度

代码或图示

OneTimeWorkRequestBuilder<SubmitWorker>()
    .setExpedited(OutOfQuotaPolicy.RUN_AS_NON_EXPEDITED_WORK_REQUEST)
    .build()

常见误区

  • 把大量任务标成加急,占用配额且触发前台通知。
  • 未提供前台通知信息,高版本执行受限或崩溃。

追问

  • 配额策略有哪些?答:加急配额不足时可回退非加急或中止;具体策略随版本(待确认)。
  • 前台服务类型怎么选?答:按任务用途声明对应类型(如数据同步、短期服务),清单与运行时权限一致。

07.1.1.6.2-057 Worker 绑定前台服务如何配置?

一句话结论

需要在前台运行的 Worker 可调用 setForeground 把任务提升为前台服务,配合 ForegroundInfo 提供通知与服务类型;通知渠道、类型声明与权限必须在清单中配齐。

概念解释

前台服务在任务执行期间有常驻通知,优先级高于普通后台任务;任务结束后服务随 Worker 终止释放,不长期驻留。

原理流程

Worker 执行 → setForeground(foregroundInfo)
  → 启动前台服务 + 通知
    → 任务结束 → 服务销毁

代码或图示

override suspend fun getForegroundInfo(): ForegroundInfo =
    ForegroundInfo(NOTIFY_ID, buildNotification(), FOREGROUND_SERVICE_TYPE_DATA_SYNC)

常见误区

  • 清单缺少前台服务类型或权限,高版本启动失败。
  • 通知渠道未创建,通知不展示。

追问

  • 服务类型能否运行时更改?答:类型在声明与 ForegroundInfo 中一致声明,变更需按新版本规则(待确认)。
  • 前台任务超时多久?答:前台服务有时长限制,超限按系统规则处理;具体时长随版本(待确认)。

07.1.1.6.2-058 任务被系统杀死后状态如何保留与重试?

一句话结论

Worker 进程被系统回收后,WorkManager 根据任务配置重新调度;未完成任务按 retry/退避重新入队,已完成结果持久化在 WorkManager 数据库中;业务自身必须幂等,避免重跑产生重复副作用。

概念解释

任务进度由 WorkManager 持久化管理,但 Worker 内存中的局部状态不保留;重跑时从输入数据与存储恢复上下文。

原理流程

进程被杀 → 任务中断
  → WorkManager 持久化队列 → 重新调度
    → Worker 从输入/存储重建上下文 → 幂等执行

代码或图示

// 重跑前先查仓库:已成功则跳过,避免重复提交
if (repository.isUploaded(id)) return Result.success()

常见误区

  • 依赖内存变量记录「已处理到第几条」,重跑从头开始重复提交。
  • 服务端接口不幂等,重试产生重复订单/消息。

追问

  • 任务状态存在哪里?答:WorkManager 内部数据库;卸载或清除数据后队列丢失。
  • 如何保证只执行一次?答:业务唯一标识 + 服务端去重 + 本地状态记录。

07.1.1.6.2-059 多进程下 WorkManager 如何初始化与配置?

一句话结论

默认由 WorkManagerInitializer 在应用进程初始化;多进程场景需确认初始化进程与数据库访问方式,避免每个进程重复初始化或队列状态不一致;自定义配置通过 Configuration.Provider 或初始化器完成。

概念解释

WorkManager 队列与状态存内部数据库,跨进程访问有约束;多进程架构应明确哪个进程负责入队与执行,避免重复调度。

原理流程

Application 实现 Configuration.Provider
  → 提供 WorkManager 配置
    → 统一入口实例化管理器

代码或图示

class App : Application(), Configuration.Provider {
    override val workManagerConfiguration = Configuration.Builder()
        .setWorkerFactory(diWorkerFactory).build()
}

常见误区

  • 多进程各自 getInstance 导致配置不一致。
  • 在非主进程初始化重型依赖,拖慢该进程启动。

追问

  • 自动初始化能否关闭?答:可通过 manifest 移除默认初始化器并手动初始化;适用场景以文档为准(待确认)。
  • 跨进程观察任务状态?答:经 WorkManager 数据库读取,各进程读到同一队列状态。

07.1.1.6.2-060 如何通过 WorkerFactory 注入依赖?

一句话结论

实现 WorkerFactory 的 createWorker,按 Worker 类从 DI 容器取仓库/会话并构造;把工厂配置进 WorkManager,解决 Worker 无参构造无法注入依赖的问题。

概念解释

默认工厂走无参构造;自定义工厂在创建 Worker 时介入,替换为带依赖的实例,配合 Hilt/Koin 等容器完成注入。

原理流程

WorkManager 需要 Worker
  → 自定义工厂.createWorker()
    → DI 取依赖 → 构造 Worker 实例

代码或图示

class DiWorkerFactory(private val repo: SyncRepository) : WorkerFactory() {
    override fun createWorker(...) = when (klass) {
        SyncWorker::class.java -> SyncWorker(appContext, params, repo)
        else -> super.createWorker(...)
    }
}

常见误区

  • 工厂内每次新建仓库实例,绕过 DI 单例。
  • Worker 构造里持有 Context 转成 Activity 引用。

追问

  • Hilt 如何集成 Worker?答:Hilt 提供 Worker 注入桥接,@HiltWorker 与工厂配合;具体组件以 Hilt 文档为准(待确认)。
  • 工厂创建失败返回什么?答:返回 null 走默认逻辑或抛异常,按框架约定处理。

07.1.1.6.2-061 CoroutineWorker 的线程模型是怎样的?

一句话结论

CoroutineWorker 在 WorkManager 提供的调度协程中执行 suspend doWork,默认不在主线程;阻塞 IO 应使用协程调度器,取消时挂起点响应,任务结束返回 Result。

概念解释

协程调度线程由 WorkManager 配置;与页面 viewModelScope 无关,Worker 协程生命周期跟随任务执行,不绑定界面。

原理流程

调度 → 启动 Worker 协程
  → doWork() suspend 执行
    → 完成返回 Result;取消时协程终止

代码或图示

override suspend fun doWork(): Result {
    return withContext(Dispatchers.IO) { repository.sync() }
        .fold({ Result.success() }, { Result.retry() })
}

常见误区

  • 在 doWork 里直接接触主线程 UI。
  • 用 Thread/阻塞队列替代协程挂起,取消不响应。

追问

  • 能在 Worker 里启动长期子协程吗?答:应在 doWork 作用域内完成;脱离作用域的任务不受取消管理。
  • 调度线程能否配置?答:通过 Configuration 调整执行器;默认适合后台任务,细节以文档为准。

07.1.1.6.2-062 如何取消一个任务?

一句话结论

可按 workId、tag 或唯一名取消:cancelById、cancelAllWorkByTag、cancelUniqueWork;取消后任务进入 CANCELLED 状态,正在执行的 Worker 收到取消信号应尽快退出。

概念解释

取消是协作式的:已开始的任务不会被强行杀死,Worker 需响应取消并停止副作用;已成功执行的结果不回滚。

原理流程

cancel(id/tag/name)
  → 未开始:标记取消
    → 执行中:发取消信号 → Worker 退出 → CANCELLED

代码或图示

WorkManager.getInstance(ctx).cancelAllWorkByTag("draft_upload")

常见误区

  • 取消后假设已执行的本地副作用回滚,实际不会。
  • 取消请求发出后立即继续读取结果,状态尚未更新。

追问

  • 周期任务取消后还会再跑吗?答:取消后本轮与后续周期停止;需重新入队才恢复。
  • 如何确认取消完成?答:观察对应 WorkInfo 到 CANCELLED 终态。

07.1.1.6.2-063 任务失败统计与幂等设计要注意什么?

一句话结论

失败按可重试/不可恢复分类统计,任务以业务唯一标识保证重复执行不产生重复副作用;服务端接口幂等,本地记录处理状态,重试与人工补偿都围绕同一标识。

概念解释

WorkManager 只负责调度与状态,不保证业务语义唯一;幂等设计是任务可重试的前提,失败统计用于观察成功率、重试次数与积压。

原理流程

任务带业务唯一 ID
  → 执行前查本地/服务端状态
    → 已处理则跳过;未处理则执行并记录结果

代码或图示

val record = repository.findPending(bizId)
if (record != null && record.status == DONE) return Result.success()
submit(bizId)
repository.markDone(bizId)

常见误区

  • 重试导致重复下单、重复发消息。
  • 失败只看 WorkInfo FAILED,不区分网络临时失败与业务拒绝。

追问

  • 积压任务如何排查?答:按 tag/唯一名查询 ENQUEUED/RETRYING 数量与约束状态。
  • 死信任务怎么处理?答:达到重试上限后 failure,转人工补偿或前端可见错误。

07.1.1.6.2-064 WorkManager 与 JobScheduler、AlarmManager、Service 是什么关系?

一句话结论

WorkManager 是上层统一抽象,底层按系统能力选择 JobScheduler(高版本)、AlarmManager/旧兼容通道等实现;它不替代前台服务(需要常驻/即时),也不替代 Alarm 的精确定时唤醒。

概念解释

选择底层实现由 WorkManager 根据 API 级别与任务特征决定;业务代码面向 WorkManager API,不必直接操作各调度器。

原理流程

WorkRequest → WorkManager
  → 高版本:JobScheduler 等受管调度
  → 旧版本:兼容调度通道
即时/常驻 → 前台服务;精确定时 → AlarmManager

代码或图示

可延迟保证执行 → WorkManager
精确定时唤醒 → AlarmManager
常驻播放/即时前台 → Service(前台)

常见误区

  • 要求 WorkManager 做闹钟式精确定时。
  • 用 JobScheduler/Alarm 重复造 WorkManager 已封装的重试与约束逻辑。

追问

  • 后台限制对这些通道分别影响?答:前台启动与定时唤醒各有版本约束,选型前对照官方后台限制文档(待确认)。
  • 任务保证到什么程度?答:设备未卸载应用、未清除数据的前提下受管调度;不保证实时性。

07.1.1.6.2-065 如何测试 Worker?

一句话结论

用 TestListenableWorkerBuilder(或 CoroutineWorker 测试构造器)在测试环境实例化 Worker,传入测试输入数据与仓库假实现,断言 Result 类型、输出数据与进度;约束、策略与队列行为用仪器测试覆盖。

概念解释

Worker 单测聚焦业务逻辑与结果判定,不依赖真实调度;测试中替换仓库为假实现,验证成功、重试、失败分支。

原理流程

构造 Worker(输入 + 假仓库)
  → 执行 doWork()
    → 断言 Result.success/retry/failure 与 outputData

代码或图示

val worker = TestCoroutineWorkerBuilder<SyncWorker>(context)
    .setInputData(Data.Builder().putLong("id", 1).build())
    .build()
val result = worker.doWork()
assertThat(result).isInstanceOf(Result.Success::class.java)

常见误区

  • 单测里跑真实网络/数据库,变成集成测试。
  • 只测成功分支,漏测可重试与终态失败。

追问

  • 取消行为怎么测?答:在挂起点检查取消状态,测试中取消协程断言任务退出。
  • WorkManager 队列策略如何测?答:仪器测试观察 WorkInfo 状态流转。

07.1.1.6.2-066 Preferences DataStore 的基本读写 API 怎么用?

一句话结论

Preferences DataStore 通过 Preferences.Key 定义键,data Flow 读取当前偏好集合,edit { it[key] = value } 协程事务写入;实例按单例持有,避免重复打开文件。

概念解释

与 SharedPreferences 的阻塞 API 不同,DataStore 基于协程 Flow,读取是流订阅,写入是事务块;键带类型,缺失时返回默认值。

原理流程

val KEY = stringPreferencesKey("theme")
读:data.map { it[KEY] ?: "system" }
写:edit { it[KEY] = "dark" }

代码或图示

val themeKey = stringPreferencesKey("theme")
suspend fun setTheme(value: String) = dataStore.edit { it[themeKey] = value }
val theme: Flow<String> = dataStore.data.map { it[themeKey] ?: "system" }

常见误区

  • 每次读写新建 DataStore 实例,多份文件句柄冲突。
  • 在主线程同步阻塞读偏好。

追问

  • 实例如何提供?答:通过 DI 单例注入,或应用级单例委托持有。
  • 键类型有哪些?答:字符串、整型、布尔、浮点、字节数组及对应集合;具体清单以文档为准(待确认)。

07.1.1.6.2-067 DataStore 的读-改-写事务一致性如何保证?

一句话结论

edit 块内对偏好的修改在事务中串行应用,读-改-写不会被并发写入交错;同一 DataStore 实例的写操作排队执行,保证状态一致性。

概念解释

事务块内可读当前值再计算新值,避免「先读后写」之间被其他写入覆盖;异常时本次编辑回滚,不留下半更新状态。

原理流程

edit { prefs ->
  val current = prefs[counterKey] ?: 0
  prefs[counterKey] = current + 1
}
// 并发 edit 排队串行执行

代码或图示

suspend fun increment() = dataStore.edit { prefs ->
    val count = prefs[countKey] ?: 0
    prefs[countKey] = count + 1
}

常见误区

  • 在 edit 块外先读 Flow 值再写,中间状态可能被其他写入修改。
  • edit 块里做阻塞重活,拉长事务持锁时间。

追问

  • 写失败会重试吗?答:事务异常向上抛出,由调用方决定重试;不静默吞错。
  • 多进程同时写怎么办?答:DataStore 设计为单进程内使用,多进程并发写不在支持范围内(见后续题)。

07.1.1.6.2-068 Proto DataStore 的协议消息与序列化怎么工作?

一句话结论

Proto DataStore 用 Protocol Buffers 定义消息类型,通过 Serializer 读写序列化字节;存储内容是一份 proto 消息,字段类型由 schema 约束,避免字符串键的类型漂移。

概念解释

Preferences 用字符串键 + 动态值;Proto 把整个偏好结构固化成消息类,读取得到类型化对象,写入修改消息字段后序列化落盘。

原理流程

proto schema → 生成消息类
  → Serializer.readFrom(bytes) / writeTo(message, output)
    → DataStore<Settings> 暴露消息 Flow

代码或图示

object SettingsSerializer : Serializer<Settings> {
    override val defaultValue = Settings.getDefaultInstance()
    override fun readFrom(input: InputStream): Settings =
        Settings.parseFrom(input)
    override fun writeTo(t: Settings, output: OutputStream) = t.writeTo(output)
}

常见误区

  • 把 Proto 当 Preferences 用,按零散字符串字段存取。
  • schema 改字段不兼容旧序列化数据,读取解析失败。

追问

  • Proto 依赖引入什么?答:protobuf 与 DataStore Proto 构件,坐标与版本以官方文档为准(待确认)。
  • 消息能存嵌套结构吗?答:可以,嵌套 message/枚举;复杂关系数据仍应归数据库。

07.1.1.6.2-069 Preferences DataStore 与 Proto DataStore 如何选型?

一句话结论

键值零散、结构简单、字段稳定用 Preferences;偏好本身是结构化对象、需要类型安全与 schema 演进管理用 Proto;团队 protobuf 工具链不成熟时不要为少量设置强行上 Proto。

概念解释

选择看数据形态与演进需求:Preferences 轻量直观,Proto 在多字段、嵌套、跨模块共享偏好时更可控。

原理流程

简单键值 → Preferences
结构化、类型约束、schema 版本 → Proto

代码或图示

维度 Preferences Proto
定义 字符串键 + 类型函数 proto 消息
类型 单值类型校验 消息整体类型
结构 扁平键值 可嵌套
成本 低 需要 protobuf 工具链

常见误区

  • 同一应用两种 DataStore 混用且职责不清,配置散落两处。
  • 用 Proto 存大量列表或二进制大对象。

追问

  • 能从 Preferences 迁到 Proto 吗?答:可以通过迁移逻辑读取旧值并构造默认消息,切换存储实现。
  • 字段后续增加怎么办?答:两种方案都靠默认值兼容旧数据;Proto 额外受 proto 兼容规则约束。

07.1.1.6.2-070 如何从 SharedPreferences 迁移到 DataStore?

一句话结论

创建 DataStore 时注册 migrations:检测旧 SharedPreferences 文件是否存在,在迁移回调中把旧键值读出写入新存储;迁移完成后旧文件保留观察期,确认无回退需求再移除。

概念解释

迁移在首次打开新 DataStore 时执行一次,回调内可读取旧 SP 并构造初始值;Preferences 与 Proto 的迁移写法不同,Proto 需组装消息默认值。

原理流程

DataStore 创建 → 检查旧 SP 文件
  → 迁移回调:读旧值 → 写新存储
    → 后续读取走新 DataStore

代码或图示

val dataStore = preferencesDataStore(
    name = "settings",
    migrations = listOf(SharedPreferencesMigration(context, "settings_sp"))
)

常见误区

  • 迁移回调里做阻塞 IO 或跨进程读取。
  • 迁移后立即删旧文件,灰度回退时数据丢失。

追问

  • 迁移失败怎么办?答:异常上抛,首次读取受阻;需记录失败状态并支持重试,不要静默丢值。
  • 键名能直接沿用吗?答:可以沿用,但建议借此机会统一命名规范。

07.1.1.6.2-071 数据校验与默认值如何设计?

一句话结论

每个偏好键提供明确默认值,读取时对非法值做校验回退;Proto 在消息层约束类型,Preferences 在读取映射处做范围/合法性检查,避免脏数据流入业务逻辑。

概念解释

默认值覆盖首次安装与键缺失;校验防御旧版本写入、损坏数据与外部篡改,异常值回退安全默认态。

原理流程

读取 data → 取值
  → 缺省用默认值
    → 非法值校验 → 回退默认 / 修正写入

代码或图示

val theme: Flow<String> = dataStore.data.map { prefs ->
    when (prefs[themeKey]) { "dark", "light", "system" -> prefs[themeKey]!!; else -> "system" }
}

常见误区

  • 直接把存储值当合法枚举用,脏值导致崩溃。
  • 各页面各自默认值不一致,同一设置表现不同。

追问

  • 校验后要不要回写修正?答:可在 edit 中写回合法值,但避免读取流里反复写;集中在启动或变更时校正。
  • 枚举新增旧值怎么兼容?答:未知值映射到默认或保守选项。

07.1.1.6.2-072 为什么 DataStore 实例必须按单例持有?

一句话结论

一个 DataStore 对应一份打开的存储文件,多实例并发打开同一文件会导致读写竞争与一致性问题;应通过 DI 或应用级单例提供唯一实例,全进程共享。

概念解释

实例内部维护读写队列与文件句柄;重复创建实例绕过了单实例的串行化保护,是常见故障来源。

原理流程

单例 DataStore
  → 所有读 Flow / edit 走同一队列
多实例 → 同一文件被多方打开 → 竞争 / 状态不一致

代码或图示

// 应用级单例委托
val Context.settingsDataStore by preferencesDataStore("settings")

常见误区

  • 在每个 Repository 里 preferencesDataStore(...) 新建实例。
  • 测试中忘记提供同一假实例,多个存储互不相同。

追问

  • 单例持有 Context 用什么?答:应用 Context,避免绑定 Activity 实例。
  • 不同存储文件能否各建实例?答:不同文件名对应不同存储,各自单例即可。

07.1.1.6.2-073 DataStore 对多进程并发写的支持边界是什么?

一句话结论

DataStore 面向单进程设计,官方不保证多进程同时读写同一文件的一致性;多进程共享偏好需要改用支持跨进程的方案(如数据库、MMKV 类方案或 IPC),具体支持边界以官方文档为准(待确认)。

概念解释

其内部串行化队列只在单实例单进程内有效;多进程各自打开文件可能写覆盖、读到旧快照。

原理流程

单进程:edit 串行排队
多进程:各进程文件句柄独立 → 无跨进程锁保证

代码或图示

多进程共享配置 → Room / 跨进程键值方案 / IPC
不要依赖 DataStore 多进程写一致性

常见误区

  • 多进程架构里直接用 DataStore 存跨进程会话配置。
  • 假设文件锁由系统自动协调。

追问

  • 哪些数据必须跨进程一致?答:登录态、全局开关;其余进程内偏好可留在本进程存储。
  • 待确认验证点?答:目标厂商系统上多进程文件写竞争的实际表现。

07.1.1.6.2-074 updateData/edit 的协程与异常如何处理?

一句话结论

edit/updateData 是挂起事务块,块内修改串行应用;抛出异常会中断本次编辑并向上传播,调用方应捕获并记录,区分 IO 异常与校验异常,不要在块内吞掉所有错误。

概念解释

事务内可先读当前值再改;块里的异常导致本次写入不提交,已有旧值保留;协程取消会终止编辑。

原理流程

dataStore.edit { prefs -> ... }
  → 成功:提交
  → 异常:回滚本次修改,异常上抛

代码或图示

suspend fun setTheme(value: String) {
    runCatching { dataStore.edit { it[themeKey] = value } }
        .onFailure { Logger.report("settings write failed", it) }
}

常见误区

  • 在 edit 块里 catch 后继续写脏值。
  • 未处理异常导致偏好写入失败被静默忽略。

追问

  • 读写冲突如何表现?答:单实例内排队,不会交错;多实例/多进程问题见前述题。
  • 协程取消时 edit 完成了吗?答:取消中断块,未提交修改不落盘。

07.1.1.6.2-075 如何删除或清理某个键?

一句话结论

Preferences 在 edit 块中 remove(key);Proto 消息字段清空按 proto 语义处理(清空字段或用默认值);批量清理在一个事务内完成,避免多次打开存储。

概念解释

删除键后读取回退默认值;清理敏感信息(退出登录)应与令牌、缓存一起在同一流程内完成。

原理流程

edit { remove(key) }
  → 提交后该键不存在 → 读取默认值

代码或图示

suspend fun clearPreference(key: Preferences.Key<String>) =
    dataStore.edit { it.remove(key) }

常见误区

  • 只把值置空字符串,键仍占存储且语义不清。
  • 退出登录只清内存不清持久偏好。

追问

  • Proto 字段能直接删除键吗?答:proto 消息无键删除概念,按字段默认值/清除处理;schema 删除字段属兼容变更。
  • 清空整份存储怎么做?答:逐个 remove 或重建默认消息,按存储类型选择。

07.1.1.6.2-076 DataStore 在仓库层如何封装?

一句话结论

仓库类注入单一 DataStore 实例,对外暴露类型化的 Flow 读取与挂起写方法;UI/ViewModel 不直接碰 DataStore API,键名、默认值与校验收敛在仓库内。

概念解释

封装层隔离存储实现,便于测试替换、后续迁移;键常量集中定义,业务方法表达语义(setTheme、observeTheme)而非裸键读写。

原理流程

ViewModel → SettingsRepository(Flow/挂起方法)
  → DataStore 单例

代码或图示

class SettingsRepository(private val store: DataStore<Preferences>) {
    fun theme(): Flow<String> = store.data.map { it[themeKey] ?: "system" }
    suspend fun setTheme(value: String) = store.edit { it[themeKey] = value }
}

常见误区

  • ViewModel 直接持有 DataStore,键与默认值散落页面。
  • 仓库暴露原始 Preferences 对象,页面随意改键。

追问

  • 多仓库访问同一存储可以吗?答:可以共享同一实例,但写方法职责应划分清楚。
  • 测试如何替换?答:仓库接口 + 内存假实现,替换 DataStore。

07.1.1.6.2-077 Proto DataStore 的 schema 演进与类型安全如何保证?

一句话结论

proto 字段编号在演进中保持不变,新增字段给默认值、不删除复用编号;类型由生成消息保证,读取得到编译期类型化对象,避免字符串键的类型错误。

概念解释

兼容规则与 protobuf 通用约定一致:字段名可改、编号不可乱;消息结构演进要兼容旧版本序列化数据。

原理流程

v1 消息字段 1,2
v2 新增字段 3(默认值)
旧数据解析 → 缺省新字段;新数据旧版本读 → 忽略未知字段

代码或图示

message Settings {
  string theme = 1;
  bool push_enabled = 2;
  // 新增字段使用新编号与默认值
}

常见误区

  • 复用已删除字段编号,旧数据串到新字段。
  • 改字段类型不保持兼容,解析异常。

追问

  • Preferences 的演进靠什么?答:键与类型约定 + 默认值,无 schema 强约束,更需要人工评审。
  • 不兼容变更怎么办?答:新建存储或写迁移逻辑转换旧消息。

07.1.1.6.2-078 哪些数据不适合放进 DataStore?

一句话结论

大列表、位图、大 JSON 文档、高频变更的计数器与关系型数据不适合;DataStore 是小体积键值/小型结构化偏好存储,大数据归数据库、文件或图片缓存。

概念解释

每次读写序列化整份存储,体积变大后读写成本与内存占用上升;关系查询、分页、约束完整性由数据库承担。

原理流程

小偏好/配置 → DataStore
列表、对象集合、可查询数据 → Room
大文件/位图 → 文件缓存 + 图片库

代码或图示

适合:theme、locale、push 开关、入门引导标记
不适合:商品列表、聊天记录、缓存图片、行为流水

常见误区

  • 把离线整页 JSON 字符串塞偏好,每次读写全量解析。
  • 用 DataStore 做跨表关联查询。

追问

  • 多大算过大?答:没有固定阈值,以读写耗时与序列化体积实测为准;增长趋势比单次大小更重要(待确认)。
  • 高频计数器怎么办?答:内存聚合 + 定期落盘,或数据库计数表。

07.1.1.6.2-079 DataStore 与 SharedPreferences 在 API 模型上的关键差异是什么?

一句话结论

SharedPreferences 提供同步 get 与 commit/apply,回调监听基于 OnSharedPreferenceChangeListener;DataStore 基于协程 Flow 异步读取、挂起事务写入,无同步阻塞读,状态以流形式观察。

概念解释

差异在并发模型与线程安全语义:DataStore 读是流收集,写是串行事务;SP 的 commit 同步落盘、apply 异步提交,历史上有一致性与回调时机问题。

原理流程

SP:getXxx 同步读;apply/commit 写;listener 回调
DataStore:data Flow 订阅;edit 挂起事务;流自动发新值

代码或图示

// DataStore 读取是流,不是同步 getter
val theme: Flow<String> = settingsRepository.theme()

常见误区

  • 把 DataStore 当 SP 在主线程同步读 first(),阻塞界面。
  • 假设 SP apply 的值立刻在其他进程可见。

追问

  • apply 与 commit 区别?答:apply 内存先更新、异步落盘;commit 同步写并返回成功与否;细节属 SP 旧机制。
  • 迁移到 Flow 后旧 listener 代码怎么改?答:改为收集仓库暴露的 Flow,绑定生命周期。

07.1.1.6.2-080 迁移期间双读双写策略如何安排?

一句话结论

过渡期可先写新 DataStore、读旧 SP(或反过来),按迁移方向灰度;确认读取走新存储稳定后,旧 SP 只读兜底,最后下线旧写入与文件。双写需定义哪边为准,避免双源不一致。

概念解释

迁移不是一次性切换:先建迁移回调回填新存储,运行期新写入进新存储,读取逐步切到新源;回退预案保留旧文件一段时间。

原理流程

阶段1:迁移回填 + 双写(新为准)
阶段2:读切新存储,旧 SP 只读兜底
阶段3:停双写、删旧文件

代码或图示

写入:先写 DataStore;过渡期同步写 SP 兜底
读取:DataStore 优先,缺失回退 SP

常见误区

  • 双写两边默认值不一致,冲突时不知道谁准。
  • 一次性强切,旧版本/老用户无迁移路径。

追问

  • 双写失败如何处理?答:以新存储为准并记录旧写失败,下次迁移补写。
  • 灰度按什么维度?答:版本/用户分群,保留回退开关。

07.1.1.6.2-081 测试中如何构造 DataStore?

一句话结论

单元测试用临时文件路径构造 preferencesDataStore/Proto DataStore,或直接用内存假仓库替代;测试结束清理临时文件,验证 Flow 初始值、写入后新值与迁移回调。

概念解释

不依赖真实设备存储路径;测试可注入自定义 DataStore 实例,断言读取流发射序列与事务写入结果。

原理流程

临时文件 → 构造 DataStore
  → 写方法 → 收集 data 断言
    → 清理临时文件

代码或图示

private val testStore = preferencesDataStore("test_settings")
// 在测试上下文注入临时实例,runTest 中收集断言

常见误区

  • 测试复用固定路径,用例间状态串扰。
  • 不取消收集 Flow,测试协程泄漏。

追问

  • Proto 测试 Serializer 吗?答:测读写往返:写消息 → 序列化 → 反序列化 → 字段一致。
  • 迁移测试怎么造旧 SP?答:测试上下文创建旧 SP 文件写入旧值,跑迁移回调断言回填。

07.1.1.6.2-082 协程取消时 DataStore 读写处于什么状态?

一句话结论

读取 Flow 在收集协程取消时停止收集,不影响已落盘数据;edit 块被取消时本次修改不提交,旧值保留;已完成的写入持久化,未完成事务回滚。

概念解释

DataStore 自身单例仍持有打开的存储;取消的是业务收集/编辑协程,不是关闭存储;重试编辑需重新发起。

原理流程

collect 取消 → 停止流发射
edit 取消 → 事务未提交 → 旧值不变

代码或图示

viewModelScope.launch {
    repository.theme().collect { /* 渲染 */ }
    // 作用域取消时收集自动停止
}

常见误区

  • 以为取消收集会删掉已保存偏好。
  • 编辑中途取消后读不到新值就判定写入失败,实际是未提交。

追问

  • 存储句柄何时关闭?答:单例生命周期内保持;进程结束统一释放(具体关闭时机以实现为准,待确认)。
  • 编辑失败重试要注意什么?答:重新读当前值再改,不要基于过期快照覆盖。

07.1.1.6.2-083 键命名与版本兼容有什么约定?

一句话结论

键名用模块前缀 + 语义命名,避免通用名冲突;偏好结构变更时保留旧键兼容读取,新键给默认值;版本升级后不静默删除旧键,保留一个观察版本周期。

概念解释

键是跨版本契约:旧版本写入的键在新版本仍可能存在;重命名键必须走迁移映射,不能直接换名丢弃旧值。

原理流程

键:"settings:theme"
版本升级:新键 "settings:theme_v2",迁移回调映射旧值

代码或图示

private const val PREFIX = "settings:"
val themeKey = stringPreferencesKey("${PREFIX}theme")

常见误区

  • 键名 "theme"、"mode" 等通用词,跨模块冲突。
  • 重构改键名不迁移,老用户偏好丢失。

追问

  • 偏好结构大改怎么办?答:新存储文件名 + 迁移回调转换,旧文件保留。
  • 枚举值字符串变更怎么兼容?答:读取时做新旧值映射。

07.1.1.6.2-084 敏感偏好如何加密落地?

一句话结论

DataStore 本身不提供加密;敏感值(令牌、凭据)结合加密存储方案(加密字段/加密数据库/Keystore 派生密钥)处理,DataStore 只存非敏感配置;具体加密组件选型按项目安全规范执行。

概念解释

明文偏好可被 root/备份读取;敏感信息不落明文键值,加密密钥托管在系统 Keystore,加密后密文再写入存储层。

原理流程

敏感值 → 加密(Keystore 密钥)→ 密文落存储
非敏感配置 → DataStore 明文

代码或图示

token/refresh_token:加密存储,不进普通偏好
theme/locale/push:DataStore 明文

常见误区

  • 把登录令牌明文存在偏好/DataStore。
  • 硬编码加密密钥随 APK 打包。

追问

  • 加密 DataStore 有官方组件吗?答:需结合安全存储方案实现;具体可选项以官方安全文档为准(待确认)。
  • 备份包含偏好吗?答:随应用备份配置,敏感值应排除备份或加密。

07.1.1.6.2-085 DataStore 初始化时机与单例持有如何安排?

一句话结论

DataStore 实例惰性创建、单例持有,首次访问时打开存储;不要在 Application onCreate 里做大量同步偏好读取,读取走协程流,写入在需要时发起。

概念解释

实例委托/DI 提供唯一引用;首次打开文件有 IO 成本,避免阻塞启动路径;启动所需配置由仓库在协程中读取。

原理流程

DI 提供单例 DataStore
  → 首次读取/写入时打开
    → 业务协程内访问,不阻塞主线程

代码或图示

val Context.settings by preferencesDataStore(name = "settings")

常见误区

  • Application 启动同步 runBlocking 读偏好,拖慢冷启动。
  • 多个类各自创建实例造成重复打开。

追问

  • 启动必须拿到的配置怎么办?答:在协程中读取,界面先给默认态,到达后更新;关键阻塞配置评估是否放内存缓存。
  • 单例能持有 Activity 吗?答:不能,用 Application Context。

07.1.1.6.2-086 配置变更与进程死亡后偏好读取行为如何?

一句话结论

偏好属于持久化存储,配置变更重建与进程死亡后都从磁盘读取;DataStore 单例在进程内缓存当前值,进程重建后重新打开文件读取,不存在内存偏好丢失问题。

概念解释

与 ViewModel 内存状态不同,偏好不依赖页面存活;读取流在新进程重新发射持久化值。

原理流程

配置变更:进程在 → 单例缓存值可读
进程死亡:重建 → 重新打开文件 → 读持久化值

代码或图示

// 任意新页面收集仓库流即可拿到持久化偏好
settingsRepository.theme().collect { applyTheme(it) }

常见误区

  • 以为配置重建后偏好需要重新保存。
  • 进程死亡后内存缓存丢失却没回读存储,显示默认值。

追问

  • 写入后立即进程死亡会丢吗?答:已提交落盘的值保留;未提交编辑随进程中断。
  • 多进程读到旧值?答:见多进程一致性限制题。

07.1.1.6.2-087 多个设置项如何批量读取与组合成流?

一句话结论

从 data Flow 一次性读取整份偏好,用 map 组合出界面需要的配置对象;多个 Flow 用 combine 聚合,避免为每个键单独打开读取或重复解析整份数据。

概念解释

整份偏好一次发射,派生视图模型在 map 中组装;相关设置项变化时合并流重新计算。

原理流程

data.map { prefs -> SettingsUi(theme = ..., locale = ...) }
多个来源 → combine(a, b) { ... }

代码或图示

val uiSettings: Flow<UiSettings> = dataStore.data.map { prefs ->
    UiSettings(
        theme = prefs[themeKey] ?: "system",
        locale = prefs[localeKey] ?: "zh-CN"
    )
}

常见误区

  • 每个设置项各收集一个流,界面订阅数量膨胀。
  • 在 map 里做重计算,每次偏好变化都重复执行。

追问

  • 写一个键会触发整份 data 发射吗?答:Preferences 整份快照作为流值发射;按需派生即可。
  • Proto 同理吗?答:消息整体流,map 取字段组装。

07.1.1.6.2-088 Proto schema 不兼容变更如何处理?

一句话结论

不兼容变更(改字段类型、复用编号、删除语义)不能直接覆盖旧数据;应新增字段/新消息版本,通过迁移逻辑转换旧消息,或新建存储文件并回填。

概念解释

旧版本序列化字节按旧 schema 解析,不兼容变更会解析异常或串值;兼容演进优先,确需破坏性变更时带迁移路径。

原理流程

检测旧版本消息
  → 迁移解析 → 转换为新消息
    → 写入新 schema 存储

代码或图示

兼容:加字段、加枚举值、保留编号
破坏:改类型、复用编号 → 必须迁移

常见误区

  • 直接改 proto 字段类型发版,老用户升级后解析崩溃。
  • 迁移只覆盖安装用户,漏了从旧版本跨多版升级的路径。

追问

  • 如何验证迁移?答:造旧版本序列化数据,升级后读取断言字段正确。
  • Preferences 有这类问题吗?答:键值类型漂移风险较低,但仍需默认值与映射兜底。

07.1.1.6.2-089 DataStore 接入有哪些高频坑?

一句话结论

高频问题:多实例打开同一文件、主线程同步阻塞读取、edit 异常未处理、存过大对象、跨进程假设一致、键名冲突与无默认值;接入前按单例、异步、事务、体积、边界逐项检查。

概念解释

多数坑来自把 SP 的同步直觉带到 DataStore,以及忽视存储边界;代码评审与启动/读写路径测试可覆盖主要风险。

原理流程

检查:单例实例 / Flow 异步 / 异常处理 / 体积 / 进程边界 / 键约定

代码或图示

反例:runBlocking { store.data.first() }
正例:repository.theme().collect { ... }

常见误区

  • 读取 first() 放在主线程点击回调里。
  • 把对象集合序列化 JSON 当字符串存偏好。

追问

  • 如何发现多实例?答:DI 检查 DataStore 提供点是否唯一;测试中核对实例引用。
  • 阻塞主线程怎么定位?答:StrictMode 或 ANR 堆栈查看 DataStore/文件 IO 调用栈。

07.1.1.6.2-090 DataStore 的版本稳定性与演进方向如何看待?

一句话结论

DataStore 是官方推荐的 SP 替代方案,API 以协程 Flow 为核心;具体构件版本、Proto 支持状态与废弃 API 以官方 release notes 为准,新项目可采用,遗留 SP 按迁移计划渐进替换。

概念解释

演进关注:协程/Flow 集成、多进程需求讨论、与 DI 容器配合;版本升级时回归读写、迁移与加密边界。

原理流程

版本核对:androidx.datastore release notes
  → 确认构件坐标与最低依赖

代码或图示

// 版本由项目 BOM 管理,不在此写死版本号
implementation "androidx.datastore:datastore-preferences"
implementation "androidx.datastore:datastore-protobuf"

常见误区

  • 凭记忆写死旧坐标版本。
  • 把实验 API 用于核心偏好链路。

追问

  • 待确认验证点?答:当前 BOM 下 Preferences/Proto 构件版本、序列化器 API 与多进程声明。
  • 旧 SP 必须一次迁完吗?答:不必,按模块/设置项渐进迁移,过渡期双读双写。

07.1.1.6.2-091 首次启动的默认偏好如何初始化?

一句话结论

默认值由键定义与 Serializer 提供,首次读取返回默认态;需要写入初始配置时在启动协程中按需 edit,不要在 Application 同步阻塞初始化全部偏好。

概念解释

首次安装无存储文件,读取走默认值;业务需要的初始开关、引导标记可在首次进入对应流程时落盘,避免启动路径重 IO。

原理流程

首次读取 → 缺省默认值
需要持久化初始值 → 协程内 edit 写入

代码或图示

suspend fun ensureOnboardingSeen() {
    val seen = store.data.first()[onboardingKey] ?: false
    if (!seen) store.edit { it[onboardingKey] = true }
}

常见误区

  • 启动时把所有默认值写入磁盘,增加冷启动 IO。
  • 各页面默认值不一致,与 Serializer 默认值脱节。

追问

  • 服务端下发的初始偏好怎么办?答:拉取后写入 DataStore,本地默认值仅作未登录兜底。
  • 默认值变更如何覆盖老用户?答:版本迁移或显式设置更新,不靠改默认值自动回写。

07.1.1.6.2-092 如何用偏好流驱动主题、语言等设置界面?

一句话结论

仓库暴露配置 Flow,设置页与应用入口都收集同一流;变更写入 DataStore,流自动发射新值,主题/语言应用在主线程切换,重建后从持久化值恢复。

概念解释

设置是典型的「持久化配置 + 流观察」场景:写入一处,所有订阅方收到更新;界面状态与存储保持单向同步。

原理流程

设置页改值 → 仓库写 DataStore
  → data 流发射 → 应用入口/页面收集 → 应用主题/语言

代码或图示

lifecycleScope.launch {
    repository.theme().collect { theme -> applyTheme(theme) }
}

常见误区

  • 主题切换只改内存状态,进程重建后回到旧设置。
  • 语言切换不刷新已创建的界面资源。

追问

  • 切换语言需要重建 Activity 吗?答:按实现策略,可重建上下文或局部刷新;配置变更行为需实测确认。
  • 多页面同时改同一设置如何同步?答:统一仓库写入,流广播给各订阅方。

07.1.1.6.2-093 DataStore 与 Room 的分工边界是什么?

一句话结论

DataStore 存少量配置、开关、标识等键值/小型结构;Room 存需要查询、关联、分页、事务一致性的业务数据;两者通过仓库层组合,界面不直接选择存储实现。

概念解释

判断依据:是否需要结构化查询、数据量增长、多表关联;配置项用 DataStore,列表与实体用数据库。

原理流程

配置/开关 → DataStore
实体列表、关联查询、离线缓存 → Room

代码或图示

维度 DataStore Room
数据形态 键值/小消息 关系表
查询 整份读取后派生 SQL 查询
体量 小 可增长
一致性 单实例事务 数据库事务/迁移

常见误区

  • 用 DataStore 存可搜索的离线列表。
  • 用 Room 存单个开关,引入表与迁移成本过重。

追问

  • 离线优先架构里两者怎么配合?答:Room 存业务实体,DataStore 存同步状态与用户偏好。
  • 缓存策略归哪层?答:仓库层决定缓存位置,页面只观察状态。

07.1.1.6.2-094 偏好变更如何通知其他页面或模块?

一句话结论

DataStore 流在同一进程内自动发射新值,各订阅方收集仓库流即可收到更新;跨模块通过公共仓库/流暴露,跨进程则需其他同步通道(数据库/IPC),不能依赖 DataStore 流跨进程通知。

概念解释

进程内订阅者在存储变更时收到新快照;未订阅的页面在重新进入时读取当前值即可;事件通知与状态读取分离。

原理流程

写入 DataStore → data Flow 发射
  → 进程内订阅方更新
跨进程 → 数据库/IPC 另行同步

代码或图示

// 公共模块暴露配置流
interface SettingsRepository {
    fun theme(): Flow<String>
}

常见误区

  • 跨进程模块订阅 DataStore 流,以为能收到其他进程写入。
  • 用事件总线重复转发偏好变更,与流状态重复。

追问

  • 订阅未活跃的页面回来怎么拿最新值?答:重新收集流即得到当前持久化值。
  • 变更需要埋点吗?答:写入处上报变更事件,流只负责状态同步。

07.1.1.6.2-095 迁移失败时的回滚策略怎么设计?

一句话结论

迁移在事务/回调中执行,失败不破坏旧文件:保留原始 SP 与旧存储,记录失败原因与版本号,下次启动重试;新存储写入完成前旧源仍可读,避免迁移中途失败导致双源皆空。

概念解释

回滚思路是「旧文件不动、新存储可丢弃重建」;迁移日志记录来源版本、键数量与失败点,便于补偿与定位。

原理流程

旧 SP 文件保留
  → 迁移写入新存储 → 失败则清理半成品新数据
    → 下次重试;成功后旧文件进入观察期

代码或图示

迁移失败:旧 SP 未被删除/覆盖
新存储:可重建,不承载唯一数据

常见误区

  • 迁移一开始就删旧文件,中途崩溃后数据丢失。
  • 不记录失败版本,每次启动重复迁移卡死。

追问

  • 迁移部分成功怎么办?答:按整体迁移判定,未完成则下次全量重试;键级幂等写入避免重复副作用。
  • 灰度如何回退?答:保留旧版本读取路径与旧文件,关闭新存储开关。

07.1.1.6.2-096 大字符串或 JSON 存 DataStore 的边界在哪?

一句话结论

短标识、序列化的小快照可以存;大段 JSON、长文本、对象集合不适合,因为每次读写整份序列化、占用内存且无查询能力;大对象应落数据库或文件,DataStore 只存引用与索引。

概念解释

Preferences 值支持字符串但受体积约束;JSON 字符串难以局部更新,改一个字段也要重写整串;Proto 同样不承载大列表。

原理流程

小快照 JSON:可存,注意体积与解析成本
大 JSON / 列表:文件 / Room,DataStore 存路径或 ID

代码或图示

不推荐:handle/cache 存整页响应 JSON
推荐:存 cache_key,内容落磁盘缓存

常见误区

  • 把离线页面模型序列化后存偏好,读写一次解析整份。
  • 长期累积多条大字符串,存储文件持续膨胀。

追问

  • 体积告警怎么设?答:观察存储文件大小与读写耗时,超阈值迁移到数据库/文件(阈值按实测,待确认)。
  • JSON 字段需要查询吗?答:需要就拆成表结构,不要在字符串里检索。

07.1.1.6.2-097 如何通过 DI 容器提供 DataStore 实例?

一句话结论

在 DI 模块提供单一 DataStore 实例(Preferences 或带 Serializer 的 Proto),仓库依赖该实例注入;实例用 Application Context 构造,避免 Activity 作用域,测试可替换为假实现。

概念解释

DI 保证全应用唯一实例、统一文件名与迁移配置;多存储按语义分别命名,各自由容器提供。

原理流程

DI provider → DataStore 单例
  → Repository 注入
    → 测试替换内存实现

代码或图示

@Provides
@Singleton
fun provideSettingsStore(@ApplicationContext ctx: Context):
        DataStore<Preferences> = ctx.settingsDataStore

常见误区

  • DI 里每次构造新实例,违反单例。
  • 注入 Activity Context 构造存储,泄漏界面引用。

追问

  • Hilt/Koin 怎么声明?答:按各自单例作用域提供;绑定仓库接口便于替换。
  • 多个 DataStore 如何区分?答:不同文件名 + 不同仓库方法,DI 按类型或限定符提供。

07.1.1.6.2-098 Worker 或后台协程中读写 DataStore 要注意什么?

一句话结论

后台任务可通过仓库注入的同一单例读写 DataStore;读写在后台调度器执行,避免在 Worker 主线程阻塞;写事务保持短小,敏感值走加密存储,任务取消时未提交编辑不落盘。

概念解释

Worker 不持有界面,通过 DI 取仓库与 DataStore;与前台页面共享同一进程内单例,读写排队串行;跨进程任务另按跨进程方案处理。

原理流程

Worker → 仓库(注入 DataStore 单例)
  → 后台线程 edit / data.first()
    → 短事务提交

代码或图示

class SyncWorker(app: Context, params: WorkerParameters,
                 private val settings: SettingsRepository) : CoroutineWorker(app, params) {
    override suspend fun doWork(): Result {
        val pushEnabled = settings.pushEnabled().first()
        // ... 同步逻辑
        return Result.success()
    }
}

常见误区

  • Worker 内新建 DataStore 实例,与页面不是同一存储。
  • 在 edit 块里跑长网络请求,拉长事务占用。

追问

  • 后台读到旧值怎么办?答:单实例内读一致;刚写入未提交的编辑读不到新值,属预期。
  • 周期性任务更新偏好要防重吗?答:按业务状态判断,避免覆盖用户刚改的设置。

07.1.1.6.2-099 单元测试如何覆盖 DataStore 读取流与写入?

一句话结论

用临时文件或内存假存储,runTest 中收集流断言初始默认值;调用写方法后断言流发射新值;迁移测试构造旧 SP 验证回填,异常分支断言回滚与旧值保留。

概念解释

测试覆盖:默认值、写入后发射、事务回滚、迁移映射;不依赖真实设备与文件系统固定路径。

原理流程

注入测试存储 → 收集 data 流
  → 写操作 → 断言新值
    → 迁移场景 → 断言旧值映射

代码或图示

@Test
fun `theme writes through to flow`() = runTest {
    val repo = SettingsRepository(testStore)
    repo.setTheme("dark")
    assertEquals("dark", repo.theme().first())
}

常见误区

  • 只测写入成功,不测默认值与非法值回退。
  • 收集流不取消,测试协程泄漏。

追问

  • Proto 测试重点?答:序列化往返、默认消息、字段兼容映射。
  • 迁移测试如何造旧数据?答:直接写旧 SharedPreferences 文件后跑迁移回调。

07.1.1.6.2-100 DataStore 读写频次与耗电如何设计?

一句话结论

偏好变更才写入,读取用流订阅避免反复打开文件;高频变更的状态在内存聚合、定期落盘,批量设置在一个事务内提交;监控存储大小、读写耗时与唤醒频次,避免频繁小事务造成 IO 与耗电。

概念解释

DataStore 适合低频配置写入;高频计数器、输入草稿、列表状态不应走偏好;写入批次合并,读取复用流缓存。

原理流程

低频配置 → 变更即写
高频状态 → 内存聚合 → 定期落盘
批量变更 → 单事务 edit

代码或图示

suspend fun updateAll(theme: String, locale: String) =
    dataStore.edit {
        it[themeKey] = theme
        it[localeKey] = locale
    }

常见误区

  • 每个输入字符都写偏好,IO 放大。
  • 页面每次返回都 first() 同步读,重复打开解析。

追问

  • 如何量化读写成本?答:日志埋点读写耗时与频次,观察文件大小趋势;耗电结合后台唤醒统计。
  • 后台周期任务写偏好注意什么?答:合并写入、避免每次周期全量重写。

参考来源

待整理清单

  • [ ] 核对项目 BOM 下 navigation、workmanager、datastore 构件的具体版本与最低 minSdk。
  • [ ] 验证类型安全路由(序列化路由)在当前版本的稳定度与回栈恢复行为。
  • [ ] 实测周期任务最小间隔、加急任务配额与前台服务类型在目标厂商系统上的表现。
  • [ ] 确认 DataStore 多进程读写的官方支持边界与替代跨进程键值方案。
  • [ ] 整理 SharedPreferences 迁移双读双写的灰度开关与回退流程。