Android 应用开发实战

📄 android-doc 全量 Review 报告 REVIEW-2026-09-29.md✓ 标记已学

审查日期：2026-09-29 审查范围：android-doc/ 全部 131 个文件 —— 28 篠教程文档（docs/）+ 双 README + TechFeed 示例工程（sample/，16 个 Gradle 模块：app + benchmark + 9 core + 5 feature + build-logic） 方法：四线并行审查（文档内容 / 构建体系 / core 模块 / feature+app），关键结论均经源码二次核实

一、总评

一句话结论：这是一套设计图纸质量远高于实现质量的项目——文档叙事、架构意识、工程规范均属上乘；但 sample 工程从未实际编译过（README 自己也坦承了这一点），导致 11 处编译级错误全部沉淀下来。文档侧无阻断问题，修复优先级应放在 sample 工程的 P0 清单上。

二、P0 —— sample 工程编译/装配阻断（11 处，全部经源码核实）

A. 构建体系（6 处）

B. 代码装配（5 处）

说明：README 的"首次导入检查清单"已坦承工程未实际编译验证——本次审查证实该预判准确，上述 11 处即沉淀的证据。

三、P1 —— 功能缺陷（sample 工程核心链路）

网络/鉴权（影响核心承诺）

1. TokenAuthenticator "无感刷新"空转（core/network/TokenAuthenticator.kt:28-39）：Mutex 内只读回旧 token 重发，从未调用刷新接口（TokenProvider.refreshToken() 全工程零调用，是死 API）。实际行为 = 重试一次必然再失败。
2. 登录凭据走 URL query（TechFeedApi.kt:30-31）：@POST + @Query 把用户名密码放进 URL，会进服务端日志/代理/自家 BODY 级日志。对第 19 章讲安全的教程是反例。应改 @Body。
3. BODY 级日志未脱敏 Authorization 头（NetworkModule.kt:40-46）：缺 .redactHeader("Authorization")。

UI 可用性（决定 demo 体验）

4. Feed 加载指示器永不显示（FeedScreen.kt:51-53 + FeedViewModel）：UI 判断 state.isLoading，但 VM 只设置 isRefreshing（且无人消费，无 PullToRefresh）→ 冷启动白屏无任何反馈。
5. 底部导航选中态永假（TechFeedApp.kt:55-57）：类型安全路由的 route 是全限定名，与 toString().substringAfterLast('.').lowercase()（"feedroute"）永不相等 → 三个 tab 永不高亮。
6. LoginRoute 不可达：导航图注册了登录页，但全仓库无任何 navigate(LoginRoute) 调用，事件分支是 -> Unit → 登录页是孤岛，auth 模块整套无法触达。
7. LoginViewModel 成功后 isLoading 卡死（LoginViewModel.kt:53-57）：成功分支不复位 loading；叠加 MutableSharedFlow() 无 replay，事件竞态丢失时按钮永久转圈。
8. 非紧凑屏没有任何导航 UI（TechFeedApp.kt:52）：Medium/Expanded 下 bottomBar 为空且无 NavigationRail → 平板/横屏无法切换页面。
9. toggleFavorite 静默失败（FeedViewModel.kt:82-86）：注释声称"失败由 error 流暴露"，但 error 流不存在，断网点收藏无任何反馈。

后台任务/深链

10. SyncScheduler 全工程零调用：周期同步从未被调度；showMessageNotification 同样零调用 → push 模块除 ensureChannels 外全是死代码。
11. 通知点击不深链（NotificationHelper.kt:45-47）：注释说深链到文章，实际只构造 launcher intent。
12. onNewIntent 空实现（MainActivity.kt:32-36）：App 前台/后台点深链无任何反应；NavHost 的 composable 也没注册 deepLinks 参数 → 深链仅冷启动有效，且返回栈断裂（直接退出应用）。

稳定性/存储

13. AnrWatchDog 三重缺陷（core/crash/AnrWatchDog.kt）：判定在 threshold/2 即触发（阈值缩水）；阻塞期间回调洪泛（无去重标志）；无法停止（重复调用即多个 watchdog 并发误报）；mainThreadStack() 是死代码且引用疑似不存在的 Debug.getThreadTid API。
14. CrashStore 补传闭环缺失：pendingReports() 无调用方，crash 文件无限累积无清理。
15. SecureTokenStorage 主线程做 Keystore+磁盘 IO（SecureTokenStorage.kt:20-28）：加密本身正确（MasterKey AES256_GCM），但构造注入发生在主线程，叠加 StrictMode 检测大概率违规。
16. CI "全模块单元测试" 只跑 :app（ci.yml:47-48）：testProdStoreDebugUnitTest 任务名只在 app 存在（flavor 仅 app 声明），feature 模块测试永远不会在 CI 运行。
17. Coil3 缺网络引擎：coil-network-okhttp 在 toml 声明但无模块使用，UI 用了 coil3.compose.AsyncImage → 运行时网络图全部加载失败（虽然当前 AsyncImage import 未使用，coverUrl 未渲染——两个问题互相掩盖）。
18. .gitignore 忽略 schemas/ 与 Room schema 入库策略自相矛盾（.gitignore:23-24）：注释说要提交 schema，模式却恰好把它忽略。

四、文档（docs/）问题

P0：无。全书可读、无断链、无乱码、无未完成段落。

P1（应修复）

A. 引用了 libs.versions.toml 中不存在的别名（4 处，照抄即 Unresolved reference）

B. 示例代码编译级/逻辑级错误（要点）

• 04-ui-view-xml-basics.md:~52,369：顶层扩展函数访问不存在的 resources；Int 接收者调 Float 扩展——两处均无法编译。
• 12-dependency-injection-hilt.md §2.12：匿名 object 继承 final class；对 WhileSubscribed 的 StateFlow 无收集者断言非空——断言必失败。
• 13-background-work-notifications.md §2.7/2.8：Fake 继承带必填构造的 final 类；dispatch 的 if/else 两分支均走本地通知（远程分支死代码）。
• 17-performance-optimization.md §2.1：startup_config.xml 是无效 XML（<resources> 内放占位元素），正确机制是 Manifest 的 tools:node="remove"。
• 19-security-hardening.md:~477：顶层函数标 @Singleton 且不在 @Module 内——Hilt 不会装配。
• 25-techfeed-auth-offline.md:131-144：TokenAuthenticator 文档版同样不调用刷新，且并发测试断言 refreshCount == 1 与 Mutex 实现（只串行化不去重，实际为 3）矛盾——文档与 sample 的 P0-3 同源。
• 09/10/12 章：DI Provider 缺 File 绑定、Room 测试用 ApplicationProvider 却放 src/test、测试示例含必错代码等。

C. 跨章矛盾（同一类在不同章给出冲突实现）

• NetworkModule 在第 09 章（完整版）与第 12 章（简化版）声称同一路径却内容不同；
• EncryptedSharedPreferences 第 10 章称"已进维护状态、推荐替代"，第 19/25 章却作为标准方案——立场相反；
• GetFeedUseCase 第 11 章当接口、第 12 章是 final 类；
• FeedViewModel 构造签名全书出现四个版本（11/12/21/24 章），未标注演进关系，读者按第 11 章写的测试在第 24 章工程里无法编译。

低成本化解方案：在涉及演进的章节开头加一句"本章对第 X 章的 Y 进行了重构"。

P2（择要）

• 第 27 章标注的 docs/samples/ch27/* 文件实际不存在，与第 23 章"每个文件都真实存在于 sample/"的承诺不符；
• 第 22 章 .versionrc.json 代码块用 // 注释（JSON 不支持）；根 build.gradle.kts 片段缺 detekt classpath（与 sample 的 P0-1/P0-2 同源）；
• 深度失衡：第 09-13 章动辄 1000+ 行，收官实战章（23-26）仅 254-303 行，学习者拼不出完整可运行代码；
• 第 26 章练习编号重复、apkalyzer 应为 apkanalyzer；第 21 章测试断言与意图矛盾（断言未截断）；第 06 章 API 命名与第 09 章不一致等。

文档整体优点（值得保持）

1. 28 章 + 双 README 目录与实际文件零偏差，"环境 → Kotlin → … → TechFeed 实战 → 附录"的认知曲线合理无缺口；
2. 一致性执行罕见：全书统一 8 段式章节结构、术语首现带英文、代码块标注 sample/ 真实路径、交叉引用抽查全部正确；
3. 版本纪律好：正文版本号与 libs.versions.toml 一致（仅 4 处别名例外）；
4. 第 11 章（协程/Flow，1320 行）与第 21、22 章达到企业内训/出版水准——CancellationException 永不吞、WhileSubscribed(5000) 动机、"Fake 优先于 Mock"等论述属中文同类资料上乘。

五、sample 工程其他亮点与 P2 择要

亮点：模块治理（16 模块 include 与磁盘零偏差，feature 零依赖仅在 :app 聚合）；TokenProvider 依赖倒置教科书级；Room Flow SSOT 响应式链路完整；测试基建（MainDispatcherRule/Turbine/Truth）专业；安全默认值到位（allowBackup=false、cleartext=false、token 真加密、userId 哈希脱敏）；R8 规则覆盖官方推荐项。

P2 择要：

• 测试缺口：core 9 模块 0 测试；app 声明了整套 androidTest 依赖但一个 androidTest 都不存在；Feed 的 combine 过滤、.catch 分支等核心逻辑零覆盖。
• core/testing/FakeFeedRemoteDataSource 未实现目标接口、缺方法，无法作为测试替身（应改 testFixtures 或接口下沉）。
• Room：ArticleEntity 无任何索引（isFavorite/cachedAt 均全表扫）；upsertKeepingFavorite N+1；clearExpiredCache 从未调用。
• UI：全项目零 @Preview；硬编码中文文案弃用了已定义的 strings.xml；observeFeed(query) 参数被静默忽略；详情页不落库断网必挂；windowBackground 与 Compose 令牌色差不一致。
• 其他：Result 与 kotlin.Result 双轨；model 模块注释称纯 JVM 却用 Parcelable；多处未使用依赖/别名（viewpager2、paging、robolectric 等）；configureondemand=true 与 configuration-cache 兼容性存疑。

六、修复路线图（建议顺序）

第一批 · 让工程编译通过（半天）

1. 生成 Gradle Wrapper（#5）→ 2. 修 build-logic classpath + 宿主 apply false（#1/#2）→ 3. Compose 插件改 CommonExtension（#3）→ 4. app 开 buildConfig（#6）→ 5. logging 拦截器改 implementation（#7）→ 6. 补 FeedRemoteDataSource @Binds（#8）→ 7. 补 NotificationHelper import（#9）→ 8. FeedRepository 接口下沉解耦 push→feed（#10）→ 9. LocalPushChannel 补 @Inject（#11）→ 10. benchmark 模块二选一处理（#4）。完成后全量 assembleDebug + testDebugUnitTest 验证。

第二批 · demo 可用性（1-2 天） isLoading/selected 永假修复、LoginRoute 可达、TokenAuthenticator 真实刷新、登录凭据改 @Body、日志脱敏、通知深链 + onNewIntent、SyncScheduler 接线、CI 测试任务改 ./gradlew test。

第三批 · 文档一致性（1 天） 补 4 处 toml 别名、修 dpToPx/测试示例等编译级错误、为 FeedViewModel 四个签名版本加演进标注、统一 EncryptedSharedPreferences 立场、补 ch27 引用文件或改标注。

第四批 · 长线质量 core 层补测试（DAO/safeCall/TokenAuthenticator 优先）、Room 索引与 N+1、AnrWatchDog 重写、Preview 与 strings 资源化、testFixtures 化 Fake。

报告完。各问题的精确行号与代码引证见审查过程记录；如需任何单项的详细修复 patch，可指定问题编号继续。

📄 android-doc 全量修复记录 REVIEW-FIXES-2026-09-29.md✓ 标记已学

日期：2026-09-29（紧随全量 review，见 REVIEW-2026-09-29.md） 范围：sample 工程全部 P0/P1 与高价值 P2 + 文档全部 P1 与主要 P2

一、sample 工程

批次 1 · 构建体系 P0（6/6 修复）

批次 1 · 代码装配 P0（5/5 修复）

批次 2 · P1 功能（全部修复）

• TokenAuthenticator 真实刷新：Mutex + 双重检查（并发 401 只刷一次）+ 独立裸 OkHttpClient 调 POST v1/auth/refresh（防递归）+ priorResponse 计数限重试 + tokenProvider.refresh() 落盘；新增 NetworkConfig.BASE_URL 单一真相
• 登录凭据改 @Body LoginRequestDto（不再走 URL query）；新增 refresh 端点定义
• Feed 可用性：isLoading 首次加载置位（进度条真正出现）；错误态带重试按钮；空态引导文案；封面 AsyncImage 渲染
• 底部导航选中态：hasRoute(KClass) 正确匹配类型安全路由；非紧凑屏补 NavigationRail
• LoginRoute 可达：401 → NavigateToLogin 事件 + 收藏页空态登录按钮，双入口
• LoginViewModel：成功分支复位 isLoading
• 深链闭环：通知点击 ACTION_VIEW techfeed://article/{id}；暖启动 addOnNewIntentListener 分发；冷启动深链改为 Feed→Detail 入栈（返回键回信息流）；空 articleId 校验
• SyncScheduler 接线（Application.onCreate）+ watchAnr() 接线
• AnrWatchDog 重写：完整阈值判定、reported 去重、stopWatchdog()；CrashReporter 支持 install 安全转型、watchAnr 先停旧、启动时 dispatchPendingReports；CrashStore 上限 10 份 + clearPending
• SecureTokenStorage：双重检查懒加载 + AuthInterceptor runBlocking(Dispatchers.IO) + LoginUseCase withContext(IO) 落盘
• Coil3 网络引擎：feed/detail/profile 三模块补 coil-network-okhttp

批次 4 · 高价值 P2

• Room：ArticleEntity 补 isFavorite/cachedAt 索引；upsertKeepingFavorite 改批量（2 查询 + upsertAll，消灭 N+1）；clearExpiredCache 在 refresh 后接线（7 天策略）
• observeFeed(query) 真正 DB 级过滤，VM 改 flatMapLatest 订阅；FeedViewModel 改用官方 flow.update，删除自造扩展
• FeedViewModelTest 扩到 7 例（新增：搜索过滤链路、401→登录事件、加载态复位）；Fake 遵守 query 契约
• FakeFeedRemoteDataSource 实现真实接口；runSuspendCatching 改 suspend 签名
• strings.xml 资源化（tab 文案）；windowBackground 与 Compose surface 令牌同色（消除冷启动闪色）；收藏图标动态 contentDescription；AppModule 清理过时注释
• sample/README 检查清单更新（wrapper 已补、schemas 不再被忽略）

二、docs 文档（28 章全部处理，P1 全清、P2 主要清）

别名缺失（4/4）：sentry-android / huawei-push / androidx-core-testing / kover 全部落入 libs.versions.toml，文档引用全部可解析（"ArchivedTaskExecutor" 笔误 → InstantTaskExecutorRule）。

编译级示例错误（全部修复）：ch01 Article 补 publishedAt、ch04 dpToPx 两处、ch05 listSaver 标准形式、ch06 Paging API 与 import、ch09 DI File 绑定 + redactHeader + BASE_URL、ch10 测试移 androidTest + observeFeed(query) 对齐、ch11/12/13 的 Fake 继承 final 类与测试必错断言、ch17 无效 XML 改 Manifest 机制、ch18 SentryAndroid.init 上下文、ch19 顶层 @Singleton 包进 @Module、ch21 截断断言/重复依赖/toDisplayDate 出处、ch22 JSON 注释与 detekt classpath、ch26 apkanalyzer 与练习编号。

跨章矛盾（全部化解）：FeedViewModel 四版签名加演进标注（11/12/14/21 → 24 收敛）；ch12 NetworkModule 标注"DI 节选，完整版见 ch09"；ch09 TokenAuthenticator 加"基础版，实际实现见 ch25"指引；EncryptedSharedPreferences 三章立场统一（维护状态但沿用，迁移属进阶练习）；ch20/21/22 变体命名统一 prodStore 风格；ch21 DAO 测试对齐 observeFeed(null)；ch22 detekt 路径对齐 sample 实际。

实战章对齐（ch23-26）：TokenAuthenticator 全段重写（含并发测试双重检查语义）、SyncFeedWorker/SyncScheduler/NotificationHelper/TechFeedApplication 清单与 sample 最终形态逐行对齐、FeedViewModel/FeedScreen 对齐（flatMapLatest/isLoading/401 事件/重试/封面）、LoginUseCase/LoginViewModel/SecureTokenStorage 对齐、AnrWatchDog/CrashReporter 对齐、benchmark 与 CI 对齐。

悬空引用（全部落地）：新建 docs/samples/chXX/ 共 121 个示例文件——全书所有 文件路径： 标注现在均指向真实存在的文件（sample/ 或 docs/samples/）；ch10 的文档自洽版 DAO 等 4 处加"教学简化版"说明；纯片段 3 处改"教学示例"措辞。

三、遗留项（不影响编译与阅读，建议后续单独立项）

1. ch09 网络章的"信封版"教学叙事（ApiResponse + FeedApi + safeApiCall）与 sample 最终形态（TechFeedApi + FeedPageDto + safeCall）是两套并存的演进式写法，已有演进指引，但深度统一需重写约半章。
2. View 体系的 sample 落地：ch04/06/14/16/24 的 View 对照代码现均在 docs/samples/ 下；若希望 sample 工程本身也包含 View 体系模块（FeedFragment/ArticleAdapter 等），影响面大，建议单独立项。
3. 未实际编译验证：本机无 Android SDK/Gradle 环境，所有修复经人工交叉核对但未经 assembleDebug 实测；首次真机导入仍按 sample/README 检查清单排查。
4. core 层测试仍偏薄（database/network 各自的 test 依赖已声明但测试文件未写）；LoginViewModel 测试需先为 LoginUseCase 抽接口。

📄 第 00 章 开发环境搭建：Android Studio、SDK 与调试 00-environment-setup.md✓ 标记已学

阶段：起步 ｜ 预计阅读 40 min ｜ 代码落地模块：无（本章产出第一个可运行 App） 相关章节：第 01 章 Kotlin 速成 ｜ 第 02 章 工程结构与 Gradle

学习目标

读完本章，你应该能够：

• [ ] 独立完成 Android Studio、JDK、Android SDK 的安装与配置，并能解释三者之间的关系。
• [ ] 创建并启动一个模拟器（AVD），也能用一台真机跑通调试。
• [ ] 创建第一个 App 并成功运行到设备上。
• [ ] 熟练使用 Logcat 过滤日志、用 adb 排查安装与启动问题。
• [ ] 知道在国内网络环境下该配哪些镜像源，避免"卡在下载"上浪费两小时。

一、核心概念

1.1 三层工具链的关系

初学者最容易混淆的就是这一堆名词。记住这张图就够了：

flowchart TB
    subgraph IDE["Android Studio（IDE）"]
        A["代码编辑 / 布局预览 / 调试器 / Profiler"]
    end
    subgraph Build["构建层"]
        B["Gradle（构建工具）"]
        C["AGP（Android Gradle Plugin）"]
        D["Kotlin 插件 / KSP"]
    end
    subgraph SDK["Android SDK（平台层）"]
        E["platform-tools → adb"]
        F["platforms → android-37"]
        G["build-tools → 编译打包工具"]
        H["emulator / system-images"]
    end
    subgraph Device["运行载体"]
        I["模拟器 AVD"]
        J["真机（USB / Wi-Fi 调试）"]
    end
    A --> B --> C --> G
    C --> F
    A --> E --> I
    A --> E --> J

一句话总结：Android Studio 是编辑器，Gradle + AGP 负责把代码变成 APK，Android SDK 提供编译和运行所需的平台与工具，设备负责跑起来。

1.2 为什么强调 JDK 版本

AGP 要求固定的最低 JDK 版本（当前基线为 JDK 17）。版本不匹配时你会看到类似报错：

Android Gradle plugin requires Java 17 to run. You are currently using Java 11.

[!TIP] Android Studio 自带一个 JDK（称为 Gradle JDK 或 Embedded JDK）。新手不要自己下载 JDK 再手动指路径，直接在 Settings → Build, Execution, Deployment → Build Tools → Gradle → Gradle JDK 选择 jbr-17 即可。

二、操作步骤

2.1 安装 Android Studio

1. 从官网下载最新稳定版安装包（Windows 为 .exe，macOS 为 .dmg，Linux 为 .tar.gz）。
2. Windows 安装时路径不要包含中文和空格，例如用 D:\Android\Android Studio。中文路径会导致 Gradle 同步出现各种诡异错误。
3. 首次启动选择 Standard 安装类型，让它自动下载 SDK、模拟器与必要组件。
4. 中途出现的 "Android SDK License" 全部 Accept。

[!WARNING] 安装目录、SDK 目录、项目目录、Gradle 缓存目录，全部不要出现中文、空格或特殊字符。这是国内开发者踩得最多的坑之一。

2.2 SDK Manager：装什么

Settings → Android SDK 或工具栏的 SDK Manager 图标，打开后按以下勾选：

• SDK Platforms：勾选你需要的版本。至少要装 targetSdk 对应版本（如 Android 16 / API 36）和一个低版本（如 API 26）用于兼容性验证。
• SDK Tools（务必勾选）：
  • Android SDK Build-Tools（编译打包）
  • Android SDK Platform-Tools（含 adb）
  • Android SDK Command-line Tools（含 sdkmanager、avdmanager）
  • Android Emulator
  • Google Play services（需要地图/推送时）
  • NDK / CMake（只在做 C/C++ 开发时才装，体积巨大）

对应的命令行写法（服务器上搭建 CI 时会用到）：

# 用命令行工具安装指定组件（无图形界面环境必备）
# 路径：sdkmanager 位于 $ANDROID_HOME/cmdline-tools/latest/bin/ 下
sdkmanager --install "platforms;android-36" "build-tools;36.0.0" "platform-tools"

# 查看已安装与可安装的全部组件
sdkmanager --list

# 接受所有许可证（CI 环境必须，否则会卡在交互提示）
yes | sdkmanager --licenses

2.3 国内网络环境配置

Gradle 默认从 services.gradle.org 与 Google Maven 拉取依赖，国内常常超时。两种解决方式：

方式一：配置 gradle.properties（推荐，随项目走）

# 文件路径：<项目根>/gradle.properties
# 分配更大内存，避免大工程 OOM 与频繁 GC
org.gradle.jvmargs=-Xmx2048m -XX:MaxMetaspaceSize=512m -Dfile.encoding=UTF-8
# 开启并行构建与配置缓存，大幅缩短构建时间
org.gradle.parallel=true
org.gradle.caching=true
org.gradle.configuration-cache=true
# 按需配置模块（多模块工程收益明显）
org.gradle.configureondemand=true
# AndroidX 必需
android.useAndroidX=true
# 非传递性 R 类（多模块下减少 R 文件体积、加快编译）
android.nonTransitiveRClass=true

方式二：镜像源

在 settings.gradle.kts 中声明仓库（见第 02 章），把 google() / mavenCentral() 换成国内镜像地址即可。注意：镜像源可能滞后，遇到"某个新版本依赖拉不到"时先切回官方源验证。

[!TIP] 判断是"网络问题"还是"配置问题"的最快方法：看报错是 Could not resolve ...（依赖拉不到，网络/源问题） 还是 Could not find method ...（DSL 写法问题，版本不匹配）。

2.4 创建模拟器（AVD）

Device Manager → Create Device：

1. Hardware：选 Pixel 系列即可（有 Play Store 标记的可直接登录 Google 账号）。
2. System Image：选 Tiramisu 及以上的 x86_64 镜像，ABI 必须匹配你的 CPU。
   • Intel CPU：开启 BIOS 中的 VT-x，装 HAXM 或直接用 Windows 的 WHPX。
   • Apple Silicon Mac：选 arm64-v8a 镜像。
   • AMD CPU：需开启 SVM 并使用 Windows Hypervisor Platform。
3. AVD 配置：RAM 建议 2GB 以上；打开 Enable Device Frame 便于截图；Graphics 设为 Automatic（若启动黑屏则改为 Software）。

启动后用 adb 验证：

# 列出当前连接的所有设备与状态
adb devices
# 期望输出：emulator-5554   device   （状态必须是 device，offline/unauthorized 都有问题）

真机调试（推荐，性能与真实度都远好于模拟器）：

1. 手机 设置 → 关于手机 → 版本号 连点 7 次打开开发者选项。
2. 开发者选项中打开 USB 调试，部分厂商还需打开"USB 安装""USB 调试（安全设置）"。
3. 用数据线连接，手机上授权弹窗点"允许"。
4. Android 11+ 支持无线调试：开发者选项 → 无线调试 → 使用配对码配对设备，然后：

# 无线调试配对（Android 11+），ip:port 在手机"无线调试"页面查看
adb pair 192.168.1.20:37211
# 配对成功后连接
adb connect 192.168.1.20:41573

2.5 创建并运行第一个 App

File → New → New Project → Empty Activity（或 Empty Compose Activity），填写：

点击 Run ▶，选择设备，等待 Gradle 同步 + 构建 + 安装。第一次会慢（几分钟），后续增量构建通常几秒到几十秒。

三、示例代码：第一个可运行的界面

新建工程默认生成一个 Activity 和布局。我们把它改成能体现"数据 → 界面"的最小闭环。

Compose 版

// sample/.../MainActivity.kt（示意：任何 Empty Compose Activity 工程都可直接替换 MainActivity）
package com.example.helloandroid

import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.activity.enableEdgeToEdge
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.padding
import androidx.compose.material3.Button
import androidx.compose.material3.Scaffold
import androidx.compose.material3.Text
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableIntStateOf
import androidx.compose.runtime.saveable.rememberSaveable
import androidx.compose.runtime.setValue
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.dp

class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        // 让内容绘制到系统栏之下，实现沉浸式（Android 15+ 默认生效）
        enableEdgeToEdge()
        // setContent 是 Activity 与 Compose 的桥梁，取代了 setContentView
        setContent {
            // rememberSaveable：横竖屏旋转、进程重建后仍能保留计数
            var count by rememberSaveable { mutableIntStateOf(0) }
            Scaffold { innerPadding ->
                Column(
                    modifier = Modifier
                        .fillMaxSize()
                        .padding(innerPadding)
                        .padding(16.dp),
                    verticalArrangement = Arrangement.Center,
                    horizontalAlignment = Alignment.CenterHorizontally,
                ) {
                    Text(text = "点击次数：$count")
                    Button(onClick = { count++ }) {
                        Text("点我 +1")
                    }
                }
            }
        }
    }
}

View / XML 版

<!-- app/src/main/res/layout/activity_main.xml -->
<?xml version="1.0" encoding="utf-8"?>
<androidx.constraintlayout.widget.ConstraintLayout
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:padding="16dp">

    <!-- TextView 与 Button 通过约束确定位置，避免了多层嵌套 -->
    <TextView
        android:id="@+id/tvCount"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text="点击次数：0"
        android:textSize="20sp"
        app:layout_constraintBottom_toTopOf="@id/btnAdd"
        app:layout_constraintStart_toStartOf="parent"
        app:layout_constraintEnd_toEndOf="parent"
        app:layout_constraintTop_toTopOf="parent"
        app:layout_constraintVertical_chainStyle="packed" />

    <Button
        android:id="@+id/btnAdd"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text="点我 +1"
        app:layout_constraintTop_toBottomOf="@id/tvCount"
        app:layout_constraintStart_toStartOf="parent"
        app:layout_constraintEnd_toEndOf="parent" />

</androidx.constraintlayout.widget.ConstraintLayout>

// app/src/main/java/com/example/helloandroid/MainActivity.kt
package com.example.helloandroid

import android.os.Bundle
import androidx.activity.enableEdgeToEdge
import androidx.appcompat.app.AppCompatActivity
import com.example.helloandroid.databinding.ActivityMainBinding

class MainActivity : AppCompatActivity() {

    // ViewBinding：编译期生成，类型安全，取代 findViewById
    private lateinit var binding: ActivityMainBinding
    private var count = 0

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        enableEdgeToEdge()
        binding = ActivityMainBinding.inflate(layoutInflater)
        setContentView(binding.root)

        // 从 savedInstanceState 恢复计数，处理横竖屏重建
        count = savedInstanceState?.getInt(KEY_COUNT) ?: 0
        renderCount()

        binding.btnAdd.setOnClickListener {
            count++
            renderCount()
        }
    }

    private fun renderCount() {
        binding.tvCount.text = getString(R.string.click_count, count)
    }

    override fun onSaveInstanceState(outState: Bundle) {
        super.onSaveInstanceState(outState)
        outState.putInt(KEY_COUNT, count)
    }

    private companion object {
        const val KEY_COUNT = "key_count"
    }
}

<!-- app/src/main/res/values/strings.xml -->
<resources>
    <string name="app_name">HelloAndroid</string>
    <!-- 用占位符而非拼接，方便国际化 -->
    <string name="click_count">点击次数：%1$d</string>
</resources>

[!TIP] 上面两套写法请各跑一遍。你会直观感受到：Compose 用状态驱动 UI（count 变了 UI 自动更新）， View 体系需要手动 setText 刷新。这个差异是后续所有 UI 知识点的主线。

四、常见坑 ⚠️

五、调试技巧

5.1 Logcat 过滤表达式

Logcat 是 Android 开发的"第一现场"。别再靠肉眼扫日志：

# 只看当前进程的日志（推荐作为默认过滤）
package:com.example.helloandroid

# 只看错误级别
package:com.example.helloandroid level:error

# 按 tag 过滤（支持正则）
tag:MyViewModel

# 组合过滤：本进程 + 排除系统的无用噪声
package:com.example.helloandroid & -tag:OpenGLRenderer & -tag:chatty

在代码里这样输出日志（不要直接用 println）：

// 定义 tag，便于过滤；常量长度限制 23 个字符
private const val TAG = "FeedViewModel"

Log.d(TAG, "加载信息流 page=$page")        // 调试
Log.w(TAG, "接口降级，使用缓存数据")        // 警告
Log.e(TAG, "请求失败", exception)          // 错误，务必带上异常对象

[!WARNING] 正式发布前必须移除敏感日志（Token、手机号、请求体）。用第 19 章介绍的 R8 规则或在 BuildConfig.DEBUG 判断后输出。

5.2 常用 adb 命令速查

# 安装 APK（-r 覆盖安装，-t 允许测试包）
adb install -r app-debug.apk

# 启动某个 Activity（调试深链、指定启动页时非常好用）
adb shell am start -n com.example.helloandroid/.MainActivity

# 查看崩溃与异常的堆栈（配合包名过滤最实用）
adb logcat -v time | grep "AndroidRuntime"

# 强制停止应用（模拟冷启动）
adb shell am force-stop com.example.helloandroid

# 清除应用数据（测试首次启动、清空缓存）
adb shell pm clear com.example.helloandroid

# 截图与录屏（写 bug 单必备）
adb exec-out screencap -p > screen.png
adb shell screenrecord /sdcard/demo.mp4 && adb pull /sdcard/demo.mp4

# 查看当前栈顶 Activity（排查跳转问题）
adb shell dumpsys activity activities | grep mResumedActivity

5.3 断点与调试器

• 条件断点：右键断点 → 设 Condition，只在 page == 3 时停下，避免循环里反复手动放行。
• 日志断点（不暂停）：右键断点 → 取消 Suspend → 勾选 "Evaluate and log"，相当于动态加日志，不用重新编译。
• Attach to Process：App 已经跑起来时，用 Run → Attach Debugger to Android Process 挂上去，不必重启。
• Evaluate Expression：断点处按 Alt+F8，可以现场执行任意表达式，验证猜想最快的方式。

5.4 Layout Inspector 与 Profiler

• Layout Inspector：Tools → Layout Inspector，查看真实运行时的视图树与每个 View 的属性。布局错乱、控件被遮挡时用它定位最快。Compose 工程同样支持，可看到重组次数（Recomposition Counts）。
• Profiler：View → Tool Windows → Profiler，实时看 CPU、内存、网络、电量。第 17 章会详细展开。

六、最佳实践

1. 目录全英文、无空格：安装路径、SDK 路径、工程路径、Gradle 缓存路径，一视同仁。
2. 版本号统一收口：所有依赖版本放 gradle/libs.versions.toml，绝不在 build.gradle.kts 里硬编码（第 02 章）。
3. 包名一次定终身：applicationId 上架后不可更改，立项时就按公司反向域名确定。
4. 优先真机调试：模拟器只在需要验证特定系统版本/屏幕尺寸时使用。
5. 日志分级与脱敏：Log.d 调试、Log.e 带异常对象；Release 包关闭调试日志。
6. 构建失败先读第一行报错：Gradle 报错的有效信息几乎总在最上面几行，后面的 Caused by 是补充。
7. 善用 Gradle 缓存与并行：打开 parallel / caching / configuration-cache，多模块工程构建时间可减半。
8. 遇到诡异问题先 Clean / Invalidate Caches：File → Invalidate Caches / Restart 能解决相当比例的 IDE 玄学问题。

// 旧写法（不推荐）：findViewById 需要强转，空指针风险高，控件多了代码冗长
TextView tv = (TextView) findViewById(R.id.tv_count);
Button btn = (Button) findViewById(R.id.btn_add);
tv.setText("点击次数：" + count);

// 过渡方案：ButterKnife（已停止维护，仅存量项目可见）
@BindView(R.id.tv_count) TextView tv;

七、本章小结

1. 工具链三层：Android Studio（IDE）→ Gradle + AGP（构建）→ Android SDK（平台与工具）→ 设备（运行）。
2. JDK 版本由 AGP 决定，用 Studio 自带的 Embedded JDK 最省心；路径全英文是硬性要求。
3. 模拟器解决"有没有设备"的问题，真机解决"像不像真实用户"的问题，两者都要会。
4. adb 是排查安装/启动/跳转问题的瑞士军刀，adb devices、adb logcat、adb shell am 三个命令要形成肌肉记忆。
5. Logcat 过滤表达式、条件断点、日志断点是日常调试效率的分水岭。

下一章：先补一门 Kotlin 速成课，把空安全、data class、扩展函数、密封类和协程这几个高频语法掌握，后面读代码就不会卡壳。

八、动手练习

基础题

1. 按本章步骤搭建环境，创建 HelloAndroid 工程，分别在模拟器和真机上跑通。
2. 用 adb devices 确认设备状态为 device；用 adb shell am start 手动启动一次 MainActivity。
3. 在 Logcat 中用 package:你的包名 过滤，只看到自己应用的日志。

进阶题 4. 分别用 Compose 和 View/XML 实现同一个计数器，对比两者的状态恢复方式（旋转屏幕后计数是否保留）。 5. 编写一个 debug.sh 脚本，一键完成：卸载旧包 → 安装新包 → 启动首页 → 抓取最近 200 行日志到文件。

思考题 6. 为什么 Android Studio 要自带 JDK，而不能直接用系统里装的 JDK？（提示：CI 环境 reproducibility） 7. 如果你的 App 在模拟器上正常、真机上崩溃，你会按什么顺序排查？（提示：ABI、系统版本、厂商 ROM、权限） 8. applicationId 与代码里的 package 属性有什么区别？为什么上架后不能改 applicationId？

📄 第 01 章 Kotlin 速成与协程预热 01-kotlin-crash-course.md✓ 标记已学

阶段：起步 ｜ 预计阅读 50 min ｜ 代码落地模块：:core:common、:core:model 前置：第 00 章 环境搭建 相关章节：第 11 章 协程与 Flow

学习目标

• [ ] 掌握 Android 开发中最高频的 Kotlin 语法：val/var、空安全、data class、扩展函数、密封类、作用域函数、泛型。
• [ ] 理解 Kotlin 与 Java 的关键差异，能读懂老项目的 Java 代码并改写成 Kotlin。
• [ ] 理解协程的"挂起"到底挂起了什么，能写出不阻塞主线程的异步代码。
• [ ] 能识别常见的 Kotlin 误用（!!、GlobalScope、runBlocking 等）。

一、核心概念

1.1 为什么 Android 选择了 Kotlin

2019 年 Google 宣布 Kotlin-First，原因不是"语法糖多"，而是三点硬收益：

1.2 一张图理解 Kotlin 类型系统

flowchart LR
    A["Any?（可空顶层类型）"] --> B["Any（非空顶层类型）"]
    B --> C["String / Int / 自定义类"]
    A --> D["String? / Int? / 自定义类?"]
    C -.->|"可以赋值给"| D
    D -.->|"需要判空后才能"| C

核心规则：类型默认非空，想允许为空必须显式加 ?。要从一个可空类型拿到非空值，必须过一道"关卡"：?.、?:、!! 或智能转换。

二、示例代码

2.1 变量、常量与类型推断

// 文件路径：docs/samples/ch01/Basics.kt
package com.techfeed.sample.basic

// val = 只读引用（不等于不可变对象），var = 可变引用
val appName: String = "TechFeed"   // 显式类型
val version = 1                     // 类型推断为 Int
var retryCount = 0                  // var 可重新赋值

// 常量：编译期常量，必须是顶层或 object 成员，用 const 修饰
const val MAX_RETRY = 3
const val BASE_URL = "https://api.techfeed.dev/"

// ⚠️ 常见误用：val 修饰的对象内部仍可变
val userList = mutableListOf("A", "B")
userList.add("C")   // 合法：引用没变，是对象内容变了

// 字符串模板：比 Java 拼接清晰得多
fun describe(): String = "$appName v$version, retry=$retryCount"

2.2 空安全：四种判空武器

// 文件路径：docs/samples/ch01/NullSafety.kt
package com.techfeed.sample.basic

data class User(val id: String, val nickname: String?)

fun safeCall(user: User?) {
    // 1. 安全调用 ?. —— 为空则整条链返回 null，不会抛异常
    val length: Int? = user?.nickname?.length

    // 2. Elvis 操作符 ?: —— 为空时提供默认值
    val name: String = user?.nickname ?: "匿名用户"

    // 3. let 作用域函数 —— 仅在非空时执行块内逻辑
    user?.nickname?.let { nickname ->
        println("昵称长度=${nickname.length}")
    }

    // 4. 非空断言 !! —— 为空直接抛 NPE，除非你 100% 确定，否则不要用
    val forced: String = user!!.nickname!!

    // 5. 提前返回 + 智能转换（推荐写法）：之后 user 被智能转为非空类型
    val checked = user ?: return
    println(checked.id)   // 此处 user 已智能转换为 User（非空）
}

// 平台类型（Java 返回的 String!）：Kotlin 无法判断其可空性，需自行判空
fun fromJava(javaValue: String) {
    // 建议：Java API 的结果统一当作可空处理
    val safe: String = javaValue.ifBlank { "default" }
}

[!WARNING] 在业务代码里看到 !! 就应该本能警惕。唯一的合理场景是：onCreate 中你已经明确知道 savedInstanceState != null， 或某个 lateinit 属性在 init 阶段必然赋值。其他情况下，用 ?: return、?: error(...) 或 checkNotNull 替代。

2.3 data class、密封类与枚举

这三个是 Android 分层架构里出镜率最高的语法：

// 文件路径：sample/core/model/src/main/java/com/techfeed/core/model/Article.kt
package com.techfeed.core.model

/**
 * 领域模型：一篇文章。
 * data class 自动生成 equals/hashCode/toString/copy，非常适合做不可变模型。
 */
data class Article(
    val id: String,
    val title: String,
    val summary: String,
    val coverUrl: String?,      // 允许为空：有的文章没有封面
    val author: Author,
    val publishedAt: Long,      // 时间戳，展示层再格式化
    val isFavorite: Boolean = false,  // 默认值，避免每次构造都传
)

data class Author(val id: String, val name: String, val avatarUrl: String?)

/**
 * 结果封装：密封类表达"有限种可能"，配合 when 可做到穷尽检查（无需 else）。
 * 这是全书所有数据层的统一返回类型。
 */
sealed interface Result<out T> {
    data class Success<out T>(val data: T) : Result<T>
    data class Failure(val error: AppError) : Result<Nothing>
    object Loading : Result<Nothing>
}

/** 错误同样用密封类建模，UI 层可以针对不同错误给出不同文案 */
sealed interface AppError {
    data class Network(val cause: Throwable) : AppError
    data class Http(val code: Int, val message: String?) : AppError
    data class Auth(val reason: String) : AppError
    data class Unknown(val cause: Throwable) : AppError
}

使用密封类时，when 必须是穷尽的，编译器会帮你检查：

// 文件路径：docs/samples/ch01/SealedWhen.kt
fun render(result: Result<List<Article>>): String = when (result) {
    is Result.Loading -> "加载中"
    is Result.Success -> "共 ${result.data.size} 篇"
    is Result.Failure -> when (val e = result.error) {
        is AppError.Network -> "网络不可用，请检查连接"
        is AppError.Http -> if (e.code == 404) "内容不存在" else "服务异常(${e.code})"
        is AppError.Auth -> "登录已失效，请重新登录"
        is AppError.Unknown -> "未知错误"
        // 不需要 else：新增子类时这里会编译报错，强制你处理
    }
}

2.4 扩展函数与作用域函数

// 文件路径：sample/core/common/src/main/java/com/techfeed/core/common/Extensions.kt
package com.techfeed.core.common

import java.text.SimpleDateFormat
import java.util.Locale

/**
 * 扩展函数：在不修改类源码、不继承的前提下给类"加方法"。
 * 编译后是静态方法，没有运行时开销。
 */
fun Long.toDisplayDate(): String =
    SimpleDateFormat("yyyy-MM-dd HH:mm", Locale.getDefault()).format(this)

fun String.truncate(max: Int): String =
    if (length <= max) this else substring(0, max) + "…"

// 扩展属性
val String.isHttpUrl: Boolean get() = startsWith("http://") || startsWith("https://")

// 泛型扩展 + 高阶函数：安全执行并统一兜底
inline fun <T> runCatchingOrDefault(default: T, block: () -> T): T = try {
    block()
} catch (t: Throwable) {
    default
}

五个作用域函数怎么选（面试与 CR 高频）：

val intent = Intent(this, DetailActivity::class.java).apply {
    putExtra("article_id", article.id)      // this = Intent
}.also {
    Log.d("Nav", "跳转到详情：${it.extras}")   // it = Intent，仅做副作用
}

2.5 集合与函数式操作

// 文件路径：docs/samples/ch01/Collections.kt
data class Article(val id: String, val title: String, val readMinutes: Int, val tags: List<String>, val publishedAt: Long)

val articles: List<Article> = emptyList()

// 链式操作：注意 map/filter 每次都会产生新的中间集合，超大列表用 asSequence 惰性求值
val titles: List<String> = articles
    .filter { it.readMinutes <= 10 }        // 过滤：10 分钟内可读完
    .sortedByDescending { it.publishedAt }  // 排序
    .map { it.title.truncate(30) }          // 转换

// groupBy / associateBy：把列表变成 Map，列表渲染分组时常用
val byTag: Map<String, List<Article>> = articles
    .flatMap { a -> a.tags.map { tag -> tag to a } }
    .groupBy({ it.first }, { it.second })

// 惰性序列：数据量 > 1万 时避免中间集合开销
val count = articles.asSequence()
    .filter { it.tags.contains("Android") }
    .count()

2.6 协程预热：挂起到底挂起了什么

这是理解协程最关键的一点：

suspend 函数挂起的是协程，不是线程。 当协程挂起时，它所在的线程被释放去做别的事；恢复时可能换到另一个线程继续执行。

sequenceDiagram
    participant M as 主线程
    participant C as 协程
    participant IO as IO 线程
    M->>C: launch { 请求接口 }
    C->>IO: withContext(Dispatchers.IO) 切线程
    Note over M: 主线程空闲，继续渲染 UI、响应点击
    IO-->>C: 网络返回
    C->>M: 自动切回主线程更新 UI

// 文件路径：docs/samples/ch01/CoroutineIntro.kt
import kotlinx.coroutines.*

// suspend：标记这个函数可以"挂起"，只能在协程或其他 suspend 函数中调用
suspend fun loadArticle(id: String): Article {
    // withContext 切换执行线程，执行完自动切回来 —— 这就是"用同步写法表达异步"
    return withContext(Dispatchers.IO) {
        // 这里是 IO 线程，可以做网络 / 数据库操作
        api.getArticle(id)
    }
}

fun main() = runBlocking {   // runBlocking 会阻塞当前线程，仅用于 main 与测试，业务代码禁用
    val job = launch {       // launch 启动一个不返回结果的协程
        val article = loadArticle("a-001")
        println("拿到文章：${article.title}")   // 已在主线程，可直接更新 UI
    }
    job.join()               // 等待协程结束
}

三个必须记住的协程概念：

// Android 中的标准写法（第 11 章展开）
class FeedViewModel : ViewModel() {
    fun refresh() {
        // viewModelScope 随 ViewModel 销毁自动取消，无需手动管理
        viewModelScope.launch {
            try {
                val list = repository.getFeed(page = 1)
                _uiState.update { it.copy(articles = list) }
            } catch (e: CancellationException) {
                throw e   // ⚠️ 取消异常必须向上抛，不能被 catch 吞掉
            } catch (e: Exception) {
                _uiState.update { it.copy(error = e.message) }
            }
        }
    }
}

[!TIP] CancellationException 是协程取消的正常信号，不是错误。用 catch (e: Exception) 会把它一起吞掉，导致协程无法真正取消——这是协程最隐蔽的坑之一。

三、常见坑 ⚠️

四、调试技巧

1. 看 Kotlin 字节码：Tools → Kotlin → Show Kotlin Bytecode，再点 Decompile 反编译成 Java。想搞懂 data class、扩展函数、when 到底生成了什么，这是最直接的方法。
2. 协程调试：在 Run/Debug Configurations 中开启协程调试，或运行时加 VM 参数：

   -Dkotlinx.coroutines.debug=on
   

   之后日志里的线程名会带上协程信息：@coroutine#3。
3. 打印当前协程上下文：

   println("当前线程=${Thread.currentThread().name}, dispatcher=${coroutineContext[ContinuationInterceptor]}")
   

4. 异常堆栈丢失：协程抛出但没打印？在 Application 里设置 Thread.setDefaultUncaughtExceptionHandler（第 18 章会做成崩溃采集）。
5. kotlin.runCatching 陷阱：它会连 CancellationException 一起捕获。协程中优先手写 try/catch 并重新抛出取消异常。

五、最佳实践

1. 默认 val，只有真正需要重新赋值才用 var；字段默认不可变能消掉大量并发与状态 bug。
2. 消灭 !!：把"它可能为空"当作设计信号，用 ?: return、requireNotNull、checkNotNull 明确表达。
3. 数据模型用 data class + 不可变字段：配合 Compose 与 StateFlow，能天然避免"改了对象但 UI 没刷新"。
4. 状态与错误用密封类建模：让编译器帮你做穷尽检查，新增状态时不会漏改 UI。
5. 扩展函数放在 core:common：命名以 toXxx / asXxx 为主，不要把复杂业务逻辑塞进扩展。
6. 禁止 GlobalScope：任何协程都要挂在有明确生命周期的 Scope 上（结构化并发）。
7. suspend 函数必须是主线程安全的：内部自行 withContext 切线程，让调用方无需关心线程。
8. 集合操作链式不超过 3 层：可读性优先，超过就拆成中间变量并加注释。

六、本章小结

1. 空安全是 Kotlin 最大的收益：类型默认非空，可空必须显式 ?，用 ?. / ?: / let 而非 !!。
2. data class 承担数据模型，密封类承担状态与结果建模，两者是分层架构的语法基石。
3. 扩展函数零成本增强类能力，作用域函数五选一按"返回值 + 上下文名"来记。
4. 协程挂起的是协程不是线程：suspend + withContext 让你用同步代码写异步逻辑。
5. 结构化并发：viewModelScope 自动取消、禁用 GlobalScope、CancellationException 不能吞。

下一章：进入工程内部，看清一个 Android 项目的目录结构与 Gradle 构建脚本到底怎么组织。

七、动手练习

基础题

1. 定义 data class Comment(val id: String, val content: String, val liked: Boolean)，写一个函数把 List<Comment> 按 liked 分组统计数量。
2. 给 String 写扩展函数 toMaskedPhone()，把 13812345678 转成 138****5678，并处理好长度不足 11 位的情况（不要抛异常）。
3. 用密封类建模"登录状态"：Idle / Loading / Success(user) / Error(message)，写一个 when 渲染函数做到穷尽。

进阶题 4. 把下面这段回调式代码改写成协程版本，并说明改写后为什么不会阻塞主线程：

api.getFeed(object : Callback<List<Article>> {
    override fun onSuccess(data: List<Article>) { runOnUiThread { render(data) } }
    override fun onFailure(e: Throwable) { runOnUiThread { showError(e) } }
})

5. 写一个 suspend fun <T> retry(times: Int, block: suspend () -> T): T，要求：失败重试、可取消（遇到 CancellationException 立即抛出）、最后一次失败才抛异常。

思考题 6. 为什么 val list = mutableListOf<Int>() 里的 list 是只读的，但内容却能改？这在多模块架构里会带来什么风险？如何设计不可变 API？ 7. runBlocking 在 Android 主线程调用会发生什么？为什么测试代码里反而推荐用它？ 8. 密封类相比"用 Int 常量 + when else"的方案，在团队协作与重构安全上有什么具体优势？

📄 第 02 章 工程结构与 Gradle 构建 02-project-structure-and-gradle.md✓ 标记已学

阶段：入门 ｜ 预计阅读 45 min ｜ 代码落地模块：工程根目录、build.gradle.kts、gradle/libs.versions.toml 前置：第 00 章 环境搭建 相关章节：第 15 章 模块化与组件化 ｜ 第 20 章 构建配置与发布

学习目标

• [ ] 能说出 Android 工程每个目录的作用，知道代码、资源、清单各自放在哪。
• [ ] 读懂并修改 build.gradle.kts，理解 AGP、Gradle、Kotlin 插件三者的职责边界。
• [ ] 掌握 Version Catalog（libs.versions.toml），把依赖版本统一收口。
• [ ] 理解一次构建的完整流程，能定位"构建慢""同步失败"的原因。
• [ ] 知道 applicationId、namespace、R 类、BuildConfig 这些容易混淆的概念。

一、核心概念

1.1 工程目录树

一个新建的 Android 工程长这样（只列出需要你真正理解的目录）：

MyApp/
├─ settings.gradle.kts            # 声明"这个工程包含哪些模块" + 仓库地址
├─ build.gradle.kts               # 根工程脚本：声明插件（通常 apply false）
├─ gradle.properties              # Gradle / JVM 参数开关
├─ gradle/
│  ├─ libs.versions.toml          # 【版本目录】所有依赖版本集中在此
│  └─ wrapper/gradle-wrapper.properties   # Gradle 版本（团队必须一致）
├─ app/
│  ├─ build.gradle.kts            # 模块脚本：插件、SDK 版本、依赖
│  ├─ proguard-rules.pro          # 混淆规则（第 19 章）
│  └─ src/
│     ├─ main/
│     │  ├─ AndroidManifest.xml   # 组件声明、权限、应用配置
│     │  ├─ java/...              # Kotlin/Java 源码（按包名分目录）
│     │  └─ res/                  # 资源（见第 07 章）
│     │     ├─ layout/ values/ drawable/ mipmap/ xml/ navigation/
│     ├─ debug/                   # 变体专属源码（sourceSet）
│     ├─ release/
│     ├─ test/                    # 单元测试（JVM，跑在本地）
│     └─ androidTest/             # 仪器化测试（跑在设备上）
└─ build/                          # 构建产物，不进版本库

[!TIP] src/main/java 目录里放 Kotlin 文件是完全正常的（历史遗留）。新工程也可以用 src/main/kotlin，二者等价，选定后团队统一即可。

1.2 三份 Gradle 脚本的分工

1.3 命名空间 vs 应用 ID

这是初学者最容易混淆的一对概念：

// 文件路径：sample/feature/feed/build.gradle.kts
android {
    namespace = "com.techfeed.feature.feed"   // 决定 R / BuildConfig 包名
    // 只有 application 模块才写 applicationId
    compileSdk = 37
}

[!WARNING] 多模块工程里，模块 A 引用模块 B 的资源时要用 B 的 namespace 对应的 R 类（com.techfeed.core.designsystem.R）。 打开 android.nonTransitiveRClass=true 后，不再有"万能 R"，这是有意为之——它让模块边界更清晰、编译更快。

二、示例代码

2.1 settings.gradle.kts

// 文件路径：sample/settings.gradle.kts
pluginManagement {
    // 约定插件工程（build-logic）作为复合构建引入，供模块脚本使用 techfeed.* 插件
    includeBuild("build-logic")
    repositories {
        google {
            content {
                // 限定这个仓库只提供这些 group 的构件，加快解析
                includeGroupByRegex("com\\.android.*")
                includeGroupByRegex("com\\.google.*")
                includeGroupByRegex("androidx.*")
            }
        }
        mavenCentral()
        gradlePluginPortal()
    }
}

dependencyResolutionManagement {
    // 严格模式：禁止在模块脚本里单独声明仓库，避免依赖来源混乱
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        // 国内加速可在此追加镜像源
        // maven("https://maven.aliyun.com/repository/google")
    }
}

rootProject.name = "TechFeed"
// 开启构建缓存与配置缓存（配合 gradle.properties）
enableFeaturePreview("TYPESAFE_PROJECT_ACCESSORS")

// —— 模块注册：每一条 include 对应一个 Gradle 模块 ——
include(":app")
include(":core:model")
include(":core:common")
include(":core:designsystem")
include(":core:network")
include(":core:database")
include(":core:datastore")
include(":core:navigation-api")
include(":core:crash")
include(":core:testing")
include(":feature:feed")
include(":feature:detail")
include(":feature:auth")
include(":feature:profile")
include(":feature:push")

2.2 版本目录：唯一版本真相

# 文件路径：sample/gradle/libs.versions.toml
[versions]
agp = "9.0.0"
kotlin = "2.4.0"
ksp = "2.4.0-1.0.0"
compileSdk = "37"
targetSdk = "36"
minSdk = "26"
composeBom = "2026.08.00"
hilt = "2.57.0"
hiltNavigationCompose = "1.2.0"
retrofit = "3.0.0"
okhttp = "5.1.0"
retrofitKotlinxSerialization = "1.0.0"
kotlinxSerialization = "1.9.0"
room = "2.8.0"
datastore = "1.2.0"
coroutines = "1.10.2"
lifecycle = "2.9.0"
activityCompose = "1.11.0"
navigationCompose = "2.9.0"
workManager = "2.11.0"
coil = "3.2.0"
junit = "4.13.2"
truth = "1.4.4"
turbine = "1.2.1"
mockk = "1.14.0"

[libraries]
androidx-core-ktx = { module = "androidx.core:core-ktx", version.ref = "coreKtx" }
androidx-lifecycle-runtime-ktx = { module = "androidx.lifecycle:lifecycle-runtime-ktx", version.ref = "lifecycle" }
androidx-lifecycle-viewmodel-compose = { module = "androidx.lifecycle:lifecycle-viewmodel-compose", version.ref = "lifecycle" }
androidx-activity-compose = { module = "androidx.activity:activity-compose", version.ref = "activityCompose" }
androidx-navigation-compose = { module = "androidx.navigation:navigation-compose", version.ref = "navigationCompose" }
androidx-compose-bom = { module = "androidx.compose:compose-bom", version.ref = "composeBom" }
androidx-compose-ui = { module = "androidx.compose.ui:ui" }
androidx-compose-ui-graphics = { module = "androidx.compose.ui:ui-graphics" }
androidx-compose-ui-tooling = { module = "androidx.compose.ui:ui-tooling" }
androidx-compose-ui-tooling-preview = { module = "androidx.compose.ui:ui-tooling-preview" }
androidx-compose-material3 = { module = "androidx.compose.material3:material3" }
androidx-hilt-navigation-compose = { module = "androidx.hilt:hilt-navigation-compose", version.ref = "hiltNavigationCompose" }
androidx-work-runtime-ktx = { module = "androidx.work:work-runtime-ktx", version.ref = "workManager" }
androidx-room-runtime = { module = "androidx.room:room-runtime", version.ref = "room" }
androidx-room-ktx = { module = "androidx.room:room-ktx", version.ref = "room" }
androidx-room-compiler = { module = "androidx.room:room-compiler", version.ref = "room" }
androidx-datastore-preferences = { module = "androidx.datastore:datastore-preferences", version.ref = "datastore" }
retrofit-core = { module = "com.squareup.retrofit2:retrofit", version.ref = "retrofit" }
retrofit-kotlinx-serialization = { module = "com.squareup.retrofit2:converter-kotlinx-serialization", version.ref = "retrofitKotlinxSerialization" }
okhttp-core = { module = "com.squareup.okhttp3:okhttp", version.ref = "okhttp" }
okhttp-logging = { module = "com.squareup.okhttp3:logging-interceptor", version.ref = "okhttp" }
kotlinx-serialization-json = { module = "org.jetbrains.kotlinx:kotlinx-serialization-json", version.ref = "kotlinxSerialization" }
kotlinx-coroutines-android = { module = "org.jetbrains.kotlinx:kotlinx-coroutines-android", version.ref = "coroutines" }
kotlinx-coroutines-test = { module = "org.jetbrains.kotlinx:kotlinx-coroutines-test", version.ref = "coroutines" }
hilt-android = { module = "com.google.dagger:hilt-android", version.ref = "hilt" }
hilt-compiler = { module = "com.google.dagger:hilt-android-compiler", version.ref = "hilt" }
hilt-android-testing = { module = "com.google.dagger:hilt-android-testing", version.ref = "hilt" }
coil-compose = { module = "io.coil-kt.coil3:coil-compose", version.ref = "coil" }
junit = { module = "junit:junit", version.ref = "junit" }
truth = { module = "com.google.truth:truth", version.ref = "truth" }
turbine = { module = "app.cash.turbine:turbine", version.ref = "turbine" }
mockk = { module = "io.mockk:mockk", version.ref = "mockk" }

[plugins]
android-application = { id = "com.android.application", version.ref = "agp" }
android-library = { id = "com.android.library", version.ref = "agp" }
kotlin-android = { id = "org.jetbrains.kotlin.android", version.ref = "kotlin" }
kotlin-compose = { id = "org.jetbrains.kotlin.plugin.compose", version.ref = "kotlin" }
kotlin-serialization = { id = "org.jetbrains.kotlin.plugin.serialization", version.ref = "kotlin" }
ksp = { id = "com.google.devtools.ksp", version.ref = "ksp" }
hilt = { id = "com.google.dagger.hilt.android", version.ref = "hilt" }
room = { id = "androidx.room", version.ref = "room" }

[bundles]
compose = ["androidx-compose-ui", "androidx-compose-ui-graphics", "androidx-compose-ui-tooling-preview", "androidx-compose-material3"]
room = ["androidx-room-runtime", "androidx-room-ktx"]
network = ["retrofit-core", "retrofit-kotlinx-serialization", "okhttp-core", "kotlinx-serialization-json"]
testing-unit = ["junit", "truth", "turbine", "kotlinx-coroutines-test"]

[!NOTE] 上面是实际 libs.versions.toml 的节选（完整文件还包含监控、测试、约定插件等分组，见 sample/gradle/libs.versions.toml），且有一处 version.ref = "coreKtx" 未在 [versions] 中定义——实际工程里请补上 coreKtx = "1.17.0"。 这类"引用了不存在的 version"是版本目录最常见的同步错误，报错信息是 Version 'coreKtx' wasn't found。

2.3 根 build.gradle.kts

// 文件路径：sample/build.gradle.kts
// 插件只声明、不应用；子模块各自 apply，避免所有模块都背上不必要的插件开销
plugins {
    alias(libs.plugins.android.application) apply false
    alias(libs.plugins.android.library) apply false
    alias(libs.plugins.kotlin.android) apply false
    alias(libs.plugins.kotlin.compose) apply false
    alias(libs.plugins.kotlin.serialization) apply false
    alias(libs.plugins.ksp) apply false
    alias(libs.plugins.hilt) apply false
    alias(libs.plugins.room) apply false
}

2.4 模块脚本：application 与 library 的差异

// 文件路径：sample/app/build.gradle.kts
plugins {
    alias(libs.plugins.android.application)
    alias(libs.plugins.kotlin.android)
    alias(libs.plugins.kotlin.compose)
    alias(libs.plugins.ksp)
    alias(libs.plugins.hilt)
}

android {
    namespace = "com.techfeed.app"
    compileSdk = libs.versions.compileSdk.get().toInt()

    defaultConfig {
        applicationId = "com.techfeed.app"     // 唯一切勿随意改
        minSdk = libs.versions.minSdk.get().toInt()
        targetSdk = libs.versions.targetSdk.get().toInt()
        versionCode = 1                         // 递增整数，市场用来判断新旧
        versionName = "1.0.0"                   // 展示给用户的版本
        testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
    }

    buildTypes {
        debug {
            // debug 包加后缀，便于与 release 共存
            applicationIdSuffix = ".debug"
            versionNameSuffix = "-debug"
            isMinifyEnabled = false
        }
        release {
            isMinifyEnabled = true
            isShrinkResources = true            // 移除未引用资源
            proguardFiles(
                getDefaultProguardFile("proguard-android-optimize.txt"),
                "proguard-rules.pro",
            )
            signingConfig = signingConfigs.getByName("debug")   // 演示用，正式见第 20 章
        }
    }

    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_17
        targetCompatibility = JavaVersion.VERSION_17
    }
    kotlinOptions {
        jvmTarget = "17"
        // 开启显式 API 模式（库模块推荐）：强制写返回值与可见性，防止 API 失控
        // freeCompilerArgs += "-Xexplicit-api=strict"
    }
    buildFeatures {
        compose = true
        buildConfig = true
    }
    packaging {
        resources {
            // 排除重复许可文件，避免打包失败
            excludes += "/META-INF/{AL2.0,LGPL2.1}"
        }
    }
}

dependencies {
    implementation(projects.core.designsystem)
    implementation(projects.core.navigationApi)
    implementation(projects.feature.feed)
    implementation(projects.feature.detail)
    implementation(projects.feature.auth)
    implementation(projects.feature.profile)
    implementation(projects.feature.push)

    implementation(platform(libs.androidx.compose.bom))
    implementation(libs.bundles.compose)
    implementation(libs.androidx.activity.compose)
    implementation(libs.androidx.navigation.compose)
    implementation(libs.androidx.hilt.navigation.compose)
    implementation(libs.hilt.android)
    ksp(libs.hilt.compiler)
    implementation(libs.kotlinx.coroutines.android)

    testImplementation(libs.bundles.testing.unit)
    debugImplementation(libs.androidx.compose.ui.tooling)
}

library 模块（以 :core:network 为例）的差异点只有三处：插件用 android.library、没有 applicationId、对外 API 建议开显式模式。

// 文件路径：sample/core/network/build.gradle.kts
plugins {
    alias(libs.plugins.android.library)
    alias(libs.plugins.kotlin.android)
    alias(libs.plugins.kotlin.serialization)
    alias(libs.plugins.ksp)
    alias(libs.plugins.hilt)
}

android {
    namespace = "com.techfeed.core.network"
    compileSdk = libs.versions.compileSdk.get().toInt()

    defaultConfig {
        minSdk = libs.versions.minSdk.get().toInt()
        // 库模块对外暴露的 API 建议开启显式模式，避免内部实现泄漏
        consumerProguardFiles("consumer-rules.pro")
    }

    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_17
        targetCompatibility = JavaVersion.VERSION_17
    }
}

dependencies {
    // api：传递给依赖方（本模块的类型出现在对外 API 签名里时用 api）
    api(projects.core.model)
    // implementation：不传递，编译更快、边界更清晰（默认就用这个）
    implementation(projects.core.common)
    implementation(libs.bundles.network)
    debugImplementation(libs.okhttp.logging)

    implementation(libs.hilt.android)
    ksp(libs.hilt.compiler)

    testImplementation(libs.bundles.testing.unit)
}

[!TIP] api vs implementation 的抉择：如果依赖类型出现在你模块的公开签名里（函数返回值、参数、父类），用 api；否则一律 implementation。 滥用 api 会让改动一个底层模块触发全量重编译，是多模块工程变慢的头号原因。

2.5 抽公共配置：约定插件

15 个模块都写一遍 compileSdk、JavaVersion、compileOptions 太蠢。企业级做法是用 Convention Plugin（约定插件）收口：

// 文件路径：sample/build-logic/convention/src/main/kotlin/AndroidLibraryConventionPlugin.kt
import com.android.build.gradle.LibraryExtension
import org.gradle.api.Plugin
import org.gradle.api.Project
import org.gradle.kotlin.dsl.configure

/** 所有 library 模块共用的 Android 配置，模块脚本只需 apply 这一行 */
class AndroidLibraryConventionPlugin : Plugin<Project> {
    override fun apply(target: Project) {
        with(target) {
            with(pluginManager) {
                apply("com.android.library")
                apply("org.jetbrains.kotlin.android")
            }
            extensions.configure<LibraryExtension> {
                compileSdk = 37
                defaultConfig { minSdk = 26 }
                compileOptions {
                    sourceCompatibility = JavaVersion.VERSION_17
                    targetCompatibility = JavaVersion.VERSION_17
                }
                // 统一开启：非传递 R 类、资源排除
                androidResources { }
                packaging { resources { excludes += "/META-INF/{AL2.0,LGPL2.1}" } }
            }
        }
    }
}

模块脚本随之简化为：

plugins {
    alias(libs.plugins.techfeed.android.library)   // 自定义约定插件
    alias(libs.plugins.techfeed.hilt)
}

[!NOTE] build-logic 需要在 settings.gradle.kts 中用 includeBuild("build-logic") 引入。 这是 Google 官方 nowinandroid 示例工程的做法，中大型项目强烈建议照搬。

三、构建流程全景

flowchart LR
    A["源码 .kt<br/>资源 res/"] --> B["Kotlin 编译"]
    B --> C["KSP 注解处理<br/>Room / Hilt 生成代码"]
    C --> D["AAPT2 编译资源<br/>生成 R 类"]
    B --> E["DEX 转换<br/>.class → .dex"]
    D --> E
    E --> F["打包 APK<br/>签名 / 对齐"]
    F --> G["R8 混淆压缩<br/>仅 release"]
    G --> H["可安装产物"]

Gradle 的三个阶段：初始化（读 settings，确定模块）→ 配置（执行所有 build.gradle.kts，建立任务图）→ 执行（跑需要的 Task）。

理解这一点就能明白：

• 配置阶段每次同步都会全量执行，所以配置代码里不能做耗时操作（读文件、发网络请求）。
• 打开 configuration-cache 后，配置结果会被缓存，第二次构建显著变快。

四、常见坑 ⚠️

五、调试技巧

# 1. 查看依赖树，定位冲突与意外引入的传递依赖
./gradlew :app:dependencies --configuration releaseRuntimeClasspath

# 2. 谁引入了 okhttp？（dependencyInsight 是依赖冲突排查利器）
./gradlew :app:dependencyInsight --dependency okhttp --configuration debugRuntimeClasspath

# 3. 构建性能剖析：生成 HTML 报告，看哪个 Task 最慢
./gradlew assembleDebug --profile

# 4. 只构建某个模块，缩短反馈周期
./gradlew :feature:feed:assembleDebug

# 5. 查看某个 Task 为什么被认为是 out-of-date
./gradlew :app:assembleDebug --info | grep -i "task.*not up-to-date"

# 6. 强制刷新动态版本 / 缓存
./gradlew build --refresh-dependencies

# 7. 列出所有可执行任务（找不着入口时用）
./gradlew :app:tasks --all

Android Studio 里：

• Build → Analyze Build Performance（或 Build Analyzer）能可视化显示每个 Task 耗时与配置阶段瓶颈。
• File → Project Structure → Dependencies 可以图形化看模块间依赖关系，发现循环依赖。

六、最佳实践

1. 版本全部收口到 libs.versions.toml：模块脚本里出现硬编码版本号一律视为 CR 不通过。
2. 优先 implementation：api 只在类型出现在公开签名时使用，滥用会让多模块构建退化成单体。
3. minSdk/compileSdk 用约定插件统一：避免 A 模块 26、B 模块 28 这种混乱。
4. 提交 Gradle Wrapper：团队协作必须用同一 Gradle 版本，CI 与本地才一致。
5. 打开 configuration-cache 与 parallel：多模块工程收益巨大，但要确认所有插件都支持。
6. namespace 与源码包名保持一致：不一致会让 R 类、Manifest 引用变得难以理解。
7. 不要在配置阶段做 I/O：读文件、发请求、解析 JSON 都会拖慢每次同步。
8. .gitignore 必须排除 build/、.gradle/、local.properties：local.properties 含本机 SDK 路径，绝不能提交。

七、本章小结

1. 目录职责：src/main（代码+资源+清单）、src/test（本地单测）、src/androidTest（仪器化测试）、变体源码集。
2. 三份脚本分工：settings（模块与仓库）、根脚本（插件版本）、模块脚本（插件+SDK+依赖）。
3. namespace 决定 R 类包名，applicationId 是市场唯一标识，上架后不可改。
4. 版本目录 libs.versions.toml 是唯一版本真相，api 与 implementation 的选择直接影响构建速度。
5. 构建三阶段：初始化 → 配置 → 执行；配置阶段要做的事越少越好。

下一章：进入 Android 的核心——四大应用组件与生命周期，理解系统在什么时候创建和销毁你的代码。

八、动手练习

基础题

1. 新建一个工程，把 compileSdk、minSdk 改成从 libs.versions.toml 读取（用 libs.versions.xxx.get().toInt()）。
2. 新建一个 core:common library 模块，在 app 中用 implementation(projects.core.common) 依赖它，调用其中的一个函数。
3. 用 ./gradlew :app:dependencies 找出工程里 okhttp 的版本，并说明它是被谁引入的。

进阶题 4. 把 app 与 core:common 中重复的 compileOptions、minSdk 抽成一个约定插件 techfeed.android.library，让两个模块脚本各只剩 plugins 与 dependencies。 5. 为工程添加 debug / release 两种构建类型，debug 加 applicationIdSuffix = ".debug"，验证两个包能同时安装在手机上。

思考题 6. 为什么 applicationId 上架后不能改，而 namespace 可以改？如果公司要求给不同渠道打不同的包，应该改哪个字段？（提示：第 20 章 productFlavors） 7. 一个 20 模块工程把某个底层库从 implementation 改成 api，构建时间会发生什么变化？为什么？ 8. 为什么 Gradle 要区分"配置阶段"和"执行阶段"？如果允许在配置阶段发网络请求，会带来什么问题？

📄 第 03 章 应用组件与生命周期 03-app-components-and-lifecycle.md✓ 标记已学

阶段：入门 ｜ 预计阅读 55 min ｜ 代码落地模块：:app、:feature:* 前置：第 02 章 工程结构与 Gradle 相关章节：第 06 章 列表与导航 ｜ 第 14 章 分层架构

学习目标

• [ ] 理解 Android 四大组件（Activity、Service、BroadcastReceiver、ContentProvider）各自的定位与使用场景。
• [ ] 能画出 Activity / Fragment 生命周期图，并说清每个回调该干什么、不该干什么。
• [ ] 理解配置变更（旋转屏幕）与"进程被系统杀死后重建"的区别，能正确保存与恢复状态。
• [ ] 理解任务栈（Task）与启动模式（launchMode），能处理"重复打开页面""回退顺序异常"这类问题。
• [ ] 知道 ViewModel 为什么能"跨越"配置变更，以及它到底能解决什么问题、不能解决什么。

一、核心概念

1.1 四大组件

[!IMPORTANT] 所有组件都必须在 AndroidManifest.xml 中声明，未声明的组件无法启动（Activity 会抛 ActivityNotFoundException）。 唯一例外是动态注册的 BroadcastReceiver（代码中注册，随上下文生命周期）。

1.2 Activity 生命周期

stateDiagram-v2
    [*] --> onCreate
    onCreate --> onStart : 创建视图
    onStart --> onResume : 可见
    onResume --> onPause : 部分遮挡/跳转
    onPause --> onStop : 完全不可见
    onStop --> onDestroy : 销毁
    onStop --> onRestart : 再次回到前台
    onRestart --> onStart
    onPause --> onResume : 遮挡消失
    onDestroy --> [*]

各回调的"该做 / 不该做"：

[!WARNING] onDestroy 不保证被调用（系统杀进程时直接终止）。因此"退出时保存数据"必须放在 onPause 或 onStop， 或用 ViewModel + SavedStateHandle 承载。

1.3 Fragment 生命周期：为什么会多出一倍

Fragment 的生命周期比 Activity 多了一套视图生命周期（onCreateView / onViewCreated / onDestroyView）：

flowchart LR
    A["onAttach"] --> B["onCreate"]
    B --> C["onCreateView<br/>创建 View"]
    C --> D["onViewCreated"]
    D --> E["onStart"] --> F["onResume"]
    F --> G["onPause"] --> H["onStop"]
    H --> I["onDestroyView<br/>销毁 View，Fragment 仍在"]
    I --> J["onDestroy"] --> K["onDetach"]
    I -.->|"回退栈返回时重新创建视图"| C

关键点：Fragment 实例可以比它的 View 活得更久（进入回退栈时 View 被销毁但 Fragment 对象保留）。

// ⚠️ 经典泄漏：Fragment 实例还在，但 View 已销毁，binding 持有整个视图树
class FeedFragment : Fragment() {
    private var _binding: FragmentFeedBinding? = null
    private val binding get() = _binding!!   // 视图销毁后访问会崩

    override fun onCreateView(inflater: LayoutInflater, container: ViewGroup?, saved: Bundle?): View {
        _binding = FragmentFeedBinding.inflate(inflater, container, false)
        return binding.root
    }

    override fun onDestroyView() {
        super.onDestroyView()
        _binding = null   // 必须置空，切断对视图树的引用
    }
}

[!TIP] Compose 项目里还需要 Fragment 吗？ 单 Activity + 纯 Compose 架构下，不需要 Fragment。Fragment 只在两种场景保留： ① 存量 View 项目渐进迁移；② 需要嵌入到别人的 Fragment 容器里。新项目直接用 Navigation-Compose（第 06 章）。

1.4 配置变更与状态恢复

两种"页面重建"，处理方式完全不同：

// ViewModel 跨越配置变更，但不跨进程重建 —— 所以要配合 SavedStateHandle
class FeedViewModel(
    private val savedStateHandle: SavedStateHandle,
    private val repository: FeedRepository,
) : ViewModel() {

    // 从 SavedStateHandle 读取：直接返回一个 StateFlow，读写都落盘到 Bundle
    val query: StateFlow<String> = savedStateHandle.getStateFlow(KEY_QUERY, "")

    fun onQueryChanged(text: String) {
        savedStateHandle[KEY_QUERY] = text   // 写入后即使进程被杀也能恢复
    }

    companion object {
        private const val KEY_QUERY = "query"
    }
}

1.5 任务栈与启动模式

Android 用**任务栈（Task）**管理 Activity，后进先出。启动模式决定"新 Activity 如何入栈"：

Intent Flag 更灵活，常用于运行时控制：

val intent = Intent(this, MainActivity::class.java).apply {
    // 清空栈顶之上的所有 Activity 并复用已存在的 MainActivity（回到主页的标准做法）
    flags = Intent.FLAG_ACTIVITY_CLEAR_TOP or Intent.FLAG_ACTIVITY_SINGLE_TOP
}
startActivity(intent)

二、示例代码

2.1 Manifest 声明

<!-- 文件路径：sample/app/src/main/AndroidManifest.xml -->
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools">

    <!-- 权限声明：危险权限还需运行时申请（见第 08 章） -->
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />

    <application
        android:name=".TechFeedApplication"
        android:allowBackup="false"
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name"
        android:roundIcon="@mipmap/ic_launcher_round"
        android:supportsRtl="true"
        android:theme="@style/Theme.TechFeed"
        android:usesCleartextTraffic="false"
        tools:targetApi="31">

        <!-- 启动 Activity：MAIN + LAUNCHER 决定了桌面图标点开哪个页面 -->
        <activity
            android:name=".MainActivity"
            android:exported="true"
            android:launchMode="singleTop"
            android:windowSoftInputMode="adjustResize"
            android:theme="@style/Theme.TechFeed">

            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>

            <!-- 深链：点击 https://techfeed.dev/article/123 直接进详情 -->
            <intent-filter android:autoVerify="true">
                <action android:name="android.intent.action.VIEW" />
                <category android:name="android.intent.category.DEFAULT" />
                <category android:name="android.intent.category.BROWSABLE" />
                <data android:scheme="https" android:host="techfeed.dev" android:pathPrefix="/article" />
            </intent-filter>
        </activity>

        <!-- 内部页面不导出，避免被其他应用调起 -->
        <activity android:name=".host.HostActivity" android:exported="false" />

        <!-- 前台服务必须声明 foregroundServiceType（Android 14+ 强制） -->
        <service
            android:name=".push.SyncService"
            android:exported="false"
            android:foregroundServiceType="dataSync" />

        <!-- 静态广播：Android 8+ 大部分隐式广播已被禁，这里只保留显式 -->
        <receiver android:name=".push.BootReceiver" android:exported="false" />
    </application>
</manifest>

[!WARNING] Android 12+ 所有带 intent-filter 的组件必须显式声明 android:exported，否则安装时报错 Targeting S+ requires that an explicit value for android:exported be defined。 不需要被外部调起的一律写 false，这是安全加固的第一道门（第 19 章）。

2.2 Activity：Compose 宿主

// 文件路径：sample/app/src/main/java/com/techfeed/app/MainActivity.kt
package com.techfeed.app

import android.content.Intent
import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.activity.enableEdgeToEdge
import androidx.compose.runtime.DisposableEffect
import androidx.core.util.Consumer
import androidx.navigation.NavController
import com.techfeed.core.designsystem.theme.TechFeedTheme
import dagger.hilt.android.AndroidEntryPoint

@AndroidEntryPoint   // Hilt 注入入口（第 12 章）
class MainActivity : ComponentActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        enableEdgeToEdge()

        // 处理深链：onNewIntent 在 singleTop 复用时被调用，必须手动更新 Intent
        handleDeepLink(intent)

        setContent {
            TechFeedTheme {
                TechFeedApp()   // 导航壳，见第 06 章
            }
        }
    }

    // singleTop 模式下，新的 Intent 走这里而不是 onCreate
    override fun onNewIntent(intent: Intent) {
        super.onNewIntent(intent)
        setIntent(intent)
        handleDeepLink(intent)
    }

    private fun handleDeepLink(intent: Intent?) {
        val articleId = intent?.data?.lastPathSegment ?: return
        DeepLinkHolder.articleId.value = articleId   // 交给导航层消费
    }
}

2.3 Activity：View 体系 + ViewModel 绑定

// 文件路径：docs/samples/ch03/DetailHostActivity.kt
package com.techfeed.feature.detail.ui

import android.os.Bundle
import androidx.activity.enableEdgeToEdge
import androidx.activity.viewModels
import androidx.appcompat.app.AppCompatActivity
import androidx.core.view.isVisible
import androidx.lifecycle.Lifecycle
import androidx.lifecycle.lifecycleScope
import androidx.lifecycle.repeatOnLifecycle
import com.techfeed.feature.detail.databinding.ActivityDetailBinding
import dagger.hilt.android.AndroidEntryPoint
import kotlinx.coroutines.launch

@AndroidEntryPoint
class DetailHostActivity : AppCompatActivity() {

    private lateinit var binding: ActivityDetailBinding

    // viewModels() 委托：同一 Activity 实例内多次调用返回同一个 ViewModel
    private val viewModel: DetailViewModel by viewModels()

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        enableEdgeToEdge()
        binding = ActivityDetailBinding.inflate(layoutInflater)
        setContentView(binding.root)

        binding.btnFavorite.setOnClickListener {
            viewModel.toggleFavorite()
        }

        observeState()
    }

    private fun observeState() {
        // repeatOnLifecycle(STARTED)：只在页面可见时收集，自动在 STOPPED 时取消
        // ⚠️ 这是 Flow 在 UI 层收集的标准写法，直接 lifecycleScope.launch{} 会浪费资源
        lifecycleScope.launch {
            repeatOnLifecycle(Lifecycle.State.STARTED) {
                launch {
                    viewModel.uiState.collect { state ->
                        binding.progress.isVisible = state.isLoading
                        binding.tvTitle.text = state.article?.title.orEmpty()
                        binding.btnFavorite.isSelected = state.article?.isFavorite == true
                    }
                }
                launch {
                    // 一次性事件（Toast/导航）用单独的 Flow，避免重建时重复触发
                    viewModel.events.collect { event ->
                        when (event) {
                            is DetailEvent.ShowToast -> toast(event.message)
                            is DetailEvent.NavigateUp -> finish()
                        }
                    }
                }
            }
        }
    }

    private fun toast(msg: String) {
        android.widget.Toast.makeText(this, msg, android.widget.Toast.LENGTH_SHORT).show()
    }
}

2.4 ViewModel：生命周期感知的状态容器

// 文件路径：sample/feature/detail/src/main/java/com/techfeed/feature/detail/ui/DetailViewModel.kt
package com.techfeed.feature.detail.ui

import androidx.lifecycle.SavedStateHandle
import androidx.lifecycle.ViewModel
import androidx.lifecycle.viewModelScope
import com.techfeed.core.model.Article
import com.techfeed.feature.detail.domain.GetArticleUseCase
import com.techfeed.feature.detail.domain.ToggleFavoriteUseCase
import dagger.hilt.android.lifecycle.HiltViewModel
import kotlinx.coroutines.flow.MutableSharedFlow
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.SharedFlow
import kotlinx.coroutines.flow.StateFlow
import kotlinx.coroutines.flow.asSharedFlow
import kotlinx.coroutines.flow.asStateFlow
import kotlinx.coroutines.launch
import javax.inject.Inject

/** 详情页 UI 状态：一个不可变快照，UI 只负责渲染它 */
data class DetailUiState(
    val isLoading: Boolean = true,
    val article: Article? = null,
    val errorMessage: String? = null,
)

/** 一次性事件：不进入 UiState，避免旋转屏幕后重复弹 Toast */
sealed interface DetailEvent {
    data class ShowToast(val message: String) : DetailEvent
    data object NavigateUp : DetailEvent
}

@HiltViewModel
class DetailViewModel @Inject constructor(
    savedStateHandle: SavedStateHandle,
    private val getArticle: GetArticleUseCase,
    private val toggleFavorite: ToggleFavoriteUseCase,
) : ViewModel() {

    // 从导航参数中取文章 id（Navigation-Compose / Navigation 都会写进 SavedStateHandle）
    private val articleId: String = checkNotNull(savedStateHandle["articleId"])

    private val _uiState = MutableStateFlow(DetailUiState())
    val uiState: StateFlow<DetailUiState> = _uiState.asStateFlow()

    private val _events = MutableSharedFlow<DetailEvent>()
    val events: SharedFlow<DetailEvent> = _events.asSharedFlow()

    init {
        load()
    }

    private fun load() {
        viewModelScope.launch {
            _uiState.value = DetailUiState(isLoading = true)
            runCatching { getArticle(articleId) }
                .onSuccess { article ->
                    _uiState.value = DetailUiState(isLoading = false, article = article)
                }
                .onFailure { e ->
                    _uiState.value = DetailUiState(isLoading = false, errorMessage = e.message)
                }
        }
    }

    fun toggleFavorite() {
        viewModelScope.launch {
            runCatching { toggleFavorite(articleId) }
                .onFailure { _events.emit(DetailEvent.ShowToast("操作失败，请重试")) }
        }
    }
}

2.5 Service 与 BroadcastReceiver（最小可用示例）

// 文件路径：docs/samples/ch03/SyncService.kt
package com.techfeed.feature.push

import android.app.NotificationChannel
import android.app.NotificationManager
import android.app.Service
import android.content.Intent
import android.os.IBinder
import androidx.core.app.NotificationCompat

/**
 * 前台服务：必须在 5 秒内调用 startForeground，否则抛 ForegroundServiceStartNotAllowedException。
 * ⚠️ 现代 Android 中，能用 WorkManager 就不要用 Service（第 13 章）。
 */
class SyncService : Service() {

    override fun onCreate() {
        super.onCreate()
        createChannel()
        // 前台服务必须有可见通知，用户可随时在系统设置中停止
        startForeground(NOTIFICATION_ID, buildNotification())
    }

    override fun onStartCommand(intent: Intent?, flags: Int, startId: Int): Int {
        // START_STICKY：被杀后尝试重建（音乐类适用）；数据同步应该用 START_NOT_STICKY
        return START_NOT_STICKY
    }

    override fun onBind(intent: Intent?): IBinder? = null   // 非绑定服务返回 null

    private fun createChannel() {
        val channel = NotificationChannel(
            CHANNEL_ID, "数据同步", NotificationManager.IMPORTANCE_LOW,
        )
        getSystemService(NotificationManager::class.java).createNotificationChannel(channel)
    }

    private fun buildNotification() = NotificationCompat.Builder(this, CHANNEL_ID)
        .setContentTitle("正在同步数据")
        .setSmallIcon(android.R.drawable.stat_notify_sync)
        .build()

    companion object {
        private const val CHANNEL_ID = "sync"
        private const val NOTIFICATION_ID = 1001
    }
}

// 文件路径：docs/samples/ch03/NetworkReceiver.kt
package com.techfeed.feature.push

import android.content.BroadcastReceiver
import android.content.Context
import android.content.Intent
import android.content.IntentFilter
import android.net.ConnectivityManager
import androidx.lifecycle.DefaultLifecycleObserver
import androidx.lifecycle.LifecycleOwner

/**
 * 动态注册的广播：必须成对注册/注销，否则泄漏 Context。
 * 用 LifecycleObserver 绑定生命周期是最安全的写法。
 */
class NetworkReceiver(
    private val onAvailable: () -> Unit,
) : BroadcastReceiver() {

    override fun onReceive(context: Context, intent: Intent) {
        if (intent.action == ConnectivityManager.CONNECTIVITY_ACTION) {
            onAvailable()
        }
    }

    companion object {
        /** 返回一个随生命周期自动注册/注销的观察者 */
        fun observer(context: Context, onAvailable: () -> Unit) = object : DefaultLifecycleObserver {
            private val receiver = NetworkReceiver(onAvailable)
            override fun onStart(owner: LifecycleOwner) {
                context.registerReceiver(receiver, IntentFilter(ConnectivityManager.CONNECTIVITY_ACTION))
            }
            override fun onStop(owner: LifecycleOwner) {
                context.unregisterReceiver(receiver)
            }
        }
    }
}

[!NOTE] Android 7+ 已禁用大部分静态隐式广播（包括 CONNECTIVITY_ACTION），所以网络监听应改用 ConnectivityManager.NetworkCallback 或 WorkManager 的网络约束。上面示例仅用于演示注册/注销配对。

三、常见坑 ⚠️

Activity Result API（取代 onActivityResult）

// 文件路径：docs/samples/ch03/ActivityResult.kt
// 在 Activity/Fragment 的初始化阶段注册（不能在点击事件里注册）
private val requestPermissionLauncher = registerForActivityResult(
    ActivityResultContracts.RequestPermission()
) { granted: Boolean ->
    if (granted) startSync() else showRationale()
}

// 触发
fun askPermission() {
    requestPermissionLauncher.launch(Manifest.permission.POST_NOTIFICATIONS)
}

// 多个权限
private val requestMultiple = registerForActivityResult(
    ActivityResultContracts.RequestMultiplePermissions()
) { result: Map<String, Boolean> ->
    val allGranted = result.values.all { it }
}

四、调试技巧

# 1. 查看当前任务栈结构（排查"为什么回到这个页面"）
adb shell dumpsys activity activities | head -40

# 2. 模拟旋转屏幕（验证配置变更处理是否正确）
adb shell settings put system accelerometer_rotation 0
adb shell content insert --uri content://settings/system --bind name:s:user_rotation --bind value:i:1

# 3. 模拟进程被系统杀死后重建（验证 SavedStateHandle 是否生效）
adb shell am kill com.techfeed.app        # 杀死进程但保留任务栈
# 然后从最近任务列表切回 App

# 4. 不保留活动（开发者选项：Don't keep activities）—— 调试生命周期的最佳开关
adb shell settings put global always_finish_activities 1

# 5. 强制触发配置变更（密度变化）
adb shell wm density 420 && adb shell wm density reset

IDE 内：

• Logcat 过滤 ActivityThread / ActivityManager 可看到组件的创建销毁轨迹。
• 在 onCreate、onStart、onResume 等加临时日志，配合"不保留活动"开关，能快速暴露状态保存问题。
• App Inspection → Background Task Inspector 可查看 WorkManager 任务状态（第 13 章）。

五、最佳实践

1. 状态一律放 ViewModel：Activity/Fragment 只做"把状态渲染出来"和"把用户事件上报"。
2. 持久化状态用 SavedStateHandle：ViewModel 只跨配置变更，不跨进程死亡。
3. 一次性事件用 SharedFlow：Toast、导航、弹窗都不应进 UiState。
4. UI 层收集 Flow 用 repeatOnLifecycle(STARTED)：避免后台仍在收集浪费资源。
5. Fragment 的 binding 必须置空：onDestroyView 中 _binding = null，这是内存泄漏第一大来源。
6. 后台任务优先 WorkManager：Service 只用于前台服务（音乐、导航、长连接）。
7. 不需要被外部调起的组件全部 exported="false"：这是安全基线。
8. 避免 singleInstance：它会导致任务栈行为难以预测，99% 的场景用 singleTop/singleTask 就够了。
9. 用 Activity Result API：类型安全、可测试，且不再依赖 requestCode 常量。

// 旧写法（已废弃）：requestCode 魔法数字、类型不安全、在 Fragment 中容易丢回调
static final int REQ_LOGIN = 1001;
startActivityForResult(new Intent(this, LoginActivity.class), REQ_LOGIN);

@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
    if (requestCode == REQ_LOGIN && resultCode == RESULT_OK) { /* ... */ }
}

六、本章小结

1. 四大组件：Activity（UI 窗口）、Service（后台）、BroadcastReceiver（广播）、ContentProvider（跨应用数据）；全部需在 Manifest 声明。
2. 生命周期的核心是"什么时候该释放资源"：onStop 释放重量级资源，onDestroy 不保证被调用。
3. Fragment 有视图生命周期，onDestroyView 必须置空 binding；纯 Compose 新项目可以不用 Fragment。
4. 配置变更（ViewModel 解决）与进程重建（SavedStateHandle 解决）是两件事，别混为一谈。
5. 任务栈决定回退行为：standard / singleTop / singleTask 配合 Intent Flag 使用。

下一章：开始写界面。先看传统 View + XML 体系——它仍然是国内存量项目的主力。

七、动手练习

基础题

1. 新建两个 Activity：MainActivity 与 DetailActivity。从 Main 点击按钮跳到 Detail，并传一个 articleId 字符串，在 Detail 中打印出来。
2. 给 DetailActivity 加一个计数器，旋转屏幕后用 SavedStateHandle 保证计数不丢。
3. 用 adb shell am start -n 直接启动 DetailActivity，验证 Manifest 声明是否正确。

进阶题 4. 开启开发者选项"不保留活动"，反复在两个页面间跳转，观察是否存在崩溃或状态丢失，并修复。 5. 把详情页改成 "UiState + Event" 双通道：加载中/成功/失败放 UiState，Toast 放 SharedFlow。验证旋转屏幕时 Toast 不会重复弹出。

思考题 6. 为什么 Android 要设计"配置变更时销毁重建 Activity"这套机制，而不是自己适配屏幕方向？（提示：资源限定符与状态一致性） 7. ViewModel 在进程被杀后还能保留吗？如果不能，SavedStateHandle 又是怎么做到"跨越进程死亡"的？（提示：onSaveInstanceState 的 Bundle 序列化到系统进程） 8. 什么场景下你会坚持使用 Fragment 而不是纯 Compose？（至少说出两个真实理由）

📄 第 04 章 UI 基础：View 与 XML 布局 04-ui-view-xml-basics.md✓ 标记已学

阶段：入门 ｜ 预计阅读 60 min ｜ 代码落地模块：:core:designsystem、:feature:detail 前置：第 03 章 应用组件与生命周期 相关章节：第 05 章 Compose 基础 ｜ 第 07 章 资源与主题

学习目标

• [ ] 掌握 View 体系的坐标概念（px / dp / sp）与三种常用布局的适用场景。
• [ ] 能用 ConstraintLayout 搭建中等复杂度页面，且布局层级不超过 3 层。
• [ ] 熟练使用 ViewBinding 访问控件，不再写 findViewById。
• [ ] 理解 View 的绘制流程（measure → layout → draw）与事件分发（dispatchTouchEvent）的基本模型。
• [ ] 能写一个简单的自定义 View，并解释 onMeasure / onDraw 中各自要注意什么。

一、核心概念

1.1 View 体系全景

flowchart TB
    W["Window（PhoneWindow）"] --> D["DecorView<br/>最顶层容器"]
    D --> B["ContentView<br/>setContentView 的根布局"]
    B --> VG["ViewGroup（容器）"]
    VG --> V1["TextView"]
    VG --> V2["ImageView"]
    VG --> V3["ViewGroup...<br/>递归嵌套"]

三个必须分清的概念：

1.2 尺寸与字号单位

// dp 与 px 的转换（自定义 View / 绘制时需要）
// 注意：顶层扩展函数访问不到 View 的 resources，必须把 Context 传进来
fun Float.dpToPx(context: Context): Float = this * context.resources.displayMetrics.density
fun Float.pxToDp(context: Context): Float = this / context.resources.displayMetrics.density

1.3 三种布局的取舍

[!TIP] 布局选型的经验法则：能用一层 ConstraintLayout 解决的，不要用三层 LinearLayout 嵌套。 测量是递归的，嵌套每深一层，整棵树的测量成本就乘一次。

1.4 ConstraintLayout 心智模型

ConstraintLayout 的每个子 View 需要水平、垂直各一组约束，否则会"飘"到 (0,0)：

水平约束：start/end 相对父容器或兄弟控件的 start/end
垂直约束：top/bottom 相对父容器或兄弟控件的 top/bottom
bias：约束链的偏向（0~1），默认居中 0.5

常用工具一览：

二、示例代码

我们做一个 TechFeed 的文章详情页头部：封面图、标题、作者信息、收藏按钮。这个例子覆盖了最常见的排版需求。

View / XML 版

<!-- 文件路径：docs/samples/ch04/view_article_header.xml -->
<?xml version="1.0" encoding="utf-8"?>
<!-- 根布局用 merge 避免 ConstraintLayout 之外多一层无意义容器（配合 include 使用） -->
<merge xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    tools:parentTag="androidx.constraintlayout.widget.ConstraintLayout"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="wrap_content">

    <!-- 封面：16:9 比例 + 圆角（ShapeableImageView 来自 Material 组件库） -->
    <com.google.android.material.imageview.ShapeableImageView
        android:id="@+id/ivCover"
        android:layout_width="0dp"
        android:layout_height="0dp"
        android:scaleType="centerCrop"
        android:contentDescription="@string/article_cover"
        app:layout_constraintDimensionRatio="16:9"
        app:layout_constraintEnd_toEndOf="parent"
        app:layout_constraintStart_toStartOf="parent"
        app:layout_constraintTop_toTopOf="parent"
        app:shapeAppearanceOverlay="@style/RoundedCover" />

    <!-- 标题：在封面下方，宽度撑满 -->
    <TextView
        android:id="@+id/tvTitle"
        android:layout_width="0dp"
        android:layout_height="wrap_content"
        android:layout_marginTop="12dp"
        android:maxLines="3"
        android:ellipsize="end"
        android:textAppearance="?attr/textAppearanceHeadlineSmall"
        app:layout_constraintEnd_toStartOf="@id/btnFavorite"
        app:layout_constraintStart_toStartOf="parent"
        app:layout_constraintTop_toBottomOf="@id/ivCover"
        tools:text="深入理解 Compose 的重组机制" />

    <!-- 头像 -->
    <ImageView
        android:id="@+id/ivAvatar"
        android:layout_width="32dp"
        android:layout_height="32dp"
        android:layout_marginTop="12dp"
        android:contentDescription="@string/author_avatar"
        app:layout_constraintStart_toStartOf="parent"
        app:layout_constraintTop_toBottomOf="@id/tvTitle"
        tools:src="@drawable/ic_avatar_placeholder" />

    <!-- 作者名：垂直居中对齐头像（相对头像，而非相对标题，避免文字两行时错位） -->
    <TextView
        android:id="@+id/tvAuthor"
        android:layout_width="0dp"
        android:layout_height="wrap_content"
        android:layout_marginStart="8dp"
        android:textAppearance="?attr/textAppearanceBodyMedium"
        app:layout_constraintBottom_toBottomOf="@id/ivAvatar"
        app:layout_constraintEnd_toEndOf="parent"
        app:layout_constraintStart_toEndOf="@id/ivAvatar"
        app:layout_constraintTop_toTopOf="@id/ivAvatar"
        tools:text="张三 · 2026-09-29" />

    <!-- 收藏按钮：标题右侧，与标题顶部对齐 -->
    <ImageButton
        android:id="@+id/btnFavorite"
        android:layout_width="40dp"
        android:layout_height="40dp"
        android:background="?attr/selectableItemBackgroundBorderless"
        android:contentDescription="@string/toggle_favorite"
        android:src="@drawable/ic_favorite_border"
        app:layout_constraintEnd_toEndOf="parent"
        app:layout_constraintTop_toTopOf="@id/tvTitle" />

</merge>

// 文件路径：docs/samples/ch04/ArticleHeaderView.kt
package com.techfeed.feature.detail.ui

import android.content.Context
import android.util.AttributeSet
import android.widget.ImageView
import android.widget.TextView
import androidx.constraintlayout.widget.ConstraintLayout
import com.techfeed.core.model.Article
import com.techfeed.feature.detail.R
import com.techfeed.feature.detail.databinding.ViewArticleHeaderBinding

/**
 * 自定义组合控件：把"头部"这块 UI 收成一个组件，外界只暴露一个 bind()。
 * 好处：布局复用、调用方零感知内部实现、方便做单测与截图测试。
 */
class ArticleHeaderView @JvmOverloads constructor(
    context: Context,
    attrs: AttributeSet? = null,
) : ConstraintLayout(context, attrs) {

    // ViewBinding 在 inflate 时同步创建，这里绑定的是"本视图自身"，不再走 setContentView
    private val binding: ViewArticleHeaderBinding =
        ViewArticleHeaderBinding.bind(
            inflate(context, R.layout.view_article_header, this)
        )

    var onFavoriteClick: (() -> Unit)? = null

    init {
        binding.btnFavorite.setOnClickListener { onFavoriteClick?.invoke() }
    }

    /** 唯一的数据入口：UI 逻辑（格式化、图标切换）全部收敛在这里 */
    fun bind(article: Article, isFavorite: Boolean) {
        binding.tvTitle.text = article.title
        binding.tvAuthor.text = context.getString(
            R.string.author_and_date, article.author.name, article.publishedAt.toDisplayDate()
        )
        // isSelected 驱动 selector 状态图标，避免手动换 drawable
        binding.btnFavorite.isSelected = isFavorite
        // 图片加载用 Coil（第 09 章的网络体系配套）
        binding.ivCover.load(article.coverUrl) {
            crossfade(true)
            placeholder(R.drawable.ic_cover_placeholder)
        }
    }
}

需要的依赖（-module :feature:detail）：

// 文件路径：sample/feature/detail/build.gradle.kts（节选）
android {
    buildFeatures {
        viewBinding = true   // ViewBinding 开关：只生成绑定类，不做任何注入，无运行时开销
    }
}

dependencies {
    implementation(libs.bundles.compose)   // 双体系并存的设计系统模块两者都要
    implementation(libs.androidx.constraintlayout)
    implementation(libs.material)
    implementation(libs.coil.view)
}

Compose 版（对照）

// 文件路径：docs/samples/ch04/ArticleHeader.kt
package com.techfeed.feature.detail.ui

import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.aspectRatio
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.size
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.Favorite
import androidx.compose.material.icons.outlined.FavoriteBorder
import androidx.compose.material3.Icon
import androidx.compose.material3.IconButton
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.draw.clip
import androidx.compose.ui.layout.ContentScale
import androidx.compose.ui.unit.dp
import coil3.compose.AsyncImage
import com.techfeed.core.designsystem.theme.rounded16
import com.techfeed.core.model.Article
import com.techfeed.core.common.toDisplayDate

/** 与 XML 版一一对应的 Compose 实现：无状态组件，数据从参数进来，事件从回调出去 */
@Composable
fun ArticleHeader(
    article: Article,
    isFavorite: Boolean,
    onFavoriteClick: () -> Unit,
    modifier: Modifier = Modifier,      // modifier 永远是第一个带默认值的参数
) {
    Column(modifier = modifier.fillMaxWidth()) {
        AsyncImage(
            model = article.coverUrl,
            contentDescription = null,   // 纯装饰性图片传 null，避免朗读软件重复播报
            contentScale = ContentScale.Crop,
            modifier = Modifier
                .fillMaxWidth()
                .aspectRatio(16f / 9f)   // 对应 XML 的 dimensionRatio="16:9"
                .clip(MaterialTheme.shapes.rounded16),
        )
        Row(verticalAlignment = Alignment.CenterVertically) {
            Text(
                text = article.title,
                style = MaterialTheme.typography.headlineSmall,
                maxLines = 3,
                modifier = Modifier.weight(1f),   // 对应 XML 的 0dp + 约束
            )
            IconButton(onClick = onFavoriteClick) {
                Icon(
                    // 用状态切换图标，替代 XML 的 isSelected + selector
                    imageVector = if (isFavorite) Icons.Filled.Favorite else Icons.Outlined.FavoriteBorder,
                    contentDescription = null,
                    tint = if (isFavorite) MaterialTheme.colorScheme.primary
                           else MaterialTheme.colorScheme.onSurfaceVariant,
                )
            }
        }
        Row(verticalAlignment = Alignment.CenterVertically) {
            AsyncImage(
                model = article.author.avatarUrl,
                contentDescription = null,
                modifier = Modifier.size(32.dp),
            )
            Text(
                text = "${article.author.name} · ${article.publishedAt.toDisplayDate()}",
                style = MaterialTheme.typography.bodyMedium,
                modifier = Modifier.padding(start = 8.dp),
            )
        }
    }
}

自定义 View 入门：绘制一个"阅读进度条"

// 文件路径：docs/samples/ch04/ReadingProgressView.kt
package com.techfeed.core.designsystem.view

import android.content.Context
import android.graphics.Canvas
import android.graphics.Paint
import android.util.AttributeSet
import android.view.View
import com.techfeed.core.designsystem.R

/**
 * 阅读进度条：演示 onMeasure 与 onDraw 的最小闭环。
 * 关键点：
 *  1. onMeasure 必须调用 setMeasuredDimension，否则崩溃；
 *  2. 绘制用的对象（Paint）在构造时创建并复用，onDraw 里禁止 new 对象（每帧调用，会引发 GC 抖动）；
 *  3. 属性变化后调用 invalidate() 触发重绘。
 */
class ReadingProgressView @JvmOverloads constructor(
    context: Context,
    attrs: AttributeSet? = null,
) : View(context, attrs) {

    private var progress = 0f

    private val trackPaint = Paint(Paint.ANTI_ALIAS_FLAG).apply {
        color = context.getColor(R.color.progress_track)
        style = Paint.Style.FILL
    }
    private val fillPaint = Paint(Paint.ANTI_ALIAS_FLAG).apply {
        color = context.getColor(R.color.progress_fill)
        style = Paint.Style.FILL
    }

    fun setProgress(value: Float) {
        progress = value.coerceIn(0f, 1f)
        invalidate()   // 请求重绘（主线程）；子线程用 postInvalidate()
    }

    override fun onMeasure(widthMeasureSpec: Int, heightMeasureSpec: Int) {
        // 默认高度 4dp：wrap_content 时给一个合理值，而不是 0
        val defaultHeight = 4f.dpToPx(context).toInt()
        val height = resolveSize(defaultHeight, heightMeasureSpec)
        setMeasuredDimension(getDefaultSize(suggestedMinimumWidth, widthMeasureSpec), height)
    }

    override fun onDraw(canvas: Canvas) {
        super.onDraw(canvas)
        val width = width.toFloat()
        // 背景轨道
        canvas.drawRect(0f, 0f, width, height.toFloat(), trackPaint)
        // 前景进度
        canvas.drawRect(0f, 0f, width * progress, height.toFloat(), fillPaint)
    }
}

三、常见坑 ⚠️

// 旧写法 1：findViewById 需要强转（旧版本），每个控件一行，多控件页面极其冗长
val tvTitle = findViewById<TextView>(R.id.tv_title)
val btnFavorite = findViewById<ImageButton>(R.id.btn_favorite)

// 旧写法 2：Kotlin synthetics（已废弃）：视图 id 直接当属性用，但存在空指针与跨布局误用风险
import kotlinx.android.synthetic.main.view_article_header.*
tvTitle.text = article.title

// 旧写法 3：ButterKnife（停止维护）
@BindView(R.id.tv_title) lateinit var tvTitle: TextView

四、调试技巧

1. Layout Inspector（Tools → Layout Inspector）：
   • 看真实运行的视图树、每个 View 的边界与属性（含 Compose 的重组次数）。
   • "Overlay" 模式可以在真机上叠加显示边界，排查"控件为什么被遮挡"。
2. 显示布局边界（开发者选项）：

   adb shell setprop debug.layout true
   

   直接在设备上看到每个 View 的裁剪边界与过度绘制染色。
3. 过度绘制检测：开发者选项 → 调试 GPU 过度绘制。蓝色以上区域越多越要警惕（第 17 章）。
4. 约束调试：ConstraintLayout 的警告会打印在 Logcat（tag ConstraintLayout），如 "do not constrain child vertically"。
5. 只重绘验证：怀疑某个 View 绘制有问题时，用 View.setLayerType(LAYER_TYPE_HARDWARE, null) 隔离它，观察掉帧是否消失。
6. 自动化布局检查：./gradlew :feature:detail:lintDebug，Lint 会报告 MissingConstraints、UselessParent 等问题（第 22 章接入 CI）。

五、最佳实践

1. 层级越少越好：目标 3 层以内；能用 ConstraintLayout 一层解决的，不用嵌套。
2. 一律 ViewBinding：findViewById、synthetics、ButterKnife 都是历史。
3. 组合控件收敛 UI 逻辑：像 ArticleHeaderView 那样，外界只调用 bind(model)，页面代码更薄。
4. tools: 命名空间做预览数据：tools:text 不影响运行时，却让预览接近真实效果。
5. 颜色、字号、间距全部走主题资源：禁止硬编码色值与字号（第 07 章主题体系）。
6. 无障碍不是可选项：可点击控件用 ImageButton/Button 而不是裸 View；图片给 contentDescription（装饰图给 null）。
7. 自定义 View 的 onDraw 里零分配：Paint、Rect 在构造时创建复用。
8. 新页面直接用 Compose：View/XML 用于维护存量页面与互操作场景（第 16 章）。

六、本章小结

1. View 体系的三层结构：Window → DecorView → 内容布局；布局 XML 是运行时解析的。
2. 单位约定：dp 管尺寸、sp 管文字；wrap_content / match_parent / 0dp+约束 各司其职。
3. 布局选型：单方向用 LinearLayout、叠放用 FrameLayout、复杂关系用 ConstraintLayout，RelativeLayout 不再新用。
4. ViewBinding 是访问控件的唯一现代方式；Fragment 中记得在 onDestroyView 置空。
5. 自定义 View 的最小闭环是 onMeasure（必须 setMeasuredDimension）+ onDraw（零对象分配）。

下一章：走进 Compose——同样的详情页头部，用声明式 UI 写出来是什么样，状态驱动和命令式刷新的差异到底在哪。

七、动手练习

基础题

1. 用 ConstraintLayout 实现"点赞数 + 评论数 + 分享按钮"的三栏底部操作条：左中右三组，间距均分，高度 48dp。
2. 把第 00 章的计数器页面改成 ViewBinding 版本，并用 tools:text 让预览显示非零计数。
3. 写一个自定义 View TagView：绘制圆角矩形背景 + 居中文字，支持 wrap_content（提示：测量文字用 Paint.measureText）。

进阶题 4. 实现 ArticleHeaderView 的深色模式适配：颜色改用主题属性，验证切换深色模式后无需改代码（结合第 07 章）。 5. 把"标题 + 作者行"抽成一个可复用控件，同时提供 XML 与 Compose 两个实现，保证视觉一致（字号/间距用同一套设计令牌）。

思考题 6. 为什么说"XML 布局是运行时解析的"这件事，从根上限定了 View 体系的能力上限？（提示：类型安全、编译期检查、条件逻辑表达力） 7. ConstraintLayout 的 Barrier 和 Guideline 分别解决什么问题？如果不用它们，你需要付出什么代价？ 8. 事件分发中"父容器拦截、子 View 消费"各发生在哪个回调？如果要实现"侧滑返回与横滑列表共存"，你会怎么设计？

📄 第 05 章 UI 基础：Jetpack Compose 05-ui-compose-basics.md✓ 标记已学

阶段：入门 ｜ 预计阅读 65 min ｜ 代码落地模块：:core:designsystem、:feature:feed 前置：第 04 章 View 与 XML ｜ 第 01 章 Kotlin 速成 相关章节：第 06 章 列表与导航 ｜ 第 17 章 性能优化

学习目标

• [ ] 理解"声明式 UI"与"命令式 UI"的本质差异，说清**重组（Recomposition）**是怎么发生的。
• [ ] 熟练使用 remember / rememberSaveable / mutableStateOf 管理状态。
• [ ] 掌握**状态提升（State Hoisting）**模式，能写出可复用、可测试的无状态组件。
• [ ] 能解释 LaunchedEffect / DisposableEffect / rememberCoroutineScope 各自的使用时机。
• [ ] 会用 Material3 主题令牌（color/typography/shape）组织一套设计系统。

一、核心概念

1.1 命令式 vs 声明式

flowchart LR
    subgraph Imperative["命令式（View 体系）"]
        A1["数据变化"] --> A2["手动找到控件"]
        A2 --> A3["手动调用 setText / setVisibility"]
        A3 --> A4["UI 更新"]
    end
    subgraph Declarative["声明式（Compose）"]
        B1["状态变化"] --> B2["自动触发重组"]
        B2 --> B3["重新执行 Composable 函数"]
        B3 --> B4["生成新 UI 树并做最小差异更新"]
    end

心智模型一句话：UI = f(state)。界面只是状态的函数，状态变了，界面自然重算。

1.2 重组的三个铁律

1. 重组是"重新执行函数"：Composable 函数可能被频繁调用，因此函数体内不要有副作用（写文件、改全局变量、发请求）。
2. 只有读取了变化状态的代码才会重新执行：这就是"跳过（skipping）"，是 Compose 性能的基石。
3. 重组可能随时中断和重放：不要依赖执行次数（比如在函数体里做 count++）。

// ⚠️ 反例：副作用直接写在组合期
@Composable
fun BadExample(articleId: String) {
    // 每次重组都会发一次请求！旋转屏幕、键盘弹出、任何状态变化都会触发
    repository.loadArticle(articleId)   // ❌
}

// ✅ 正例：副效应放入 LaunchedEffect，以 articleId 为 key
@Composable
fun GoodExample(articleId: String) {
    LaunchedEffect(articleId) {
        repository.loadArticle(articleId)
    }
}

1.3 状态 API 速查

1.4 状态提升（State Hoisting）

无状态组件的模式固定为三段式：

@Composable
fun XxxCard(
    value: T,                 // ① 状态：由调用方传入
    onValueChange: (T) -> Unit,  // ② 事件：向上报告
    modifier: Modifier = Modifier,  // ③ modifier 放最后（带默认值）
)

好处：组件可预览、可测试、可在多处复用；状态集中在拥有它的层级（通常是 ViewModel 或父组件）。

二、示例代码

2.1 状态与事件：搜索框

// 文件路径：sample/feature/feed/src/main/java/com/techfeed/feature/feed/ui/SearchBar.kt
package com.techfeed.feature.feed.ui

import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.text.KeyboardActions
import androidx.compose.foundation.text.KeyboardOptions
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.Close
import androidx.compose.material.icons.filled.Search
import androidx.compose.material3.Icon
import androidx.compose.material3.IconButton
import androidx.compose.material3.OutlinedTextField
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.ui.Modifier
import androidx.compose.ui.text.input.ImeAction

/**
 * 无状态搜索框：状态由调用方持有（提升），事件向上回调。
 * 这样它可以在预览中直接展示任意内容，也可以被任意页面复用。
 */
@Composable
fun FeedSearchBar(
    query: String,                       // ① 状态：提升到调用方
    onQueryChange: (String) -> Unit,     // ② 事件：上报变化
    onSearch: () -> Unit,                // ② 事件：上报搜索动作
    modifier: Modifier = Modifier,
) {
    OutlinedTextField(
        value = query,
        onValueChange = onQueryChange,
        modifier = modifier.fillMaxWidth(),
        placeholder = { Text("搜索文章…") },
        leadingIcon = { Icon(Icons.Filled.Search, contentDescription = null) },
        trailingIcon = {
            if (query.isNotEmpty()) {
                IconButton(onClick = { onQueryChange("") }) {
                    Icon(Icons.Filled.Close, contentDescription = "清空")
                }
            }
        },
        singleLine = true,
        keyboardOptions = KeyboardOptions(imeAction = ImeAction.Search),
        keyboardActions = KeyboardActions(onSearch = { onSearch() }),
    )
}

// 有状态容器：在 ViewModel 侧持有真实状态（对应第 03 章的 UiState 模式）
// 文件路径：sample/feature/feed/src/main/java/com/techfeed/feature/feed/ui/FeedScreen.kt（节选）
@Composable
fun FeedScreen(viewModel: FeedViewModel = hiltViewModel()) {
    // collectAsStateWithLifecycle：页面进入后台自动停止收集，避免浪费与泄漏
    val state by viewModel.uiState.collectAsStateWithLifecycle()

    Column {
        FeedSearchBar(
            query = state.query,
            onQueryChange = viewModel::onQueryChange,   // 方法引用，避免 lambda 新建
            onSearch = viewModel::search,
        )
        // ……列表部分见第 06 章
    }
}

2.2 remember / rememberSaveable 的边界

// 文件路径：docs/samples/ch05/ReadingStateDemo.kt
package com.techfeed.feature.feed.ui

import androidx.compose.foundation.layout.Column
import androidx.compose.material3.Button
import androidx.compose.material3.OutlinedTextField
import androidx.compose.material3.Slider
import androidx.compose.material3.Text
import androidx.compose.runtime.*

// 演示用简单类型（真实业务里是 core/model 的领域模型）
data class ReadingProgress(val articleId: String, val percent: Int)

@Composable
fun ReadingStateDemo() {
    Column {
        // 场景 A：临时 UI 状态。旋转屏幕会丢（remember 不落盘）——但它丢了也无妨
        var sliderExpanded by remember { mutableStateOf(false) }

        // 场景 B：用户输入。必须 rememberSaveable，旋转/进程重建都不能丢
        var keyword by rememberSaveable { mutableStateOf("") }
        OutlinedTextField(value = keyword, onValueChange = { keyword = it })

        // 场景 C：派生状态。字数统计随 keyword 自动重算，不需要手动刷新
        val charCount by remember(keyword) { derivedStateOf { keyword.length } }
        Text("已输入 $charCount 字")

        // 场景 D：自定义 Saver。ReadingProgress 是自定义类型，不在自动保存白名单里，
        // 用 listSaver 拆成基础类型列表：save 负责"拆"、restore 负责"组"
        var progress by rememberSaveable(stateSaver = listSaver(
            save = { listOf(it.articleId, it.percent) },
            restore = { ReadingProgress(it[0] as String, it[1] as Int) },
        )) { mutableStateOf(ReadingProgress("article-1", 0)) }

        Button(onClick = { sliderExpanded = !sliderExpanded }) { Text("展开") }
    }
}

[!WARNING] remember 的值在进程被杀后必然丢失。任何"用户会心疼的数据"（输入、选择、滚动位置）都要用 rememberSaveable 或上移到 ViewModel + SavedStateHandle（第 03 章）。

2.3 Material3 主题：设计令牌

// 文件路径：docs/samples/ch05/Color.kt
package com.techfeed.core.designsystem.theme

import androidx.compose.ui.graphics.Color

// 浅色配色（示例值，实际项目由设计师给色板）
val md_light_primary = Color(0xFF1B6EF3)
val md_light_onPrimary = Color(0xFFFFFFFF)
val md_light_surface = Color(0xFFFDFBFF)
val md_light_onSurface = Color(0xFF1A1C1E)

// 深色配色
val md_dark_primary = Color(0xFFA6C8FF)
val md_dark_onPrimary = Color(0xFF00315F)
val md_dark_surface = Color(0xFF111318)
val md_dark_onSurface = Color(0xFFE2E2E9)

// 文件路径：sample/core/designsystem/src/main/java/com/techfeed/core/designsystem/theme/Theme.kt
package com.techfeed.core.designsystem.theme

import androidx.compose.foundation.isSystemInDarkTheme
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.darkColorScheme
import androidx.compose.material3.lightColorScheme
import androidx.compose.runtime.Composable

private val LightColors = lightColorScheme(
    primary = md_light_primary,
    onPrimary = md_light_onPrimary,
    surface = md_light_surface,
    onSurface = md_light_onSurface,
)

private val DarkColors = darkColorScheme(
    primary = md_dark_primary,
    onPrimary = md_dark_onPrimary,
    surface = md_dark_surface,
    onSurface = md_dark_onSurface,
)

@Composable
fun TechFeedTheme(
    darkTheme: Boolean = isSystemInDarkTheme(),   // 默认跟随系统
    content: @Composable () -> Unit,
) {
    MaterialTheme(
        colorScheme = if (darkTheme) DarkColors else LightColors,
        typography = TechFeedTypography,
        shapes = TechFeedShapes,
        content = content,
    )
}

使用时永远通过令牌取值，而不是硬编码颜色：

Text(
    text = title,
    // ✅ 令牌：深浅色自动适配
    color = MaterialTheme.colorScheme.onSurfaceVariant,
    style = MaterialTheme.typography.bodyMedium,
)

2.4 副效应：什么时候用哪个

// 文件路径：docs/samples/ch05/SideEffects.kt
package com.techfeed.sample.sideeffects

import androidx.compose.runtime.*

/** 1. LaunchedEffect：进入组合启动协程；key 变化时取消旧协程、重启新协程 */
@Composable
fun ArticlePage(articleId: String, viewModel: ArticleViewModel) {
    LaunchedEffect(articleId) {           // articleId 变了 → 重新加载
        viewModel.load(articleId)
    }
}

/** 2. DisposableEffect：需要手动清理的资源（监听器、广播、回调） */
@Composable
fun ConnectivityBanner(connectivity: ConnectivityObserver) {
    val status by connectivity.status.collectAsStateWithLifecycle()

    DisposableEffect(connectivity) {
        // 开始：注册
        val handle = connectivity.register()
        onDispose {
            // 结束：注销 —— 与注册严格配对，漏了就是泄漏
            handle.unregister()
        }
    }
}

/** 3. rememberCoroutineScope：在事件回调中启动协程（不能在组合期直接 launch） */
@Composable
fun ScrollToTopButton(listState: LazyListState) {
    val scope = rememberCoroutineScope()
    Button(onClick = {
        scope.launch { listState.animateScrollToItem(0) }   // 事件回调里启动
    }) { Text("回到顶部") }
}

/** 4. SideEffect：每次成功重组后执行（把 Compose 状态同步给非 Compose 世界） */
@Composable
fun AnalyticsScreen(screenName: String) {
    SideEffect {
        Analytics.trackScreen(screenName)   // 埋点 SDK 是普通 Java 对象，不是 Compose 状态
    }
}

三、常见坑 ⚠️

四、调试技巧

1. 重组计数：Layout Inspector → Composition Counts，直接看每个组件重组了多少次（第 17 章性能优化入口）。
2. 双击修饰符面板：在 @Preview 中，Layout Inspector 可以叠加显示 Compose 语义树边界。
3. 语义树打印：UI 测试排障利器——

   composeTestRule.onRoot().printToLog("semantics")   // 在 Logcat 打印语义树
   

4. debugInspectorInfo：给自定义 Modifier 写元数据，Layout Inspector 中能看到每个 modifier 的参数。
5. 快照观察：Snapshot.withMutableSnapshot / snapshotFlow 可以把"状态变化"转成 Flow，用于打印状态轨迹：

   snapshotFlow { state.articles.size }
       .distinctUntilChanged()
       .collect { Log.d("Feed", "列表长度变化: $it") }
   

6. 预览参数化：@Preview(name = "深色", uiMode = Configuration.UI_MODE_NIGHT_YES)、@Preview(fontScale = 1.3f)，一次写多个预览覆盖关键形态。

五、最佳实践

1. 组件分层：无状态叶子组件（可预览、可测试）→ 有状态容器（连 ViewModel）→ Screen（组装）。
2. 状态提升三段式：value: T, onValueChange: (T) -> Unit, modifier: Modifier = Modifier。
3. 状态下沉与上提的判断标准：谁能"读懂"这个状态就放在谁那里；多个组件共享就上提到最近公共父级或 ViewModel。
4. 列表项只接收需要的数据：不要把整个 UiState 传给 item，否则任何字段变化都会让整列重组。
5. 副效应 API 对号入座：协程用 LaunchedEffect、需要清理用 DisposableEffect、事件回调里用 rememberCoroutineScope、同步到非 Compose 世界用 SideEffect。
6. 主题令牌优先：颜色/字体/形状一律从 MaterialTheme 取，杜绝硬编码。
7. key() 明确标识列表项身份：配合 LazyColumn（第 06 章），让重组最小化。
8. @Stable / @Immutable 慎用：先让数据类天然稳定（全 val + 基本类型/String），标注是兜底不是常规手段（第 17 章）。

<!-- View 体系需要：布局 + 代码双向同步 -->
<com.google.android.material.textfield.TextInputLayout ...>
    <com.google.android.material.textfield.TextInputEditText
        android:id="@+id/etSearch" ... />
</com.google.android.material.textfield.TextInputLayout>

// 命令式：状态与控件是两份事实，需要手动保持同步
binding.etSearch.doOnTextChanged { text, _, _, _ ->
    viewModel.onQueryChange(text.toString())
}
viewModel.query.observe(this) { query ->      // 状态回来还要防抖、防重复 set
    if (binding.etSearch.text.toString() != query) {
        binding.etSearch.setText(query)
    }
}

六、本章小结

1. UI = f(state)：状态是唯一事实源，Compose 通过智能重组自动把状态映射为界面。
2. 重组铁律：函数体无副作用；只有读取变化状态的代码会重跑；执行次数不可依赖。
3. 状态 API：mutableStateOf + remember(Saveable) 管局部状态，ViewModel + StateFlow 管业务状态，collectAsStateWithLifecycle 桥接。
4. 状态提升三段式让组件可预览、可测试、可复用。
5. 主题令牌（color/typography/shape）是设计系统的最小内核，深浅色与无障碍都从它受益。

下一章：把状态驱动应用到最重的 UI 场景——列表与页面导航，对比 RecyclerView 与 LazyColumn、Navigation 与 Navigation-Compose 两套方案。

七、动手练习

基础题

1. 实现一个"标签选择器"：横排若干标签，点击选中（多选），选中态用 MaterialTheme.colorScheme.primary 高亮；要求组件无状态、可预览。
2. 写一个带 rememberSaveable 的倒计时组件：旋转屏幕后剩余秒数不重置。（提示：保存"结束时间戳"而不是"剩余秒数"更稳。）
3. 用 derivedStateOf 实现"输入长度超过 140 字时变红提示"。

进阶题 4. 把第 04 章的 ArticleHeaderView（XML 版）与本章的 ArticleHeader（Compose 版）放在一起，逐项列出"手动同步点"的消失（至少列 5 处）。 5. 实现"折叠式详情页"：点击标题展开/收起正文，展开动画用 animateContentSize()；思考为什么不用 if/else 硬切。 6. 给 ArticleHeader 写 3 个 @Preview：浅色、深色、字体放大 1.3 倍。

思考题 7. remember { } 与 rememberSaveable { } 的实现差异是什么？为什么后者能跨进程死亡？（提示：Bundle 序列化进系统进程） 8. 为什么 Compose 要求"组合期无副作用"？如果不遵守，会出现哪三类具体 bug？ 9. CompositionLocal 与"参数逐层传递"各适合什么场景？滥用 CompositionLocal 会让什么变差？（提示：可读性、可测试性）

📄 第 06 章 列表与导航 06-lists-and-navigation.md✓ 标记已学

阶段：入门 ｜ 预计阅读 65 min ｜ 代码落地模块：:feature:feed、:app 前置：第 04 章 View 与 XML ｜ 第 05 章 Compose 基础 相关章节：第 09 章 网络请求 ｜ 第 14 章 分层架构

学习目标

• [ ] 理解 RecyclerView 的回收复用机制，能写出带 DiffUtil 的 ListAdapter。
• [ ] 会用 LazyColumn（key、contentType、分页），并解释它与 RecyclerView 的异同。
• [ ] 掌握 Navigation 组件的核心概念（NavHost、NavController、back stack entry、参数）。
• [ ] 会用 Navigation-Compose 搭建单 Activity 导航图，安全地传参与返回。
• [ ] 知道列表性能的三板斧：稳定 key、缩小重组范围、避免过度测量。

一、核心概念

1.1 列表的本质：回收复用

屏幕只能显示十几个列表项，但数据可能有上万条。两套体系的核心思想一致——只创建"屏幕上正在显示的"那些视图对象：

flowchart LR
    subgraph RV["RecyclerView"]
        A1["onCreateViewHolder<br/>创建（很少发生）"] --> A2["onBindViewHolder<br/>绑定数据（滚动时反复）"]
        A2 --> A3["滚出屏幕"] --> A4["回收池 RecycledViewPool"]
        A4 --> A2
    end
    subgraph LC["LazyColumn"]
        B1["只组合可见项"] --> B2["滚出屏幕即销毁组合"]
        B2 --> B3["滚回屏幕重新组合<br/>（状态由 rememberSaveable 保存）"]
    end

1.2 为什么 key 如此重要

列表项没有稳定 id 时，框架只能按位置匹配新旧数据。典型事故：

• 列表头部插入一条新数据，所有 item 的状态（勾选、动画、输入框内容）串位。
• 删除中间一项后，动画错乱、图片闪烁。

稳定 key = 数据的身份（id），不是位置。 这是列表正确性的第一原则，两套体系通用。

1.3 导航的核心模型

flowchart LR
    NC["NavController<br/>导航的指挥者"] --> NH["NavHost<br/>承载目的地的容器"]
    NH --> D1["Destination A<br/>（Compose 路由 / Fragment）"]
    NH --> D2["Destination B"]
    NH --> D3["Destination C"]
    D1 -->|"navigate()"| D2 -->|"navigate()"| D3
    D3 -->|"popBackStack()"| D2 -->|"popBackStack()"| D1

• 单 Activity 架构下，NavHost 是唯一的"页面容器"，目的地（Destination）之间的切换不产生新的 Activity。
• 返回栈（back stack）由 NavController 管理：navigate 压栈，系统返回键 / popBackStack 出栈。
• 目的地之间不共享 ViewModel；跨页面共享数据用 Activity 级 ViewModel 或数据层（第 14 章）。

二、示例代码

2.1 RecyclerView 版信息流列表

// 文件路径：docs/samples/ch06/ArticleAdapter.kt
package com.techfeed.feature.feed.ui.view

import android.view.LayoutInflater
import android.view.ViewGroup
import androidx.recyclerview.widget.DiffUtil
import androidx.recyclerview.widget.ListAdapter
import androidx.recyclerview.widget.RecyclerView
import coil.load
import com.techfeed.core.model.Article
import com.techfeed.feature.feed.databinding.ItemArticleBinding

/**
 * ListAdapter：内置 DiffUtil 的异步差量更新。
 * 调用方只需 submitList(newList)，框架自动算出最小增删改并带动画。
 */
class ArticleAdapter(
    private val onClick: (Article) -> Unit,
) : ListAdapter<Article, ArticleAdapter.ArticleViewHolder>(DIFF) {

    override fun onCreateViewHolder(parent: ViewGroup, viewType: Int): ArticleViewHolder {
        val binding = ItemArticleBinding.inflate(
            LayoutInflater.from(parent.context), parent, false
        )
        return ArticleViewHolder(binding, onClick)
    }

    override fun onBindViewHolder(holder: ArticleViewHolder, position: Int) {
        holder.bind(getItem(position))   // getItem 内部处理了 position 与数据的映射
    }

    class ArticleViewHolder(
        private val binding: ItemArticleBinding,
        onClick: (Article) -> Unit,
    ) : RecyclerView.ViewHolder(binding.root) {

        private var current: Article? = null

        init {
            // 点击监听只在创建时设置一次，绑定当前 item 引用 —— 避免每次 bind 都 new 监听器
            binding.root.setOnClickListener { current?.let(onClick) }
        }

        fun bind(article: Article) {
            current = article
            binding.tvTitle.text = article.title
            binding.tvMeta.text = "${article.author.name} · ${article.readMinutes} 分钟"
            binding.ivCover.load(article.coverUrl) {
                crossfade(true)
                placeholder(com.techfeed.core.designsystem.R.drawable.ic_cover_placeholder)
            }
        }
    }

    companion object {
        /**
         * DiffUtil：areItemsTheSame 比"身份"（id），areContentsTheSame 比"内容"。
         * ⚠️ 身份比较绝不能用位置或 equals 全量比对（贵且会误判）。
         */
        private val DIFF = object : DiffUtil.ItemCallback<Article>() {
            override fun areItemsTheSame(oldItem: Article, newItem: Article) =
                oldItem.id == newItem.id

            override fun areContentsTheSame(oldItem: Article, newItem: Article) =
                oldItem == newItem   // data class 自动实现 equals，直接比
        }
    }
}

2.2 Compose 版信息流列表

// 文件路径：docs/samples/ch06/FeedList.kt
package com.techfeed.feature.feed.ui

import androidx.compose.foundation.clickable
import androidx.compose.foundation.layout.*
import androidx.compose.foundation.lazy.LazyColumn
import androidx.compose.foundation.lazy.items
import androidx.compose.material3.*
import androidx.compose.runtime.Composable
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.draw.clip
import androidx.compose.ui.layout.ContentScale
import androidx.compose.ui.unit.dp
import coil3.compose.AsyncImage
import com.techfeed.core.model.Article

@Composable
fun FeedList(
    articles: List<Article>,
    onArticleClick: (String) -> Unit,
    modifier: Modifier = Modifier,
    contentPadding: PaddingValues = PaddingValues(16.dp),
) {
    LazyColumn(
        modifier = modifier.fillMaxSize(),
        contentPadding = contentPadding,   // 用 contentPadding 而非外层 padding：滚动时内容能画到边距外
        verticalArrangement = Arrangement.spacedBy(12.dp),
    ) {
        items(
            items = articles,
            key = { it.id },           // ⭐ 稳定 key：身份是 id，不是位置
            contentType = { "article" },  // 提示同类型项可复用组合
        ) { article ->
            // ⭐ 只把 item 需要的数据传进来：article 变化只重组这一个 item
            ArticleListItem(
                article = article,
                onClick = { onArticleClick(article.id) },
            )
        }
    }
}

@Composable
private fun ArticleListItem(article: Article, onClick: () -> Unit) {
    Card(onClick = onClick) {
        Row(modifier = Modifier.padding(12.dp), verticalAlignment = Alignment.CenterVertically) {
            AsyncImage(
                model = article.coverUrl,
                contentDescription = null,
                contentScale = ContentScale.Crop,
                modifier = Modifier
                    .size(72.dp)
                    .clip(MaterialTheme.shapes.small),
            )
            Column(modifier = Modifier.padding(start = 12.dp)) {
                Text(
                    text = article.title,
                    style = MaterialTheme.typography.titleMedium,
                    maxLines = 2,
                )
                Text(
                    text = "${article.author.name} · ${article.readMinutes} 分钟",
                    style = MaterialTheme.typography.bodySmall,
                    color = MaterialTheme.colorScheme.onSurfaceVariant,
                )
            }
        }
    }
}

2.3 Navigation-Compose：单 Activity 导航图

// 文件路径：sample/app/src/main/java/com/techfeed/app/navigation/TechFeedNavHost.kt
package com.techfeed.app.navigation

import androidx.compose.runtime.Composable
import androidx.compose.ui.Modifier
import androidx.navigation.NavHostController
import androidx.navigation.compose.NavHost
import androidx.navigation.compose.composable
import androidx.navigation.navArgument
import androidx.navigation.NavType
import androidx.navigation.toRoute
import com.techfeed.feature.detail.ui.DetailScreen
import com.techfeed.feature.feed.ui.FeedScreen
import kotlinx.serialization.Serializable

/**
 * 路由用密封类/序列化对象建模（类型安全导航）：
 * 好处是参数名、类型都在编译期检查，字符串拼错直接编译失败。
 */
@Serializable
data object FeedRoute            // 列表页：无参数

@Serializable
data class DetailRoute(val articleId: String)   // 详情页：携带文章 id

@Composable
fun TechFeedNavHost(
    navController: NavHostController,
    modifier: Modifier = Modifier,
) {
    NavHost(
        navController = navController,
        startDestination = FeedRoute,   // 起始目的地
        modifier = modifier,
    ) {
        composable<FeedRoute> {
            FeedScreen(
                onArticleClick = { articleId ->
                    // 单一入口跳详情：所有页面跳转都经 NavHost，屏幕组件保持无导航依赖
                    navController.navigate(DetailRoute(articleId))
                },
            )
        }
        composable<DetailRoute> { backStackEntry ->
            // 从返回栈条目中取出路由对象，参数类型安全
            val route = backStackEntry.toRoute<DetailRoute>()
            DetailScreen(
                articleId = route.articleId,
                onBack = navController::popBackStack,
            )
        }
    }
}

// 文件路径：sample/app/src/main/java/com/techfeed/app/MainActivity.kt（节选）
@AndroidEntryPoint
class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        enableEdgeToEdge()
        setContent {
            TechFeedTheme {
                val navController = rememberNavController()
                Scaffold { innerPadding ->
                    TechFeedNavHost(
                        navController = navController,
                        modifier = Modifier.padding(innerPadding),
                    )
                }
            }
        }
    }
}

2.4 Navigation（View 体系）对照

<!-- 文件路径：docs/samples/ch06/nav_graph.xml -->
<?xml version="1.0" encoding="utf-8"?>
<navigation xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    android:id="@+id/nav_graph"
    app:startDestination="@id/feedFragment">

    <fragment
        android:id="@+id/feedFragment"
        android:name="com.techfeed.feature.feed.ui.view.FeedFragment"
        android:label="信息流"
        tools:layout="@layout/fragment_feed"
        xmlns:tools="http://schemas.android.com/tools">
        <!-- 声明式参数：跳转时用 navArgs 生成的类型安全类 -->
        <action
            android:id="@+id/action_feed_to_detail"
            app:destination="@id/detailFragment" />
    </fragment>

    <fragment
        android:id="@+id/detailFragment"
        android:name="com.techfeed.feature.detail.ui.view.DetailFragment"
        android:label="详情"
        tools:layout="@layout/fragment_detail">
        <argument
            android:name="articleId"
            app:argType="string"
            android:defaultValue="" />
    </fragment>
</navigation>

// Fragment 中跳转（View 体系）
private fun navigateToDetail(articleId: String) {
    findNavController().navigate(
        FeedFragmentDirections.actionFeedToDetail(articleId = articleId)
    )
}

// 目的地接收参数：navArgs 插件生成 Properties 类
class DetailFragment : Fragment() {
    private val args: DetailFragmentArgs by navArgs()
    // args.articleId 即为类型安全的参数
}

[!TIP] 两套 Navigation 怎么选？ 新项目 / Compose 项目：Navigation-Compose + 类型安全路由。 存量 View 项目：Navigation XML + navArgs（比手写 Bundle 强一个量级）。 两者概念一致（目的地、返回栈、action），学会一套另一套自然通。

2.5 分页：Paging3 最小接入

// 文件路径：docs/samples/ch06/FeedPagingSource.kt
package com.techfeed.feature.feed.data

import androidx.paging.PagingSource
import androidx.paging.PagingState
import com.techfeed.core.model.Article
import com.techfeed.core.network.api.TechFeedApi

/** 数据源：把"第 N 页"的请求翻译成 Paging 能理解的 Page */
class FeedPagingSource(
    private val api: TechFeedApi,
) : PagingSource<Int, Article>() {

    override suspend fun load(params: LoadParams<Int>): LoadResult<Int, Article> {
        val page = params.key ?: 1   // 首次加载 key 为 null
        return try {
            val response = api.getFeed(page = page, pageSize = params.loadSize)
            LoadResult.Page(
                data = response.articles,
                prevKey = if (page == 1) null else page - 1,   // 首页没有"上一页"
                nextKey = if (response.hasMore) page + 1 else null,  // 没有更多了
            )
        } catch (e: Exception) {
            LoadResult.Error(e)   // 错误交给 LoadState 处理，不要直接 crash
        }
    }

    override fun getRefreshKey(state: PagingState<Int, Article>): Int? =
        state.anchorPosition?.let { anchor -> state.closestPageToPosition(anchor)?.prevKey?.plus(1) }
}

[!NOTE] 这里注入的是 TechFeedApi（getFeed 返回 FeedPageDto，字段为 articles / hasMore），与第 23/24 章及 sample/ 工程的最终形态一致；第 09 章网络层教学版（FeedApi.getArticles + ApiResponse 信封）是其演进前身。

// Compose 中消费分页流
@Composable
fun PagedFeedList(viewModel: FeedViewModel = hiltViewModel()) {
    val items = viewModel.articles.collectAsLazyPagingItems()

    when {
        items.loadState.refresh is LoadState.Loading -> FullScreenLoading()
        items.loadState.refresh is LoadState.Error -> ErrorRetry(
            onRetry = { items.retry() }
        )
        else -> LazyColumn {
            items(count = items.itemCount, key = items.itemKey { it.id }) { index ->
                items[index]?.let { article -> ArticleListItem(article, onClick = {}) }
            }
            // 底部加载更多
            if (items.loadState.append is LoadState.Loading) {
                item { LoadingFooter() }
            }
        }
    }
}

三、常见坑 ⚠️

四、调试技巧

# 1. 观察导航动作（logcat 里 Nav 报告每次入栈出栈）
adb logcat -s NavController

# 2. 查看返回栈
adb shell dumpsys activity activities | grep -A 20 "Historical Record"

Compose 侧：

• navController.addOnDestinationChangedListener { _, dest, _ -> Log.d("Nav", "→ ${dest.route}") } 打印路由切换轨迹。
• 列表调试：在 item 的 key 里临时拼上 hashCode()，如果滚动时频繁变化说明 key 不稳定。
• LazyColumn 的 beyondBoundsPageCount/userScrollEnabled 等参数可用于复现滚动边界问题。

RecyclerView 侧：

• RecyclerView.setItemViewCacheSize() 与 RecycledViewPool 状态可在 Profiler 的 Memory 面板观察。
• Adapter.setHasStableIds(true)（配 getItemId）是 DiffUtil 的替代，但只适合全部 item 类型一致的简单列表。

五、最佳实践

1. key 永远用业务 id，位置、索引、hashCode 都不是身份。
2. 列表项最小化数据：传 Article 就够，别传 UiState；Compose 中每个 item 一个重组边界。
3. 跳转收敛到 NavHost：Screen 组件只暴露 onArticleClick: (String) -> Unit 回调，不 import 导航库——组件才能脱离导航独立测试。
4. 路由用类型安全建模（@Serializable data class），告别字符串拼接。
5. 分页与缓存分离：Paging 管数据流，本地缓存策略交给 Repository（第 10、25 章）。
6. 防重复跳转：统一在 NavHost 层做 launchSingleTop，而不是每个点击回调里各自判断。
7. DiffUtil 只比较"身份 + 内容"：areContentsTheSame 直接用 data class 的 equals；如有高频字段（如未读数），实现 ChangePayload 做局部刷新。
8. 多类型列表用 contentType / getItemViewType 明确声明，复用效率显著提升。

// ListView：无强制复用约定、无差量更新、需要手动 notifyDataSetChanged()
listView.adapter = object : BaseAdapter() {
    override fun getView(position: Int, convertView: View?, parent: ViewGroup?): View {
        var view = convertView
        if (view == null) view = layoutInflater.inflate(R.layout.item, parent, false) // 手写复用
        // 手动 findViewById……
        return view!!
    }
}

// 手写 Bundle 跳转：参数名是魔法字符串，类型不安全
val intent = Intent(context, DetailActivity::class.java)
intent.putExtra("article_id", id)     // 拼错不会报错，运行时才炸

六、本章小结

1. 列表的灵魂是回收复用：RecyclerView 复用 View 对象，LazyColumn 只组合可见项。
2. 稳定 key（业务 id） 是列表正确性的第一原则，两套体系通用。
3. RecyclerView 用 ListAdapter + DiffUtil 获得差量更新；LazyColumn 用 key + contentType + 最小数据 获得高效重组。
4. 导航统一心智模型：NavController 指挥 NavHost 里的目的地入栈出栈；参数用类型安全建模。
5. 屏幕组件只暴露回调（onArticleClick），导航逻辑收敛在 NavHost——组件可独立预览与测试。

下一章：列表和页面都依赖的正确"皮肤"从哪来——资源体系、主题与深浅色、多语言与大屏自适应。

七、动手练习

基础题

1. 用 ListAdapter + DiffUtil 实现一个"文章收藏列表"，支持删除单项，验证删除中间项时动画与状态都正确。
2. 用 LazyColumn 重写第 1 题，注意给 items 加 key；对比删除时的行为差异。
3. 搭建一个两页导航图：列表页 → 详情页（传 articleId），用类型安全路由。

进阶题 4. 给信息流加"Paging3 分页 + 底部加载中/到底提示 + 失败重试"，用 MockWebServer 模拟接口（第 09 章）。 5. 实现多类型列表：文章卡片、广告卡片、日期分隔头三种类型，两套体系各写一遍（contentType / 多 ViewHolder）。 6. 实现"列表滚动位置保存与恢复"：旋转屏幕后 LazyColumn 停留在原位置（提示：rememberLazyListState + rememberSaveable）。

思考题 7. DiffUtil 的 areItemsTheSame 与 areContentsTheSame 为什么必须分开？如果只用 equals 一个函数，会损失什么？ 8. 为什么 Navigation 组件要在页面切换时保存并恢复"视图状态"而不是"重建一切"？它与 ViewModel 的保存是同一层吗？ 9. LazyColumn 中 item 里调用 remember(article.id) { ... } 的语义是什么？如果 key 换成 position 会出什么问题？

📄 第 07 章 资源、主题与自适应 07-resources-theming-adaptive.md✓ 标记已学

阶段：入门 ｜ 预计阅读 55 min ｜ 代码落地模块：:core:designsystem 前置：第 04 章 View 与 XML ｜ 第 05 章 Compose 基础 相关章节：第 19 章 安全加固（关于国际化合规） ｜ 第 20 章 构建与发布

学习目标

• [ ] 掌握 res/ 目录的资源分类与限定符（Qualifier）匹配规则，能解释"系统如何选中正确的资源"。
• [ ] 会管理 strings、colors、dimens、styles/themes，理解"资源驱动"的设计思维。
• [ ] 能正确实现深色模式与多语言（含 RTL），并知道为什么禁止硬编码颜色和文案。
• [ ] 会用矢量图（VectorDrawable）与 WebP 控制图片资源体积与质量。
• [ ] 理解窗口尺寸类（WindowSizeClass），能做手机/平板/折叠屏的自适应布局。

一、核心概念

1.1 res 目录与资源类型

res/
├─ drawable/            # 矢量图、Shape、LayerList、位图
├─ mipmap-*/            # 启动图标（系统会按密度选择，只放 launcher icon）
├─ layout/              # 布局
├─ values/              # strings.xml / colors.xml / dimens.xml / themes.xml / styles.xml
├─ values-night/        # 深色模式限定资源
├─ values-zh-rCN/       # 简体中文限定资源
├─ xml/                 # backup_rules、network_security_config 等
├─ font/                # 自定义字体
└─ raw/                 # 原始文件（音视频、JSON 种子数据）

编译后每个资源都有唯一整数 ID，通过 R 类访问。资源名就是 API：R.string.app_name。

1.2 限定符匹配规则

限定符是目录名的"后缀"，系统在运行时按设备当前配置挑选最匹配的资源：

values-zh-rCN/  → 中文（中国）
values-night/   → 深色模式
layout-land/    → 横屏
drawable-xxhdpi/ → 超高密度屏
values-w600dp/  → 最小宽度 ≥600dp（平板）

匹配规则（重点）：

1. 淘汰：先剔除与设备配置冲突的目录（设备是中文，values-en/ 直接出局）。
2. 逐级选择：按限定符优先级（语言 > 布局方向 > 夜间模式 > 密度 > 尺寸…）选最匹配的。
3. 兜底：无匹配限定目录时，使用不带限定符的默认目录——所以 values/、drawable/ 永远必须存在。

[!WARNING] "只在 values-night/ 放深色、忘了 values/ 放浅色"是高频事故：部分设备/预览环境拿不到 night 资源时直接崩。

1.3 主题 vs 样式

主题的本质是属性查询表：XML 里写 ?attr/colorPrimary，运行时从当前主题查值。这也是深浅色"零代码适配"的机制——同一属性在不同主题下指向不同色值。

Compose 中的对应物是 MaterialTheme(colorScheme, typography, shapes)（第 05 章），两者靠设计令牌对齐。

1.4 窗口尺寸类（WindowSizeClass）

折叠屏与平板普及后，"按屏幕尺寸"判断已经过时，官方推荐按窗口可用宽高分类：

判断依据是窗口而非物理屏幕：分屏、自由窗口、折叠态变化时窗口类随之变化。

二、示例代码

2.1 资源文件组织

<!-- 文件路径：sample/core/designsystem/src/main/res/values/strings.xml -->
<resources>
    <string name="app_name">TechFeed</string>
    <!-- 带占位符的文案：位置参数用 %1$s，翻译人员可自由调整语序 -->
    <string name="author_and_date">%1$s · %2$s</string>
    <!-- 复数：不同数量用不同模板，英文会处理 "1 article" / "3 articles" -->
    <plurals name="article_count">
        <item quantity="one">%d 篇文章</item>
        <item quantity="other">%d 篇文章</item>
    </plurals>
</resources>

<!-- 文件路径：sample/core/designsystem/src/main/res/values/colors.xml -->
<resources>
    <!-- 语义命名，不写"浅蓝/深蓝"这种视觉描述，避免主题切换时语义失效 -->
    <color name="surface">#FDFBFF</color>
    <color name="on_surface">#1A1C1E</color>
    <color name="primary">#1B6EF3</color>
    <color name="progress_track">#1F1A1C1E</color>
    <color name="progress_fill">#FF1B6EF3</color>
</resources>

<!-- 文件路径：sample/core/designsystem/src/main/res/values-night/colors.xml -->
<resources>
    <!-- 深色模式：同名资源覆盖值，业务代码零改动 -->
    <color name="surface">#111318</color>
    <color name="on_surface">#E2E2E9</color>
    <color name="primary">#A6C8FF</color>
</resources>

// 代码中访问资源的正确姿势（View 体系）
binding.tvTitle.text = context.getString(R.string.author_and_date, author.name, date)
binding.root.setBackgroundColor(ContextCompat.getColor(context, R.color.surface))
val count = context.resources.getQuantityString(R.plurals.article_count, n, n)

2.2 主题：XML 侧

<!-- 文件路径：sample/core/designsystem/src/main/res/values/themes.xml -->
<resources>
    <!-- Material3 主题：定义DayNight父主题，深浅色自动切换 -->
    <style name="Theme.TechFeed" parent="Theme.Material3.DayNight.NoActionBar">
        <item name="colorPrimary">@color/primary</item>
        <item name="android:colorBackground">@color/surface</item>
        <item name="android:windowBackground">@color/surface</item>
        <!-- 状态栏跟随 surface 颜色（Android 15+ 已默认沉浸，这里兼容旧版本） -->
        <item name="android:statusBarColor">@android:color/transparent</item>
        <item name="android:windowLightStatusBar">true</item>
    </style>

    <!-- 复用样式：圆角封面 -->
    <style name="RoundedCover">
        <item name="cornerFamily">rounded</item>
        <item name="cornerSize">16dp</item>
    </style>
</resources>

<!-- 文件路径：sample/core/designsystem/src/main/res/values-night/themes.xml -->
<resources>
    <style name="Theme.TechFeed" parent="Theme.Material3.DayNight.NoActionBar">
        <item name="colorPrimary">@color/primary</item>
        <item name="android:colorBackground">@color/surface</item>
        <item name="android:windowBackground">@color/surface</item>
        <item name="android:statusBarColor">@android:color/transparent</item>
        <item name="android:windowLightStatusBar">false</item>
    </style>
</resources>

2.3 主题：Compose 侧（与 XML 对齐）

// 文件路径：sample/core/designsystem/src/main/java/com/techfeed/core/designsystem/theme/Tokens.kt
package com.techfeed.core.designsystem.theme

import androidx.compose.material3.Typography
import androidx.compose.material3.Shapes
import androidx.compose.foundation.shape.RoundedCornerShape
import androidx.compose.ui.text.TextStyle
import androidx.compose.ui.text.font.FontWeight
import androidx.compose.ui.unit.dp
import androidx.compose.ui.unit.sp

/** 设计令牌：与 XML 主题共用同一套数值，保证双体系视觉一致 */
val TechFeedTypography = Typography(
    headlineSmall = TextStyle(fontSize = 24.sp, fontWeight = FontWeight.SemiBold, lineHeight = 32.sp),
    titleMedium = TextStyle(fontSize = 16.sp, fontWeight = FontWeight.Medium, lineHeight = 24.sp),
    bodyMedium = TextStyle(fontSize = 14.sp, lineHeight = 20.sp),
    bodySmall = TextStyle(fontSize = 12.sp, lineHeight = 16.sp),
)

val TechFeedShapes = Shapes(
    small = RoundedCornerShape(8.dp),
    medium = RoundedCornerShape(12.dp),
    large = RoundedCornerShape(16.dp),
)

[!TIP] 双体系并行时，设计令牌是唯一对齐点：XML 的 styles.xml 与 Compose 的 Theme.kt 都从同一份设计规范生成。 团队可以写一个脚本从 Figma 导出令牌同时生成两份代码，杜绝"两边颜色不一致"的低级 bug。

2.4 矢量图与图片资源

<!-- 文件路径：docs/samples/ch07/ic_favorite_border.xml -->
<!-- 矢量图：一个文件适配所有密度，体积只有位图的几百分之一 -->
<vector xmlns:android="http://schemas.android.com/apk/res/android"
    android:width="24dp"
    android:height="24dp"
    android:viewportWidth="24"
    android:viewportHeight="24"
    android:tint="?attr/colorControlNormal">
    <path
        android:fillColor="@android:color/white"
        android:pathData="M16.5,3c-1.74,0 -3.41,0.81 -4.5,2.09C10.91,3.81 9.24,3 7.5,3 4.42,3 2,5.42 2,8.5c0,3.78 3.4,6.86 8.55,11.54L12,21.35l1.45,-1.32C18.6,15.36 22,12.28 22,8.5 22,5.42 19.58,3 16.5,3zM12.1,18.55l-0.1,0.1 -0.1,-0.1C7.14,14.24 4,11.39 4,8.5 4,6.5 5.5,5 7.5,5c1.54,0 3.04,0.99 3.57,2.36h1.87C13.46,5.99 14.96,5 16.5,5c2,0 3.5,1.5 3.5,3.5 0,2.89 -3.14,5.74 -7.9,10.05z" />
</vector>

图片资源决策表：

[!TIP] mipmap 目录只放启动图标，其余图片一律放 drawable；启动图标要提供自适应图标（ic_launcher.xml + 前景/背景层）。

2.5 多语言与 RTL

values/            # 默认（英语），翻译缺失时的兜底 —— 必须完整
values-zh-rCN/     # 简体中文
values-zh-rTW/     # 繁体中文（注意：使用中国台湾等地区代码，遵循 ISO 639-1/3166 规范）
values-ar/         # 阿拉伯语：布局需支持 RTL 镜像

RTL 适配清单：

<!-- 用 start/end 而不是 left/right，RTL 下自动镜像 -->
android:layout_marginStart="8dp"
android:paddingEnd="16dp"
<!-- 图标是否需要镜像 -->
android:autoMirrored="true"

// 强制应用内语言切换（AppCompat 1.6+，无需重启 Activity）
val localeList = LocaleListCompat.forLanguageTags("zh-CN")
AppCompatDelegate.setApplicationLocales(localeList)

[!WARNING] 文案绝不能写在代码或布局里（android:text="确认"）。一是不走翻译流程，二是 Lint 会报 HardcodedText。所有用户可见文案进 strings.xml。

2.6 窗口尺寸类自适应

// 文件路径：sample/app/src/main/java/com/techfeed/app/ui/TechFeedApp.kt（节选）
package com.techfeed.app.ui

import androidx.compose.material3.windowsizeclass.WindowWidthSizeClass
import androidx.compose.material3.windowsizeclass.ExperimentalMaterial3WindowSizeClassApi
import androidx.compose.material3.windowsizeclass.calculateWindowSizeClass
import androidx.compose.runtime.Composable
import androidx.activity.ComponentActivity

@OptIn(ExperimentalMaterial3WindowSizeClassApi::class)
@Composable
fun TechFeedApp(activity: ComponentActivity) {
    // 窗口尺寸类：随分屏、折叠、旋转自动变化
    val windowSize = calculateWindowSizeClass(activity)

    when (windowSize.widthSizeClass) {
        WindowWidthSizeClass.Compact -> FeedScreenCompact()      // 手机：单栏 + 底部导航
        WindowWidthSizeClass.Medium -> FeedScreenMedium()        // 小平板：导航栏 + 单列表
        WindowWidthSizeClass.Expanded -> FeedScreenExpanded()    // 平板横屏：列表+详情 双栏
        else -> FeedScreenCompact()
    }
}

// 双栏（列表-详情）是平板体验的关键：不能只是"放大版手机 UI"
@Composable
fun FeedScreenExpanded() {
    Row {
        ArticleList(modifier = Modifier.width(360.dp))
        VerticalDivider()
        DetailPane(modifier = Modifier.weight(1f))   // 详情占据剩余宽度
    }
}

三、常见坑 ⚠️

四、调试技巧

1. 预览任意配置：Android Studio 布局预览可切换深色、语言、字号、屏幕尺寸，不用真机来回折腾。
2. 强制深色模式：

   adb shell cmd uimode night yes
   adb shell cmd uimode night no
   

3. 强制 RTL 布局：开发者选项 → 强制 RTL 布局方向，立刻暴露所有 left/right 残留。
4. 资源混淆排查：怀疑资源名冲突时用 aapt2 dump resources app-debug.apk | grep <name> 查看 APK 内资源表。
5. 图片内存估算：一张 1080×1920 的 ARGB_8888 位图占 8.3MB 内存（1080×1920×4 字节），与文件大小无关——这就是为什么要让 Coil 下载"合适尺寸"的图（第 17 章）。
6. 翻译完整性：./gradlew lint 会输出 MissingTranslation 与 PluralsCandidate 报告。

五、最佳实践

1. 资源名语义化：color/surface、dimen/spacing_m、style/TextTitle，杜绝 color/blue1。
2. 默认目录永远完整：values/、drawable/ 是兜底，不能为空壳。
3. 一切用户可见文案进 strings.xml，占位符用 %1$s 显式编号。
4. 图标优先矢量图，内容图用 WebP；mipmap 只放启动图标。
5. 深浅色/多语言零代码适配：靠限定符与主题属性，不要在代码里 if (isDark) ...。
6. 大屏不是放大版手机：用 WindowSizeClass 切换导航形态与双栏布局。
7. 设计令牌双端同源：XML 主题与 Compose 主题从同一份令牌生成。
8. 无障碍从资源开始：contentDescription、对比度（4.5:1）、sp 字号、触控目标 ≥48dp。

六、本章小结

1. res/ 是声明式配置中心：资源名即 API，限定符即条件，运行时按设备配置自动匹配。
2. 主题是属性查询表：?attr/colorXxx 让深浅色切换零代码；Compose 与 XML 靠设计令牌对齐。
3. 文案进 strings.xml（显式占位符 + plurals），颜色走语义命名，图标优先矢量图。
4. 多语言三件套：默认语言兜底完整、RTL 用 start/end、应用内切换用 AppCompatDelegate。
5. 自适应的正解是 WindowSizeClass：手机单栏、平板双栏，窗口变化驱动布局重构。

下一章：跨出"页面"的边界——Intent 如何发起与接收通信、权限如何申请、进程之间如何对话。

七、动手练习

基础题

1. 为 TechFeed 补全深色模式：把第 04 章 ArticleHeaderView 的所有硬编码色替换为主题属性，用 adb shell cmd uimode night yes/no 验证零代码切换。
2. 新建 values-zh-rCN/strings.xml，给现有页面补一份中文文案，验证系统语言切换后即时生效。
3. 把一张 512×512 的 PNG 图标转成 VectorDrawable，对比资源体积与各密度下的清晰度。

进阶题 4. 实现"应用内语言切换"：设置页提供中文/英文选项，用 AppCompatDelegate.setApplicationLocales 即时生效并持久化。 5. 用 WindowSizeClass 实现列表-详情双栏：手机上点击跳转详情页，平板（Expanded）上右侧面板内嵌显示。 6. 把 App 的全部图标资源从 PNG 迁移到矢量图，统计 APK 体积变化（用 ./gradlew assembleDebug 前后对比）。

思考题 7. 为什么 Android 要求"默认资源目录必须存在"？如果不存在，资源解析失败时会发生什么？ 8. "设计令牌"解决的是设计系统的什么问题？如果没有令牌，双体系（XML+Compose）并行开发会积累哪类 bug？ 9. WindowSizeClass 为什么以"窗口"而非"屏幕"为判断依据？举两个会导致两者不一致的真实场景。

📄 第 08 章 Intent、IPC 与权限 08-intent-ipc-and-permissions.md✓ 标记已学

阶段：入门 ｜ 预计阅读 55 min ｜ 代码落地模块：:feature:auth、:app 前置：第 03 章 应用组件与生命周期 ｜ 第 06 章 导航 相关章节：第 13 章 后台任务与通知 ｜ 第 19 章 安全加固

学习目标

• [ ] 能区分显式与隐式 Intent，掌握 Intent 的组成（action、data、extras、flags）。
• [ ] 会实现与调试深链（Deep Link）与 App Links，处理"从外部拉起 App"的完整链路。
• [ ] 理解运行时权限模型（普通/危险/特殊权限），能写出规范的通知/定位权限申请流程。
• [ ] 理解 Android 的进程隔离与 Binder 通信模型，能解释 AIDL 解决什么问题。
• [ ] 知道跨进程传数据的边界（Bundle 大小限制、Serializable vs Parcelable）。

一、核心概念

1.1 Intent 的解剖

flowchart TB
    I["Intent（意图）"]
    I --> ACT["action：要做什么（VIEW / SEND / ...）"]
    I --> DATA["data + type：对什么做（URI + MIME）"]
    I --> CAT["category：附加语境（BROWSABLE / DEFAULT）"]
    I --> EX["extras：键值对参数（Bundle）"]
    I --> CMP["component：明确目标（显式 Intent）"]

// 显式：应用内跳转（新代码应优先走 Navigation，Intent 用于启动 Activity 场景）
val intent = Intent(context, DetailActivity::class.java)
    .putExtra("articleId", articleId)

// 隐式：交给系统匹配合适的处理者
val share = Intent(Intent.ACTION_SEND).apply {
    type = "text/plain"
    putExtra(Intent.EXTRA_TEXT, "推荐阅读：$title $url")
}
// 用 chooser 让用户每次选择分享目标，而不是记忆默认应用
context.startActivity(Intent.createChooser(share, "分享文章"))

[!WARNING] 隐式 Intent 的响应方是全系统。发起前必须检查有没有 App 能接： intent.resolveActivity(packageManager) != null（Android 11+ 还需在 Manifest 声明 <queries>，见下文）。

1.2 深链与 App Links

<!-- 文件路径：sample/app/src/main/AndroidManifest.xml（节选，第 03 章已出现，这里补全说明） -->
<!-- 自定义 scheme：开发调试方便，但可被劫持，正式收单等敏感场景必须用 App Links -->
<intent-filter>
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data android:scheme="techfeed" android:host="article" />
</intent-filter>

<!-- App Links：autoVerify=true 触发系统域名验证 -->
<intent-filter android:autoVerify="true">
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data android:scheme="https" android:host="techfeed.dev" android:pathPrefix="/article" />
</intent-filter>

服务器侧验证文件（路径固定，不可改）：

// 文件路径（服务器）：https://techfeed.dev/.well-known/assetlinks.json
[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.techfeed.app",
    "sha256_cert_fingerprints": [
      "AB:CD:EF:...（签名证书 SHA-256，用 keytool 获取，debug 与 release 各一条）"
    ]
  }
}]

1.3 Android 权限模型

核心流程：

flowchart LR
    A["需要危险权限"] --> B{"清单已声明?"}
    B -->|否| F["直接崩溃 SecurityException"]
    B -->|是| C{"已授权?"}
    C -->|是| E["执行"]
    C -->|否| D{"shouldShowRequestPermissionRationale?"}
    D -->|"true（拒绝过）"| G["先解释为什么需要，再申请"]
    D -->|"false（首次）"| H["直接申请"]
    G --> H
    H --> I{"用户授予?"}
    I -->|否| J["降级运行 / 引导设置页"]

[!IMPORTANT] 权限三原则：最小化（不要一次申请一串）、按需申请（用到才申请，且解释用途）、优雅降级（拒绝后功能不可用但 App 可用）。 上架审核（包括国内应用商店）都会检查权限与功能的匹配度。

1.4 进程隔离与 Binder

flowchart LR
    subgraph P1["App A 进程（沙箱）"]
        A["A 的内存空间"]
    end
    subgraph K["内核空间"]
        BD["Binder 驱动"]
    end
    subgraph P2["App B / 系统服务进程"]
        B["B 的内存空间"]
    end
    A -->|"copy_from_user（一次拷贝）"| BD
    BD -->|"copy_to_user"| B

• 每个 App 运行在独立进程、独立沙箱，不能直接读写对方内存。
• 所有跨进程调用（IPC）都经过 Binder 驱动：系统服务（AMS、WMS、PMS）本质都是 Binder 服务，你调用的 startActivity 最终都是一次 IPC。
• 应用层跨进程通信的选择：AIDL（强类型接口）、Messenger（消息队列式）、ContentProvider（结构化数据）、Broadcast（一对多通知）、文件/SharedPreferences（不推荐跨进程，有并发问题）。

二、示例代码

2.1 运行时权限：通知权限完整流程

// 文件路径：docs/samples/ch08/NotificationPermissionManager.kt
package com.techfeed.feature.push

import android.Manifest
import android.content.Context
import android.content.pm.PackageManager
import android.os.Build
import androidx.core.content.ContextCompat
import androidx.activity.ComponentActivity
import androidx.activity.result.contract.ActivityResultContracts

/**
 * 通知权限管理（Android 13+ POST_NOTIFICATIONS 为运行时权限）。
 * 设计要点：
 *  1. 权限逻辑集中在一个类里，UI 层只调用 askIfNeeded()；
 *  2. 拒绝后不重复骚扰：第二次拒绝引导去系统设置。
 */
class NotificationPermissionManager(
    private val activity: ComponentActivity,
    private val onResult: (granted: Boolean) -> Unit,
) {
    private val launcher = activity.registerForActivityResult(
        ActivityResultContracts.RequestPermission()
    ) { granted -> onResult(granted) }

    fun isGranted(): Boolean =
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
            ContextCompat.checkSelfPermission(
                activity, Manifest.permission.POST_NOTIFICATIONS
            ) == PackageManager.PERMISSION_GRANTED
        } else {
            true   // Android 13 以下安装即授予
        }

    /** 入口：先判断，被拒过一次则先解释再申请 */
    fun askIfNeeded(explainRationale: () -> Unit) {
        when {
            isGranted() -> onResult(true)
            activity.shouldShowRequestPermissionRationale(Manifest.permission.POST_NOTIFICATIONS) ->
                explainRationale()   // 用户拒绝过：先弹解释对话框，确认后再 launch
            else -> launcher.launch(Manifest.permission.POST_NOTIFICATIONS)
        }
    }

    /** 引导用户去系统设置（彻底拒绝后唯一路径） */
    fun openAppSettings() {
        activity.startActivity(
            android.content.Intent(
                android.provider.Settings.ACTION_APP_NOTIFICATION_SETTINGS
            ).putExtra(android.provider.Settings.EXTRA_APP_PACKAGE, activity.packageName)
        )
    }
}

2.2 深链接收与分发

// 文件路径：sample/app/src/main/java/com/techfeed/app/deeplink/DeepLinkParser.kt
package com.techfeed.app.deeplink

import android.net.Uri

/** 深链解析：把 URI 翻译成强类型的路由指令，白名单校验是安全底线 */
sealed interface DeepLink {
    data class Article(val id: String) : DeepLink
    data class Profile(val userId: String) : DeepLink
    data object Home : DeepLink
}

object DeepLinkParser {

    fun parse(uri: Uri?): DeepLink {
        if (uri == null) return DeepLink.Home
        return when {
            // techfeed://article/123 或 https://techfeed.dev/article/123
            uri.host == "article" || (uri.host == "techfeed.dev" && uri.pathSegments.firstOrNull() == "article") ->
                DeepLink.Article(uri.lastPathSegment.orEmpty())

            // https://techfeed.dev/u/42
            uri.host == "techfeed.dev" && uri.pathSegments.firstOrNull() == "u" ->
                DeepLink.Profile(uri.pathSegments.getOrNull(1).orEmpty())

            else -> DeepLink.Home   // 未识别一律回首页，绝不能白屏
        }
    }
}

[!NOTE] Android 11+ 的包可见性限制：隐式 Intent 调用 resolveActivity / queryIntentActivities 前， 必须在 Manifest 里声明 <queries>，否则查询结果永远为 null（且不报错，极难排查）：

<!-- 文件路径：sample/app/src/main/AndroidManifest.xml（节选） -->
<queries>
    <!-- 允许查询能处理网页/分享的应用 -->
    <intent>
        <action android:name="android.intent.action.VIEW" />
        <data android:scheme="https" />
    </intent>
    <intent>
        <action android:name="android.intent.action.SEND" />
        <data android:mimeType="text/plain" />
    </intent>
</queries>

2.3 AIDL：跨进程接口的最小示例

// 文件路径：docs/samples/ch08/ICounterService.aidl
// AIDL 文件：定义跨进程接口（服务端与客户端共享同一份）
package com.techfeed.core.common;

interface ICounterService {
    int getCount();
    void increment();
}

// 文件路径：docs/samples/ch08/CounterService.kt
package com.techfeed.core.common

import android.app.Service
import android.content.Intent
import android.os.IBinder
import android.os.Process
import android.util.Log

/** 服务端：实现 AIDL 生成的 Stub，运行在独立进程（Manifest 里 android:process=":counter"） */
class CounterService : Service() {

    private var count = 0

    // Stub 是 AIDL 编译期生成的抽象类，实现了跨进程调用到本地调用的翻译
    private val binder = object : ICounterService.Stub() {
        override fun getCount(): Int = count
        override fun increment() {
            count++
            Log.d("CounterService", "increment in pid=${Process.myPid()}")
        }
    }

    override fun onBind(intent: Intent?): IBinder = binder
}

// 客户端绑定与调用（异步！所有 IPC 调用都可能阻塞，要在子线程做）
suspend fun bindAndIncrement(context: Context) = withContext(Dispatchers.IO) {
    val result = suspendCancellableCoroutine { cont ->
        var service: ICounterService? = null
        val conn = object : ServiceConnection {
            override fun onServiceConnected(name: ComponentName, binder: IBinder) {
                service = ICounterService.Stub.asInterface(binder)
                cont.resume(service)
            }
            override fun onServiceDisconnected(name: ComponentName) { service = null }
        }
        context.bindService(Intent(context, CounterService::class.java), conn, Context.BIND_AUTO_CREATE)
    }
    result?.increment()
}

[!TIP] 大多数业务不需要 AIDL。先问自己：真的要跨进程吗？多数"看似跨进程"的需求（后台任务、定时同步） 用 WorkManager + 单进程就能解决。跨进程的正当理由：独立于主进程的存活需求、复用另一个 App 的能力、内存隔离。

2.4 Parcelable：跨进程/跨页面传对象

// 文件路径：sample/core/model/src/main/java/com/techfeed/core/model/ArticleParcel.kt
package com.techfeed.core.model

import android.os.Parcelable
import kotlinx.parcelize.Parcelize

/**
 * @Parcelize 自动生成读写代码，告别手写 Parcelable 的几百行样板。
 * Parcel 用于：Intent 传参、Bundle、SavedStateHandle、跨进程（同 App 的多进程间）。
 */
@Parcelize
data class ArticleParcel(
    val id: String,
    val title: String,
    val authorId: String,
) : Parcelable

[!WARNING] Bundle 不是数据库。TransactionTooLargeException 的阈值约 1MB（且共享全局缓冲区）， Intent 里只放 id/少量字段，详情数据由目标页面自己加载。把整个文章列表塞进 Intent 是最常见的崩溃来源之一。

三、常见坑 ⚠️

四、调试技巧

# 1. 模拟深链（不经过浏览器，直接测试解析逻辑）
adb shell am start -a android.intent.action.VIEW -d "techfeed://article/a-001"
adb shell am start -a android.intent.action.VIEW -d "https://techfeed.dev/article/a-001"

# 2. 重新触发 App Links 域名验证并查看结果
adb shell pm verify-app-links --re-verify com.techfeed.app
adb shell pm get-app-links com.techfeed.app

# 3. 授予/撤销权限（免得反复点弹窗）
adb shell pm grant com.techfeed.app android.permission.POST_NOTIFICATIONS
adb shell pm revoke com.techfeed.app android.permission.POST_NOTIFICATIONS

# 4. 查看某应用声明的全部权限与授权状态
adb shell dumpsys package com.techfeed.app | grep -A 30 "requested permissions"

# 5. 查看跨进程服务
adb shell dumpsys activity services com.techfeed.app

IDE 内：

• App Links Assistant（Tools → App Links Assistant）可视化生成 intent-filter 与 assetlinks.json。
• 权限调试：Android Studio 的 App Quality Insights / dumpsys 输出配合使用。
• Binder 死锁排查：anr traces（/data/anr/）里的 "held by thread" 是定位 Binder 线程池耗尽的关键。

五、最佳实践

1. 应用内跳转优先 Navigation（第 06 章）；Intent 留给跨应用通信与启动 Activity 场景。
2. 对外暴露的组件一律 exported="false"，深链目的地单独控制并做白名单校验（第 19 章）。
3. 深链解析器独立成类并写单测：URI → 强类型路由，未知输入回首页。
4. 权限集中管理 + 三段式话术：申请前解释（为什么需要）、拒绝后引导（去设置）、降级可用（功能不崩）。
5. IPC 一律异步，且优先评估 WorkManager/单进程方案；AIDL 是最后手段。
6. Intent/Bundle 只传轻量参数（id、标志位），对象传输用 @Parcelize。
7. 敏感操作不用自定义 scheme 深链直接触发（如支付回调），必须用 App Links + 签名校验。
8. 权限申请体验即转化率：在上下文场景中申请（点"开启通知"按钮时），不要在启动页一波带走。

// 旧写法：requestCode 魔法数字 + 回调集中处理，多权限时 if-else 地狱
private fun askCamera() {
    requestPermissions(arrayOf(Manifest.permission.CAMERA), 100)
}

override fun onRequestPermissionsResult(requestCode: Int, permissions: Array<out String>, grantResults: IntArray) {
    if (requestCode == 100 && grantResults[0] == PackageManager.PERMISSION_GRANTED) { /* ... */ }
}

六、本章小结

1. Intent 是组件间的"意图快递单"：显式（指定目标）用于应用内，隐式（描述意图）用于跨应用，发起前必须判空 + <queries>。
2. 深链是流量入口也是攻击面：自定义 scheme 便利但可劫持，敏感场景用 App Links（域名 + 签名指纹双重验证）。
3. 权限分普通/危险/特殊三级；危险权限走"检查 → 解释 → 申请 → 降级"四步，永远最小化与按需。
4. Android 进程互相隔离，一切 IPC 走 Binder；应用层方案按需求选 AIDL/Messenger/Provider/Broadcast。
5. Bundle 有 ~1MB 的隐含上限：Intent 传 id，不传数据。

下一章：进入进阶篇——网络请求。从一条 HTTP 请求在 OkHttp 拦截器链里的旅程讲起。

七、动手练习

基础题

1. 实现"分享文章"功能：构造隐式 ACTION_SEND Intent，处理"没有任何可分享应用"的降级提示。
2. 为 TechFeed 添加 techfeed://article/{id} 深链，写 DeepLinkParser 并为它写 5 个单元测试（正常、缺参、未知 host、https、空 URI）。
3. 给 App 加通知权限申请：首次进入消息中心时申请，拒绝一次后弹解释对话框，彻底拒绝后引导设置页。

进阶题 4. 用 App Links Assistant 完成 https://techfeed.dev/article/{id} 的配置，并用 pm verify-app-links 验证通过（可自建本地服务放 assetlinks.json）。 5. 实现一个跨进程计数服务（:counter 进程 + AIDL），主进程 UI 实时显示计数值，并验证进程隔离（adb shell ps | grep counter）。 6. 把第 03 章的详情页改造为"只传 articleId"，用 SavedStateHandle 恢复，构造一个 2MB 的数据场景验证 TransactionTooLargeException 的触发与修复。

思考题 7. 为什么 Binder 只需要一次内存拷贝，而传统 Socket IPC 需要两次？（提示：mmap 映射接收方缓冲区） 8. "深链白名单"应该校验哪些东西？只有 host 够吗？参数（articleId）层面还要防什么？ 9. Android 13 把通知列为运行时权限，这对"推送到达率"产品指标意味着什么？你会如何设计权限引导时机？

📄 第 09 章 网络请求：OkHttp 与 Retrofit 09-networking-retrofit-okhttp.md✓ 标记已学

阶段：进阶 ｜ 预计阅读 60 min ｜ 代码落地模块：:core:network、:core:model 前置：第 01 章 Kotlin 速成与协程预热 ｜ 第 02 章 工程结构与 Gradle 相关章节：第 10 章 数据存储 ｜ 第 11 章 协程与 Flow ｜ 第 12 章 依赖注入 ｜ 第 19 章 安全加固

学习目标

• [ ] 理解一次网络请求从发起到拿到数据的完整链路，说清 OkHttp 与 Retrofit 各自的职责边界。
• [ ] 掌握应用拦截器与网络拦截器的区别，能独立写出鉴权注入、日志、重试、错误处理、缓存五类拦截器。
• [ ] 用 kotlinx.serialization 定义数据传输对象（Data Transfer Object, DTO），处理字段重命名、字段缺失与未知字段。
• [ ] 能把后端的统一响应封装映射为 Result<T> / AppError，让 UI 层拿到结构化错误而不是裸异常。
• [ ] 会用 MockWebServer 为接口层写测试，并为第 19 章的证书绑定（Certificate Pinning）预留接入点。

一、核心概念

1.1 一次请求的完整链路

Android 上的网络请求不是"一个库干完所有事"，而是四层协作：

flowchart TB
    A["UI / ViewModel<br/>发起请求"] --> B["Repository<br/>业务语义 + 线程切换"]
    B --> C["Retrofit 接口<br/>把 Kotlin 函数翻译成 HTTP 请求"]
    C --> D["Converter<br/>对象 ↔ JSON"]
    D --> E["OkHttp<br/>拦截器链 + 连接池 + 缓存 + TLS"]
    E --> F["Socket / 网络"]
    F --> E
    E --> D
    D --> C
    C --> B
    B -->|"Result&lt;T&gt;"| A

四层各自的职责，混用会让代码难以测试：

[!TIP] 判断代码放错层的标准：Repository 里出现 @GET / @POST 注解就说明 Retrofit 泄漏到了业务层； 反过来，拦截器里出现 Article 这种领域模型，就说明业务泄漏到了传输层。

1.2 拦截器链：OkHttp 最值得理解的设计

OkHttp 把"发请求"拆成一条责任链（Chain of Responsibility），每个拦截器拿到 Request，可以改写它、短路它、或交给下一个。

flowchart TB
    R["原始 Request"] --> A1["应用拦截器 ①<br/>AuthInterceptor 注入 Token"]
    A1 --> A2["应用拦截器 ②<br/>HttpLoggingInterceptor"]
    A2 --> A3["应用拦截器 ③<br/>ErrorInterceptor 统一错误"]
    A3 --> B1["RetryAndFollowUp<br/>重定向 / 路由失败重试"]
    B1 --> B2["Bridge<br/>补 Content-Type/gzip 头"]
    B2 --> B3["Cache<br/>读写本地缓存"]
    B3 --> B4["Connect<br/>建立连接 / 连接池复用"]
    B4 --> B5["CallServer<br/>真正的 Socket 读写"]
    B5 --> B4 --> B3 --> B2 --> B1
    B1 --> A3 --> A2 --> A1 --> P["最终 Response"]

应用拦截器（Application Interceptor） 与 网络拦截器（Network Interceptor） 的差异是面试与实战的高频分水岭：

[!WARNING] 不要在应用拦截器里做"只关心真实网络流量"的统计——缓存命中时它照样执行，你的埋点会虚高。 反过来，鉴权头必须用应用拦截器注入：网络拦截器在缓存命中时不执行，会导致缓存路径下丢 token。

1.3 Retrofit 到底帮你做了什么

Retrofit 不是 HTTP 客户端，它是"把 Kotlin 接口翻译成 OkHttp 调用"的动态代理。你写的 suspend fun 方法，在运行时被解析成 Request，交给 OkHttp 执行，返回值再交给 Converter 反序列化。

关键收益有三点：

1. suspend 函数天然在 OkHttp 的线程池执行，不需要你手动 withContext(Dispatchers.IO)（第 11 章会解释为什么）。
2. 接口是 Kotlin 接口，可以直接用 Fake 实现做单元测试，不必碰 HTTP。
3. 参数注解（@Query / @Path / @Body / @Header）把 URL 拼装的样板代码消灭掉。

1.4 序列化：为什么选 kotlinx.serialization

kotlinx.serialization 的两个必开配置：ignoreUnknownKeys = true（后端加字段不会让 App 崩）、coerceInputValues = true（字段类型异常时回落到默认值而非抛异常）。

1.5 统一响应封装与 Result 映射

国内后端通常返回统一信封：

{ "code": 0, "message": "ok", "data": { "id": "a-001", "title": "..." } }

处理方式：DTO 层保留信封结构，Repository 层把它翻译成第 01 章定义的 Result<T> / AppError。UI 层永远不认识 code 这个字段——这样后端换协议（比如改 gRPC、改 GraphQL）时，改动被关在 :core:network 里。

1.6 缓存：Cache-Control 与离线可用

OkHttp 的 Cache 完全遵循 HTTP 语义：Cache-Control: max-age=60 表示 60 秒内直接用缓存。麻烦在于很多后端不给这个头，于是你有两个选择：

• 服务端协商：推动后端补 Cache-Control（最优）。
• 客户端改写：写一个应用拦截器，给响应补上 Cache-Control（务实做法，本章示例采用）。

离线场景（完全没网）需要 Cache-Control: only-if-cached + max-stale，配合第 10 章的 Room 做"网络为源、本地为缓存"的单一数据源（Single Source of Truth, SSOT）。

1.7 Mock 与安全的两个"预留口"

• Mock：接口层测试不该依赖真实后端。MockWebServer 起一个本地 HTTP 服务，能精确控制响应码、延迟、畸形 JSON——这是验证"错误处理写对了没有"的唯一可靠方式。
• 安全：证书绑定放在第 19 章展开，但接入点必须现在就留：OkHttpClient.Builder 里留一个 certificatePinner 的注入位，否则第 19 章要改所有构造点。

二、示例代码

2.1 模块依赖：版本一律收口

// 文件路径：sample/core/network/build.gradle.kts
plugins {
    alias(libs.plugins.techfeed.android.library)
    alias(libs.plugins.kotlin.serialization)   // 开启 kotlinx.serialization 编译器插件
    alias(libs.plugins.hilt)
    alias(libs.plugins.ksp)
}

dependencies {
    // api：Article/Result 出现在对外签名里，必须传递
    api(projects.core.model)
    implementation(projects.core.common)
    implementation(libs.bundles.network)          // retrofit + okhttp + serialization
    debugImplementation(libs.okhttp.logging)      // ⚠️ 日志拦截器只进 debug 包
    implementation(libs.hilt.android)
    ksp(libs.hilt.compiler)
    testImplementation(libs.bundles.testing.unit)
}

[!NOTE] 具体版本号全部在 gradle/libs.versions.toml 中定义，正文不硬编码任何版本。升级时只改 TOML 一处。

2.2 DTO 定义与 @Serializable

// 文件路径：sample/core/network/src/main/java/com/techfeed/core/network/model/ArticleDto.kt
package com.techfeed.core.network.model

import com.techfeed.core.model.Article
import com.techfeed.core.model.Author
import kotlinx.serialization.SerialName
import kotlinx.serialization.Serializable

/** 后端返回的统一信封：code 为 0 表示成功 */
@Serializable
data class ApiResponse<T>(
    val code: Int = 0,
    val message: String? = null,
    val data: T? = null,
)

/** DTO 只负责"描述线上 JSON 长什么样"，不要在这里写业务逻辑 */
@Serializable
data class ArticleDto(
    @SerialName("id") val id: String,
    @SerialName("title") val title: String,
    @SerialName("summary") val summary: String? = null,     // 可空 + 默认值，后端不返回也不崩
    @SerialName("cover_url") val coverUrl: String? = null,  // 下划线命名靠 @SerialName 映射
    @SerialName("author") val author: AuthorDto? = null,
    @SerialName("published_at") val publishedAt: Long = 0L,
    @SerialName("tags") val tags: List<String> = emptyList(),
)

@Serializable
data class AuthorDto(
    @SerialName("id") val id: String,
    @SerialName("nickname") val name: String,
    @SerialName("avatar") val avatarUrl: String? = null,
)

/** DTO → 领域模型。转换集中在一处，后端改字段名时只改这里 */
fun ArticleDto.toDomain(isFavorite: Boolean = false): Article = Article(
    id = id,
    title = title,
    summary = summary.orEmpty(),
    coverUrl = coverUrl,
    author = author?.toDomain() ?: Author(id = "", name = "佚名", avatarUrl = null),
    publishedAt = publishedAt,
    isFavorite = isFavorite,
)

fun AuthorDto.toDomain(): Author = Author(id = id, name = name, avatarUrl = avatarUrl)

// 文件路径：docs/samples/ch09/AppJson.kt
package com.techfeed.core.network.json

import kotlinx.serialization.json.Json

/**
 * 全局唯一的 Json 实例。
 * ignoreUnknownKeys：后端新增字段时老版本 App 不会崩溃（线上事故高发点）
 * coerceInputValues：类型不匹配时回落到默认值，避免单个脏数据毁掉整个列表
 * explicitNulls = false：缺失字段用默认值，减少 DTO 里的 ? 噪音
 */
val AppJson = Json {
    ignoreUnknownKeys = true
    coerceInputValues = true
    explicitNulls = false
    encodeDefaults = true
    isLenient = true          // 容忍非标准 JSON（如 NaN、单引号）
}

2.3 鉴权注入：应用拦截器 + Token 提供器

// 文件路径：sample/core/network/src/main/java/com/techfeed/core/network/AuthInterceptor.kt
package com.techfeed.core.network

import okhttp3.Interceptor
import okhttp3.Response
import javax.inject.Inject
import javax.inject.Singleton

/** Token 由 :core:datastore 实现，:core:network 只依赖接口 —— 依赖倒置（第 15 章） */
interface TokenProvider {
    fun accessToken(): String?
    suspend fun refreshToken(): String?   // 刷新是挂起操作，不能阻塞拦截器线程
}

@Singleton
class AuthInterceptor @Inject constructor(
    private val tokenProvider: TokenProvider,
) : Interceptor {

    override fun intercept(chain: Interceptor.Chain): Response {
        val token = tokenProvider.accessToken()
        // 无 token（未登录）时保持原请求，避免给匿名接口强加无效头
        val request = if (token.isNullOrBlank()) {
            chain.request()
        } else {
            chain.request().newBuilder()
                .header("Authorization", "Bearer $token")
                .header("X-Client", CLIENT_ID)
                .build()
        }
        return chain.proceed(request)
    }

    private companion object {
        const val CLIENT_ID = "android"
    }
}

// 文件路径：sample/core/network/src/main/java/com/techfeed/core/network/TokenAuthenticator.kt
package com.techfeed.core.network

import kotlinx.coroutines.runBlocking
import okhttp3.Authenticator
import okhttp3.Request
import okhttp3.Response
import okhttp3.Route
import javax.inject.Inject
import javax.inject.Singleton

/**
 * 401 时刷新 Token 并重发请求。
 * ⚠️ Authenticator 接口是同步的，这里用 runBlocking 是"必要的妥协"：
 * 线程已是 OkHttp 的后台线程，不会阻塞主线程；但要确保 refreshToken 自带超时。
 */
@Singleton
class TokenAuthenticator @Inject constructor(
    private val tokenProvider: TokenProvider,
) : Authenticator {

    override fun authenticate(route: Route?, response: Response): Request? {
        // 关键：限制重试次数，否则刷新接口本身也返回 401 时会无限循环
        if (response.count() >= MAX_RETRY) return null

        val newToken = runBlocking { tokenProvider.refreshToken() } ?: return null
        return response.request.newBuilder()
            .header("Authorization", "Bearer $newToken")
            .build()
    }

    /** 统计同一请求被 401 挑战的次数（response.priorResponse 链） */
    private fun Response.count(): Int {
        var result = 1
        var prior = priorResponse
        while (prior != null) {
            result++
            prior = prior.priorResponse
        }
        return result
    }

    private companion object {
        const val MAX_RETRY = 2
    }
}

[!WARNING] Authenticator 只在服务端返回 401 时触发，且必须配合 OkHttpClient.authenticator() 使用。 如果你的后端用 code == 1001 表示登录失效（HTTP 状态仍为 200），它不会触发——这种情况只能在 ErrorInterceptor 或 Repository 里处理。

[!NOTE] 上面是"基础版"：拿到 refresh token 直接换新。sample 工程的实际实现（同一路径）比它多了三件事： Mutex + 双重检查（并发 401 只刷新一次）、独立裸 OkHttpClient 调刷新接口（防止刷新请求自己 401 时无限递归）、 刷新结果经 tokenProvider.refresh() 落盘。完整实现与并发语义详见第 25 章。

2.4 超时、重试与统一错误处理

// 文件路径：docs/samples/ch09/RetryInterceptor.kt
package com.techfeed.core.network

import okhttp3.Interceptor
import okhttp3.Request
import okhttp3.Response
import java.io.IOException
import java.net.SocketTimeoutException
import javax.inject.Inject
import javax.inject.Singleton

@Singleton
class RetryInterceptor @Inject constructor() : Interceptor {

    override fun intercept(chain: Interceptor.Chain): Response {
        val request = chain.request()
        var lastException: IOException? = null

        repeat(MAX_RETRY) { attempt ->
            try {
                val response = chain.proceed(request)
                // 5xx 是服务端临时故障，值得重试；4xx 是客户端错误，重试没有意义
                if (response.isSuccessful || response.code !in RETRYABLE_CODES) return response
                response.close()   // ⚠️ 丢弃的响应必须关闭，否则连接泄漏
            } catch (e: SocketTimeoutException) {
                lastException = e
            } catch (e: IOException) {
                // ConnectException 等：连接层失败可重试
                lastException = e
            }
            if (attempt < MAX_RETRY - 1) backoff(attempt)
        }
        throw lastException ?: IOException("请求失败")
    }

    private fun backoff(attempt: Int) {
        // 指数退避 + 抖动，避免大量客户端同时重试把服务端打垮（惊群）
        val delayMs = BASE_DELAY_MS * (1 shl attempt)
        Thread.sleep(delayMs + (Math.random() * JITTER_MS).toLong())
    }

    private companion object {
        const val MAX_RETRY = 3
        const val BASE_DELAY_MS = 300L
        const val JITTER_MS = 100L
        val RETRYABLE_CODES = 500..599
    }
}

[!WARNING] 只对幂等请求重试。上面示例对 POST 也会重试，实际项目请用 @Headers("X-Idempotent: true") 或自定义标记区分； 下单、支付类接口无脑重试会造成重复扣款。另外 Thread.sleep 在拦截器里是可接受的（拦截器本就运行在后台线程）， 但在协程业务代码里请改用 delay()（第 11 章）。

// 文件路径：docs/samples/ch09/ErrorInterceptor.kt
package com.techfeed.core.network

import com.techfeed.core.model.AppError
import okhttp3.Interceptor
import okhttp3.Response
import java.io.IOException
import javax.inject.Inject
import javax.inject.Singleton

/** 把 HTTP 层异常统一翻译成领域错误 AppError，业务层不再 catch IOException */
class ApiException(val appError: AppError) : IOException(appError.toString())

@Singleton
class ErrorInterceptor @Inject constructor() : Interceptor {

    override fun intercept(chain: Interceptor.Chain): Response {
        val response = try {
            chain.proceed(chain.request())
        } catch (e: IOException) {
            // 网络不可达 / DNS 失败 / 超时：统一包装为 AppError.Network
            throw ApiException(AppError.Network(cause = e))
        }

        if (response.isSuccessful) return response

        val error = when (response.code) {
            401 -> AppError.Auth(reason = "登录已失效")
            403 -> AppError.Auth(reason = "无访问权限")
            404 -> AppError.Http(code = 404, message = "内容不存在")
            in 400..499 -> AppError.Http(code = response.code, message = "请求有误")
            else -> AppError.Http(code = response.code, message = "服务异常")
        }
        response.close()
        throw ApiException(error)
    }
}

2.5 日志拦截器：只进 debug 包、必须脱敏

// 文件路径：sample/core/network/src/main/java/com/techfeed/core/network/di/NetworkModule.kt
package com.techfeed.core.network.di

import com.techfeed.core.network.AppJson
import com.techfeed.core.network.AuthInterceptor
import com.techfeed.core.network.ErrorInterceptor
import com.techfeed.core.network.NetworkConfig
import com.techfeed.core.network.RetryInterceptor
import android.content.Context
import dagger.Module
import dagger.Provides
import dagger.hilt.InstallIn
import dagger.hilt.android.qualifiers.ApplicationContext
import dagger.hilt.components.SingletonComponent
import okhttp3.Cache
import okhttp3.MediaType.Companion.toMediaType
import okhttp3.OkHttpClient
import okhttp3.logging.HttpLoggingInterceptor
import retrofit2.Retrofit
import retrofit2.converter.kotlinx.serialization.asConverterFactory
import java.io.File
import java.util.concurrent.TimeUnit
import javax.inject.Singleton

@Module
@InstallIn(SingletonComponent::class)   // 作用域见第 12 章
object NetworkModule {

    @Provides
    @Singleton
    fun provideOkHttpClient(
        // ⚠️ 不能直接声明 cacheDir: File——裸 File 类型没有绑定，Dagger 会报 missing binding；
        // 正确做法是注入 @ApplicationContext Context，再从 context.cacheDir 取缓存目录
        @ApplicationContext context: Context,
        authInterceptor: AuthInterceptor,
        errorInterceptor: ErrorInterceptor,
        retryInterceptor: RetryInterceptor,
        loggingInterceptor: HttpLoggingInterceptor?,   // 可空：release 变体下由 Hilt 提供 null
    ): OkHttpClient = OkHttpClient.Builder()
        .connectTimeout(10, TimeUnit.SECONDS)     // 建立 TCP/TLS 连接
        .readTimeout(15, TimeUnit.SECONDS)        // 读取响应；大文件接口应单独配置
        .writeTimeout(15, TimeUnit.SECONDS)
        .callTimeout(30, TimeUnit.SECONDS)        // 整体上限，防止慢请求无限占用
        .retryOnConnectionFailure(true)           // OkHttp 内建：路由/连接失败自动换路由
        .cache(Cache(File(context.cacheDir, "http_cache"), CACHE_SIZE_BYTES))
        .addInterceptor(errorInterceptor)         // ⚠️ 顺序即责任链顺序，见 1.2
        .addInterceptor(retryInterceptor)
        .addInterceptor(authInterceptor)
        .apply { loggingInterceptor?.let(::addInterceptor) }   // 日志放最后：看到的是最终发出的请求
        // .certificatePinner(...)  ← 第 19 章在此处接入证书绑定，接入点现在就留好
        .build()

    @Provides
    @Singleton
    fun provideRetrofit(client: OkHttpClient): Retrofit = Retrofit.Builder()
        // BASE_URL 收口在 NetworkConfig.BASE_URL 常量（NetworkConfig.kt）：
        // TokenAuthenticator 构造裸刷新请求时必须复用同一常量，避免两处硬编码漂移。
        // ⚠️ 值必须以 / 结尾，否则报 "baseUrl must end in /"
        .baseUrl(NetworkConfig.BASE_URL)
        .client(client)
        // kotlinx.serialization 的 Converter 需要显式声明媒体类型
        .addConverterFactory(AppJson.asConverterFactory("application/json".toMediaType()))
        .build()

    private const val CACHE_SIZE_BYTES = 10L * 1024 * 1024   // 10MB，按业务数据量调
}

[!TIP] 日志拦截器在 debugImplementation 依赖下，release 编译会直接找不到类——所以用 @Provides ... : HttpLoggingInterceptor? 配合 @Nullable 处理，或者把日志放进 src/debug/ 源码集。别用 if (BuildConfig.DEBUG) 硬编码依赖， 那样 release 包里依然会带上日志库。此外，BODY 级日志会把 Authorization 头原样打进 Logcat——token 可能随日志 进入崩溃报告或用户反馈截图，务必给日志拦截器加 .redactHeader("Authorization") 脱敏（第 19 章展开）。

2.6 缓存：给"没有 Cache-Control 的后端"兜底

// 文件路径：docs/samples/ch09/CacheInterceptor.kt
package com.techfeed.core.network

import okhttp3.Interceptor
import okhttp3.Response
import java.util.concurrent.TimeUnit
import javax.inject.Inject
import javax.inject.Singleton

/**
 * 有网：强制缓存 30 秒（覆盖服务端缺失的 Cache-Control）
 * 无网：允许读取 7 天内的过期缓存（only-if-cached + max-stale）
 */
@Singleton
class OfflineCacheInterceptor @Inject constructor(
    private val networkMonitor: NetworkMonitor,
) : Interceptor {

    override fun intercept(chain: Interceptor.Chain): Response {
        val request = chain.request()
        // 只缓存 GET：POST/PUT 的响应缓存是非法的
        if (request.method != "GET") return chain.proceed(request)

        return if (networkMonitor.isOnline()) {
            val response = chain.proceed(request)
            response.newBuilder()
                .removeHeader("Pragma")                       // 旧时代头，会禁用缓存
                .header("Cache-Control", "public, max-age=$ONLINE_MAX_AGE_S")
                .build()
        } else {
            val requestOffline = request.newBuilder()
                .cacheControl(
                    okhttp3.CacheControl.Builder()
                        .onlyIfCached()                       // 只走缓存，绝不发起网络
                        .maxStale(OFFLINE_MAX_STALE_D, TimeUnit.DAYS)
                        .build(),
                )
                .build()
            val response = chain.proceed(requestOffline)
            // 无网且无缓存时返回 504，交给上层走 Room 兜底（第 10 章）
            if (response.code == 504) response.close()
            response
        }
    }

    private companion object {
        const val ONLINE_MAX_AGE_S = 30
        const val OFFLINE_MAX_STALE_D = 7
    }
}

/** 网络状态抽象：实现见 :core:common，避免拦截器直接依赖 Context */
interface NetworkMonitor {
    fun isOnline(): Boolean
}

2.7 Retrofit 接口：suspend 函数与参数注解

// 文件路径：docs/samples/ch09/FeedApi.kt
package com.techfeed.core.network.api

import com.techfeed.core.network.model.ApiResponse
import com.techfeed.core.network.model.ArticleDto
import com.techfeed.core.network.model.PageDto
import retrofit2.http.GET
import retrofit2.http.Header
import retrofit2.http.Path
import retrofit2.http.Query

interface FeedApi {

    /** suspend：Retrofit 会在后台线程池执行，调用方无需切线程 */
    @GET("v1/articles")
    suspend fun getArticles(
        @Query("page") page: Int,
        @Query("page_size") pageSize: Int = 20,
        @Query("tag") tag: String? = null,          // null 参数会被自动省略，不会拼成 tag=null
        @Header("X-Request-Id") requestId: String,
    ): ApiResponse<PageDto<ArticleDto>>

    @GET("v1/articles/{id}")
    suspend fun getArticleDetail(@Path("id") id: String): ApiResponse<ArticleDto>
}

// 文件路径：sample/core/network/src/main/java/com/techfeed/core/network/api/TechFeedApi.kt
package com.techfeed.core.network.api

import retrofit2.create

/**
 * 所有 Api 的聚合入口，由 Hilt 提供单例。
 * 好处：新增接口只需加一个 val，调用方无需感知 Retrofit 的存在。
 */
class TechFeedApi internal constructor(retrofit: retrofit2.Retrofit) {
    val feed: FeedApi = retrofit.create()
    val auth: AuthApi = retrofit.create()
}

2.8 结果映射：从 ApiResponse 到 Result

// 文件路径：sample/core/network/src/main/java/com/techfeed/core/network/safeCall.kt
package com.techfeed.core.network

import com.techfeed.core.model.AppError
import com.techfeed.core.model.Result
import com.techfeed.core.network.model.ApiResponse
import kotlinx.coroutines.CancellationException

/**
 * 网络调用的统一包装：
 * 1. 捕获 ApiException（来自 ErrorInterceptor）并转成 Result.Failure
 * 2. 拆信封：code != 0 视为业务失败
 * 3. CancellationException 必须原样抛出，绝不能吞（第 11 章）
 */
suspend inline fun <T, R> safeApiCall(
    crossinline call: suspend () -> ApiResponse<T>,
    crossinline map: (T) -> R,
): Result<R> = try {
    val response = call()
    if (response.code == SUCCESS_CODE && response.data != null) {
        Result.Success(map(response.data))
    } else {
        // 业务错误码：登录失效单独归类，便于 UI 跳登录页
        val error = if (response.code == CODE_TOKEN_EXPIRED) {
            AppError.Auth(reason = response.message ?: "登录已失效")
        } else {
            AppError.Http(code = response.code, message = response.message)
        }
        Result.Failure(error)
    }
} catch (e: ApiException) {
    Result.Failure(e.appError)
} catch (e: CancellationException) {
    throw e                     // ⚠️ 取消不是错误，必须向上传递
} catch (e: Exception) {
    Result.Failure(AppError.Unknown(cause = e))
}

private const val SUCCESS_CODE = 0
private const val CODE_TOKEN_EXPIRED = 1001

// 文件路径：sample/core/network/src/main/java/com/techfeed/core/network/datasource/FeedRemoteDataSource.kt
package com.techfeed.core.network.datasource

import com.techfeed.core.model.Article
import com.techfeed.core.model.Result
import com.techfeed.core.network.api.TechFeedApi
import com.techfeed.core.network.model.toDomain
import com.techfeed.core.network.safeApiCall
import java.util.UUID
import javax.inject.Inject
import javax.inject.Singleton

@Singleton
class FeedRemoteDataSource @Inject constructor(
    private val api: TechFeedApi,
) {
    /** 数据源层只做"取数据"，不做缓存策略（那是 Repository 的事，见第 14 章） */
    suspend fun getArticles(page: Int, pageSize: Int = 20): Result<List<Article>> =
        safeApiCall(
            call = { api.feed.getArticles(page, pageSize, requestId = UUID.randomUUID().toString()) },
            map = { page -> page.items.map { it.toDomain() } },
        )
}

// 旧写法：Observable + 线程切换 + 订阅管理，还需要手动处理 dispose
api.getArticles(page)
    .subscribeOn(Schedulers.io())
    .observeOn(AndroidSchedulers.mainThread())
    .subscribe({ list -> render(list) }, { e -> showError(e) })

// 更早的回调写法：嵌套地狱 + 生命周期泄漏风险
api.getArticles(page, object : Callback<List<Article>> {
    override fun onSuccess(data: List<Article>) {
        api.getAuthor(data[0].authorId, object : Callback<Author> { /* ... */ })
    }
})

2.9 UI 层：加载 / 错误态的双体系实现

网络结果最终要落到界面上。这里给同一个"错误 + 重试"界面的两套写法。

// 文件路径：docs/samples/ch09/FeedErrorContent.kt
package com.techfeed.feature.feed.ui

import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.padding
import androidx.compose.material3.Button
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.dp

/** Compose 版：UI 是状态的函数，state 变化自动重组，无需手动 setText */
@Composable
fun FeedErrorContent(
    message: String,
    onRetry: () -> Unit,
    modifier: Modifier = Modifier,
) {
    Column(
        modifier = modifier.fillMaxSize().padding(24.dp),
        verticalArrangement = Arrangement.Center,
        horizontalAlignment = Alignment.CenterHorizontally,
    ) {
        Text(text = message, style = MaterialTheme.typography.bodyLarge)
        Button(onClick = onRetry, modifier = Modifier.padding(top = 16.dp)) {
            Text("重试")
        }
    }
}

<!-- 文件路径：docs/samples/ch09/view_feed_error.xml -->
<?xml version="1.0" encoding="utf-8"?>
<!-- View 版：布局与刷新逻辑分离，需要手动切换 visibility -->
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:id="@+id/errorContainer"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:gravity="center"
    android:orientation="vertical"
    android:padding="24dp"
    android:visibility="gone">

    <TextView
        android:id="@+id/tvError"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:textAppearance="?attr/textAppearanceBodyLarge" />

    <Button
        android:id="@+id/btnRetry"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:layout_marginTop="16dp"
        android:text="重试" />
</LinearLayout>

// 文件路径：docs/samples/ch09/FeedErrorView.kt
package com.techfeed.feature.feed.ui

import android.content.Context
import android.util.AttributeSet
import android.view.LayoutInflater
import android.widget.LinearLayout
import androidx.core.view.isVisible
import com.techfeed.feature.feed.databinding.ViewFeedErrorBinding

/** 自定义 View 封装错误态，让 XML 体系也能做到"状态驱动 UI" */
class FeedErrorView @JvmOverloads constructor(
    context: Context,
    attrs: AttributeSet? = null,
) : LinearLayout(context, attrs) {

    private val binding = ViewFeedErrorBinding.inflate(LayoutInflater.from(context), this, true)

    fun render(message: String?, onRetry: () -> Unit) {
        isVisible = message != null            // 状态驱动：有错误才显示，与 Compose 思路一致
        binding.tvError.text = message.orEmpty()
        binding.btnRetry.setOnClickListener { onRetry() }
    }
}

2.10 测试：MockWebServer 验证接口层

// 文件路径：docs/samples/ch09/FeedRemoteDataSourceTest.kt
package com.techfeed.core.network

import com.google.common.truth.Truth.assertThat
import com.techfeed.core.model.AppError
import com.techfeed.core.network.api.FeedApi
import com.techfeed.core.network.api.TechFeedApi
import com.techfeed.core.network.datasource.FeedRemoteDataSource
import com.techfeed.core.network.model.toDomain
import kotlinx.coroutines.test.runTest
import mockwebserver3.MockResponse
import mockwebserver3.MockWebServer
import org.junit.After
import org.junit.Before
import org.junit.Test
import retrofit2.Retrofit
import retrofit2.converter.kotlinx.serialization.asConverterFactory
import retrofit2.create

class FeedRemoteDataSourceTest {

    private lateinit var server: MockWebServer
    private lateinit var dataSource: FeedRemoteDataSource

    @Before
    fun setUp() {
        server = MockWebServer()
        server.start()
        val retrofit = Retrofit.Builder()
            .baseUrl(server.url("/"))         // 指向本地 Mock 服务
            .addConverterFactory(AppJson.asConverterFactory("application/json".toMediaType()))
            .build()
        // 用一个只实现了 FeedApi 的假聚合入口，隔离被测目标
        val api = TechFeedApi(retrofit)
        dataSource = FeedRemoteDataSource(api)
    }

    @After
    fun tearDown() {
        server.close()        // ⚠️ 不关会端口泄漏，CI 上表现为用例互相干扰
    }

    @Test
    fun `正常响应映射为 Success`() = runTest {
        server.enqueue(
            MockResponse(code = 200, body = """
                {"code":0,"message":"ok","data":{"items":[{"id":"a-1","title":"标题","published_at":1700000000}]}}
            """.trimIndent()),
        )

        val result = dataSource.getArticles(page = 1)

        assertThat(result).isInstanceOf(Result.Success::class.java)
        assertThat((result as Result.Success).data.first().title).isEqualTo("标题")

        // 顺带断言请求：验证 Query 参数真的发出去了
        val recorded = server.takeRequest()
        assertThat(recorded.path).contains("page=1")
    }

    @Test
    fun `未知字段不导致崩溃`() = runTest {
        server.enqueue(
            MockResponse(code = 200, body = """
                {"code":0,"data":{"items":[{"id":"a-1","title":"t","future_field":{}}]}}
            """.trimIndent()),
        )

        val result = dataSource.getArticles(page = 1)
        assertThat(result).isInstanceOf(Result.Success::class.java)   // ignoreUnknownKeys 生效
    }

    @Test
    fun `业务错误码映射为 AppError`() = runTest {
        server.enqueue(
            MockResponse(code = 200, body = """{"code":1001,"message":"token expired"}"""),
        )

        val result = dataSource.getArticles(page = 1)

        assertThat(result).isInstanceOf(Result.Failure::class.java)
        assertThat((result as Result.Failure).error).isInstanceOf(AppError.Auth::class.java)
    }
}

[!TIP] 想要覆盖"超时""连接失败"这类场景，用 MockResponse 的 socket 策略： MockResponse().apply { socketPolicy = SocketPolicy.NoResponse }，配合把 OkHttpClient 的超时调短， 就能在本地稳定复现线上最难复现的网络异常。

2.11 为第 19 章预留：证书绑定接入点

// 文件路径：docs/samples/ch09/PinningConfig.kt
package com.techfeed.core.network

/**
 * 证书绑定配置：本章只定义占位，实现与密钥轮换策略见第 19 章。
 * 提前定义接口是为了让 OkHttpClient 的构造点从一开始就预留 pinning 位置，
 * 避免第 19 章接入时改遍所有构造代码。
 */
interface PinningConfig {
    /** 返回 null 表示不启用绑定（如 debug 包 / Mock 环境） */
    fun pinner(): Any?
}

三、常见坑 ⚠️

四、调试技巧

1. Network Inspector（首选）：App Inspection → Network Inspector 能看到每个请求的 URL、Header、Body 与时序，不需要改代码。
2. adb 侧验证网络可达性：

   # 在设备上测 DNS 与连通（设备网络与电脑网络可能不同）
   adb shell ping -c 3 api.techfeed.dev
   adb shell curl -sS -o /dev/null -w "%{http_code}" https://api.techfeed.dev/v1/articles?page=1
   # 查看 App 建立的连接
   adb shell dumpsys connectivity | grep -i "techfeed"
   

3. OkHttp 事件监听：实现 EventListener 统计 DNS、TLS 握手、首字节耗时，能定位"慢到底是慢在哪一段"。

   class TimingEventListener : EventListener() {
       override fun dnsStart(call: Call, domainName: String) { /* 打时间戳 */ }
       override fun responseHeadersStart(call: Call) { /* 计算 TTFB */ }
   }
   

4. MockWebServer 复现线上问题：把线上拿到的响应体原样 enqueue，可以在本地 100% 复现解析崩溃。
5. Charles / mitmproxy 抓 HTTPS：Android 7+ 默认不信任用户 CA，需要在 res/xml/network_security_config.xml 中 为 debug 变体配置 <debug-overrides>（详见第 19 章）。抓包失败时先确认这一条。
6. 日志分级：HttpLoggingInterceptor.Level.BODY 会把图片/大列表刷爆 Logcat，调试时先用 HEADERS，必要时才升到 BODY。
7. 对比验证：用 curl 请求同一接口，如果 curl 也失败，问题在服务端或网络，别在客户端浪费时间。

五、最佳实践

1. 拦截器顺序有语义：Error → Retry → Auth → Logging。错误处理在最外层才能捕获内层抛出的异常；日志在最内层才能看到最终发出的请求。
2. 鉴权与业务解耦：:core:network 只依赖 TokenProvider 接口，实现放在 :core:datastore（第 10 章），避免网络层反向依赖存储层实现。
3. DTO 与领域模型分离：ArticleDto 只在网络层可见，出 :core:network 之前必须转成 Article。后端改字段名时改动被关在一个文件里。
4. ignoreUnknownKeys 必开：这是成本最低的线上稳定性保险。
5. 错误统一在拦截器层翻译：业务代码里不该出现 catch (IOException)，只该看到 Result.Failure(AppError)。
6. 重试只对幂等请求：并在重试中加指数退避 + 抖动，避免惊群。
7. 日志只进 debug：用 debugImplementation 而非 if (BuildConfig.DEBUG)，同时给 Authorization 等头设 REDACTED。
8. 测试用 MockWebServer 而非真实环境：真实后端不稳定会让 CI 变红，且无法覆盖错误分支。
9. 单例 OkHttpClient：连接池、TLS 会话复用都在 client 上，每次新建会显著变慢并耗尽 socket。

六、本章小结

1. 职责分层：Retrofit 描述请求、OkHttp 负责传输、kotlinx.serialization 负责序列化、Repository 负责语义，四层不能混。
2. 拦截器是 OkHttp 的灵魂：应用拦截器每次调用一次、可短路、缓存命中也执行；网络拦截器只在真实网络发生时执行、可能多次。鉴权用前者，原始流量统计用后者。
3. 序列化要宽容：ignoreUnknownKeys + coerceInputValues + @SerialName，让后端演进不摧毁客户端。
4. 错误要结构化：ErrorInterceptor 把 HTTP 异常翻译成 AppError，safeApiCall 把信封翻译成 Result<T>，UI 只消费 Result。
5. 可测试性来自边界：MockWebServer 让接口层测试不依赖真实后端，也能覆盖超时、畸形 JSON、业务错误码这些最难复现的分支。

上一章回顾：第 03 章给出的 UiState + Event 双通道，正是本章 Result<T> 在 UI 层的落点。 下一章：网络拿到的数据需要落地——进入 第 10 章 数据存储：Room、DataStore 与文件存储， 学习如何把 Article 存进本地数据库，并实现"离线也能看"的单一数据源。

七、动手练习

基础题

1. 给 FeedApi 增加一个 @POST("v1/articles/{id}/favorite") 接口（无请求体），用 MockWebServer 验证请求方法与路径正确。
2. 写一个 HeaderInterceptor，统一注入 X-App-Version、X-Device-Id 与 Accept-Language，并用 server.takeRequest() 断言头已发出。
3. 定义 UserDto 并配置 AppJson，让它能正确解析 {"user_id":"u1","nick_name":"张三","vip_level":3}，且忽略多余的 extra 字段。

进阶题 4. 实现 OfflineCacheInterceptor：有网时缓存 60 秒，无网时允许读取 3 天内的过期缓存。用 MockWebServer 验证"第二次请求未发出网络调用"（提示：server.requestCount == 1）。 5. 给 RetryInterceptor 增加"只对幂等请求重试"的判断（通过自定义请求头标记），并写一个测试证明 POST 请求不会被重试。 6. 用 EventListener 统计一次请求的 DNS / 连接 / TLS / 首字节耗时，输出到 Logcat，对比首次与第二次请求（验证连接复用）。

思考题 7. 为什么 Authenticator 里必须限制重试次数？如果刷新 Token 的接口本身返回 401，不加限制会发生什么？ 8. 缓存应该放在 OkHttp 层还是 Room 层？两者分别解决什么问题？如果一个接口既要"秒开"又要"可编辑"，你会怎么分层？ 9. 拦截器里出现了 Article 这类领域模型，为什么是设计问题？它会带来哪些具体的维护成本？

📄 第 10 章 数据存储：Room、DataStore 与文件存储 10-persistence-room-datastore.md✓ 标记已学

阶段：进阶 ｜ 预计阅读 60 min ｜ 代码落地模块：:core:database、:core:datastore 前置：第 01 章 Kotlin 速成与协程预热 ｜ 第 09 章 网络请求 相关章节：第 11 章 协程与 Flow ｜ 第 14 章 分层架构与 MVI ｜ 第 19 章 安全加固 ｜ 第 25 章 登录鉴权与离线缓存

学习目标

• [ ] 能按"数据形态 + 访问频率 + 安全等级"三要素选型，说清 SharedPreferences / DataStore / Room / 文件各自的适用边界。
• [ ] 掌握 Room 三件套（Entity / Dao / Database）的写法，能用 Flow 返回可观察查询并用 @Transaction 保证一致性。
• [ ] 理解数据库迁移的三种策略（自动迁移、手动 Migration、destructiveMigration）及其代价，会做预填充数据库。
• [ ] 掌握 DataStore 的 Preferences 与 Proto 两种形态，能从 SharedPreferences 平滑迁移。
• [ ] 能正确选择内部存储 / 外部存储 / MediaStore，并知道敏感数据该用什么方式加密落盘。

一、核心概念

1.1 存储方案怎么选

先别急着写代码，用这张表选型：

[!IMPORTANT] SharedPreferences 已被官方标记为弃用，新代码一律用 DataStore。它的问题不是"慢"，而是： 同步 I/O 可能在主线程造成卡顿与 ANR、apply() 的异步提交不保证落盘时机、没有事务、没有类型安全、没有错误信号。

1.2 Room 在 SQLite 之上加了什么

flowchart TB
    A["Entity<br/>@Entity 数据表定义"] --> D["RoomDatabase<br/>编译期生成实现"]
    B["Dao<br/>@Dao SQL 接口"] --> D
    C["TypeConverter<br/>复杂类型 ↔ 基础类型"] --> D
    D --> E["SQLiteOpenHelper<br/>建表 / 版本管理"]
    E --> F["SQLite 文件<br/>/data/data/pkg/databases/"]
    D -->|"KSP 编译期校验 SQL"| G["编译期报错<br/>列名写错当场发现"]

Room 的三个硬收益：

1. 编译期校验 SQL：列名、表名写错会编译失败，而不是运行时崩。
2. 直接返回 Flow / suspend：查询结果变化自动推送，无需手动 ContentObserver。
3. 迁移可验证：导出 schema JSON，让版本演进可追溯。

1.3 Room 三件套的职责

1.4 Flow 返回与事务

Dao 返回 Flow<List<T>> 时，Room 会在事务内监听相关表的变化，表一变就重新查询并推送。这意味着：

• 查询方法不需要 suspend（Flow 的收集本身就是异步的）。
• 不要在 Flow 查询里做耗时计算——它在事务线程上执行，会阻塞其他写入。
• 一次性的"读—改—写"必须用 @Transaction，否则中间状态可能被其他线程读到。

1.5 迁移策略的三条路

[!WARNING] fallbackToDestructiveMigration() 出现在 release 代码里应视为 P0 事故隐患。 如果某些表的数据可以丢（纯缓存），至少用 fallbackToDestructiveMigrationOnDowngrade() 或按表精确控制。

1.6 DataStore 的两种形态

共同优点：基于协程与 Flow 的异步 API、原子读写（事务）、可读的错误信号（IOException 而非静默失败）。

1.7 文件存储的三块地

[!NOTE] Android 10 起强制分区存储（Scoped Storage）：不能再直接用 File API 写公共目录， 必须通过 MediaStore 或系统文件选择器（SAF）。想临时兼容可加 android:requestLegacyExternalStorage， 但 targetSdk 提高后失效，不建议依赖。

1.8 加密存储简述

• EncryptedFile（androidx.security:security-crypto）：基于流式加密（AES256-GCM），适合大文件。
• EncryptedSharedPreferences：security-crypto 库处于维护状态，但仍是官方对 Android Keystore 的最简可靠封装，本教程第 19/25 章沿用它存 token；迁移到 Tink 或 DataStore + Keystore 自行加密属进阶练习。
• 密钥一律存放于 Android Keystore，由系统级安全硬件保护，App 无法导出私钥（第 19 章展开）。

二、示例代码

2.1 模块配置与 schema 导出

// 文件路径：sample/core/database/build.gradle.kts
plugins {
    alias(libs.plugins.techfeed.android.library)
    alias(libs.plugins.kotlin.serialization)
    alias(libs.plugins.room)      // androidx.room 插件：配置 schema 目录
    alias(libs.plugins.ksp)
    alias(libs.plugins.hilt)
}

room {
    // ⚠️ 一定要导出 schema：它是迁移可验证、可回溯的唯一依据，需提交到版本库
    schemaDirectory("$projectDir/schemas")
}

dependencies {
    api(projects.core.model)
    implementation(libs.bundles.room)      // room-runtime + room-ktx
    ksp(libs.androidx.room.compiler)       // KSP 代替 kapt，编译更快
    implementation(libs.hilt.android)
    ksp(libs.hilt.compiler)
    testImplementation(libs.bundles.testing.unit)
}

2.2 Entity：表结构定义

// 文件路径：sample/core/database/src/main/java/com/techfeed/core/database/entity/ArticleEntity.kt（教学简化版，sample 实际实现见同路径文件）
package com.techfeed.core.database.entity

import androidx.room.ColumnInfo
import androidx.room.Entity
import androidx.room.Index
import androidx.room.PrimaryKey
import com.techfeed.core.model.Article
import com.techfeed.core.model.Author

@Entity(
    tableName = "articles",
    // 索引：列表按时间倒序查询，必须建索引，否则数据量大时全表扫描
    indices = [Index(value = ["published_at"]), Index(value = ["is_favorite"])],
)
data class ArticleEntity(
    @PrimaryKey @ColumnInfo(name = "id") val id: String,
    @ColumnInfo(name = "title") val title: String,
    @ColumnInfo(name = "summary") val summary: String,
    @ColumnInfo(name = "cover_url") val coverUrl: String?,
    @ColumnInfo(name = "author_id") val authorId: String,
    @ColumnInfo(name = "author_name") val authorName: String,
    @ColumnInfo(name = "author_avatar") val authorAvatar: String?,
    @ColumnInfo(name = "published_at") val publishedAt: Long,
    @ColumnInfo(name = "is_favorite") val isFavorite: Boolean = false,
    @ColumnInfo(name = "cached_at") val cachedAt: Long = System.currentTimeMillis(),
    // 分页需要：信息流是多页拼接的，保存页码才能按序还原
    @ColumnInfo(name = "page") val page: Int = 0,
)

fun ArticleEntity.toDomain(): Article = Article(
    id = id,
    title = title,
    summary = summary,
    coverUrl = coverUrl,
    author = Author(authorId, authorName, authorAvatar),
    publishedAt = publishedAt,
    isFavorite = isFavorite,
)

fun Article.toEntity(page: Int = 0): ArticleEntity = ArticleEntity(
    id = id,
    title = title,
    summary = summary,
    coverUrl = coverUrl,
    authorId = author.id,
    authorName = author.name,
    authorAvatar = author.avatarUrl,
    publishedAt = publishedAt,
    isFavorite = isFavorite,
    page = page,
)

[!TIP] 这里是扁平化存储：把 Author 拆成三列而不是单独建表做外键关联。 缓存型数据追求"一次查询出列表"，扁平化比关联查询快得多。真正需要独立查询 Author 时才拆表。

2.3 Dao：Flow、事务与 Upsert

// 文件路径：sample/core/database/src/main/java/com/techfeed/core/database/dao/ArticleDao.kt（教学简化版，sample 实际实现见同路径文件）
package com.techfeed.core.database.dao

import androidx.room.Dao
import androidx.room.Insert
import androidx.room.OnConflictStrategy
import androidx.room.Query
import androidx.room.Transaction
import androidx.room.Upsert
import com.techfeed.core.database.entity.ArticleEntity
import kotlinx.coroutines.flow.Flow

@Dao
interface ArticleDao {

    /** 返回 Flow：表变化自动重新查询并推送。方法不必是 suspend。
     *  query 非空时在 DB 层按标题过滤（LIKE 大小写不敏感只对 ASCII，教学够用），
     *  比取全量到内存再 filter 省得多（第 17 章性能意识的落点） */
    @Query(
        "SELECT * FROM articles WHERE is_favorite = 0 " +
            "AND (:query IS NULL OR title LIKE '%' || :query || '%') " +
            "ORDER BY published_at DESC",
    )
    fun observeFeed(query: String?): Flow<List<ArticleEntity>>

    @Query("SELECT * FROM articles WHERE is_favorite = 1 ORDER BY published_at DESC")
    fun observeFavorites(): Flow<List<ArticleEntity>>

    @Query("SELECT * FROM articles WHERE id = :id")
    fun observeById(id: String): Flow<ArticleEntity?>

    /** 一次性查询：需要 suspend（首次访问会触发 IO） */
    @Query("SELECT COUNT(*) FROM articles")
    suspend fun count(): Int

    /**
     * Upsert：存在则更新、不存在则插入。
     * 用于"网络数据落地"——后端可能重复下发同一篇文章。
     */
    @Upsert
    suspend fun upsertAll(items: List<ArticleEntity>)

    @Insert(onConflict = OnConflictStrategy.IGNORE)
    suspend fun insertAllIgnoring(items: List<ArticleEntity>)

    @Query("UPDATE articles SET is_favorite = :favorite WHERE id = :id")
    suspend fun setFavorite(id: String, favorite: Boolean)

    /** 只保留最近 N 页，防止缓存无限膨胀（配合 WorkManager 定期清理，见第 13 章） */
    @Query("DELETE FROM articles WHERE page < :minPage AND is_favorite = 0")
    suspend fun deleteStale(minPage: Int): Int

    /**
     * @Transaction 保证"清空 + 插入"是原子的：
     * 否则中途查询会看到空列表，UI 可能出现闪烁的白屏。
     */
    @Transaction
    suspend fun replacePage(page: Int, items: List<ArticleEntity>) {
        deleteByPage(page)
        upsertAll(items)
    }

    @Query("DELETE FROM articles WHERE page = :page AND is_favorite = 0")
    suspend fun deleteByPage(page: Int)
}

2.4 Database：版本、迁移与预填充

// 文件路径：sample/core/database/src/main/java/com/techfeed/core/database/TechFeedDatabase.kt（教学简化版，sample 实际实现见同路径文件）
package com.techfeed.core.database

import androidx.room.AutoMigration
import androidx.room.Database
import androidx.room.RoomDatabase
import androidx.room.TypeConverters
import com.techfeed.core.database.dao.ArticleDao
import com.techfeed.core.database.dao.DraftDao
import com.techfeed.core.database.entity.ArticleEntity
import com.techfeed.core.database.entity.DraftEntity

@Database(
    entities = [ArticleEntity::class, DraftEntity::class],
    version = 3,
    // 自动迁移：Room 能推断的简单变更（v2 加列、v3 加索引）
    autoMigrations = [
        AutoMigration(from = 2, to = 3),
    ],
    exportSchema = true,     // 必须 true，schema JSON 是迁移审计的依据
)
@TypeConverters(Converters::class)
abstract class TechFeedDatabase : RoomDatabase() {
    abstract fun articleDao(): ArticleDao
    abstract fun draftDao(): DraftDao

    companion object {
        const val NAME = "techfeed.db"
    }
}

// 文件路径：docs/samples/ch10/Converters.kt
package com.techfeed.core.database

import androidx.room.TypeConverter
import kotlinx.serialization.encodeToString
import kotlinx.serialization.decodeFromString
import kotlinx.serialization.json.Json

/** Room 只认基础类型，List 这类复杂字段必须做类型转换 */
class Converters {
    @TypeConverter
    fun fromStringList(value: List<String>?): String? =
        value?.let { Json.encodeToString(it) }

    @TypeConverter
    fun toStringList(value: String?): List<String>? =
        value?.let { Json.decodeFromString(it) }
}

// 文件路径：sample/core/database/src/main/java/com/techfeed/core/database/di/DatabaseModule.kt（教学简化版，sample 实际实现见同路径文件）
package com.techfeed.core.database.di

import android.content.Context
import androidx.room.Room
import androidx.sqlite.db.SupportSQLiteDatabase
import com.techfeed.core.database.TechFeedDatabase
import com.techfeed.core.database.dao.ArticleDao
import dagger.Module
import dagger.Provides
import dagger.hilt.InstallIn
import dagger.hilt.android.qualifiers.ApplicationContext
import dagger.hilt.components.SingletonComponent
import javax.inject.Singleton

@Module
@InstallIn(SingletonComponent::class)
object DatabaseModule {

    @Provides
    @Singleton
    fun provideDatabase(@ApplicationContext context: Context): TechFeedDatabase =
        Room.databaseBuilder(context, TechFeedDatabase::class.java, TechFeedDatabase.NAME)
            // v1 → v2 无法自动推断（列重命名），必须手写 SQL
            .addMigrations(MIGRATION_1_2)
            // 预填充：把 assets 中打包好的初始数据作为首次创建的数据库
            // .createFromAsset("database/prepopulated.db")
            // ⚠️ 下面这行仅供开发期；release 出现即为数据丢失风险
            // .fallbackToDestructiveMigration()
            .addCallback(object : RoomDatabase.Callback() {
                override fun onCreate(db: SupportSQLiteDatabase) {
                    // 建库时的初始化钩子：也可以在这里插入预置数据
                    db.execSQL("CREATE INDEX IF NOT EXISTS idx_articles_page ON articles(page)")
                }
            })
            .build()

    @Provides
    fun provideArticleDao(db: TechFeedDatabase): ArticleDao = db.articleDao()

    /** 手动迁移：一次写好，永不删除（用户可能停留在任何旧版本） */
    private val MIGRATION_1_2 = object : androidx.room.migration.Migration(1, 2) {
        override fun migrate(db: androidx.sqlite.db.SupportSQLiteDatabase) {
            db.execSQL("ALTER TABLE articles ADD COLUMN is_favorite INTEGER NOT NULL DEFAULT 0")
            db.execSQL("ALTER TABLE articles ADD COLUMN cached_at INTEGER NOT NULL DEFAULT 0")
        }
    }
}

[!WARNING] 迁移对象永远不要删。用户可能半年没更新，从 v1 直接升到 v5，Room 会依次执行 1→2、2→3…… 少任何一段，那批用户就会崩（或触发 destructive 丢数据）。

2.5 Repository：单一数据源（SSOT）

这是第 09 章网络能力与本章存储能力的结合点，也是第 14 章分层架构的雏形：

// 文件路径：docs/samples/ch10/OfflineFirstFeedRepository.kt
package com.techfeed.core.database.repository

import com.techfeed.core.database.dao.ArticleDao
import com.techfeed.core.database.entity.toDomain
import com.techfeed.core.database.entity.toEntity
import com.techfeed.core.model.Article
import com.techfeed.core.model.Result
import com.techfeed.core.network.datasource.FeedRemoteDataSource
import kotlinx.coroutines.flow.Flow
import kotlinx.coroutines.flow.map
import javax.inject.Inject
import javax.inject.Singleton

/**
 * 离线优先（Offline First）仓库：
 * - 对外只暴露 Flow，UI 永远读本地，天然"秒开"
 * - 网络只负责刷新本地，不直接给 UI
 * 这是"单一数据源（Single Source of Truth, SSOT）"的标准实现。
 */
@Singleton
class OfflineFirstFeedRepository @Inject constructor(
    private val remote: FeedRemoteDataSource,
    private val dao: ArticleDao,
) {
    fun observeFeed(query: String? = null): Flow<List<Article>> =
        dao.observeFeed(query).map { list -> list.map { it.toDomain() } }   // 映射在 Flow 内，保持流式

    /** 刷新：先写库，UI 通过 Flow 自动收到新数据，不需要返回值 */
    suspend fun refresh(page: Int): Result<Unit> = when (val result = remote.getArticles(page)) {
        is Result.Success -> {
            dao.replacePage(page, result.data.map { it.toEntity(page) })
            Result.Success(Unit)
        }
        // ⚠️ 失败不覆盖本地：旧的缓存仍然可用，这正是离线优先的价值
        is Result.Failure -> Result.Failure(result.error)
        Result.Loading -> Result.Loading
    }
}

2.6 DataStore Preferences

// 文件路径：sample/core/datastore/src/main/java/com/techfeed/core/datastore/UserPreferences.kt
package com.techfeed.core.datastore

import android.content.Context
import androidx.datastore.core.DataStore
import androidx.datastore.preferences.core.Preferences
import androidx.datastore.preferences.core.booleanPreferencesKey
import androidx.datastore.preferences.core.edit
import androidx.datastore.preferences.core.intPreferencesKey
import androidx.datastore.preferences.core.stringPreferencesKey
import androidx.datastore.preferences.preferencesDataStore
import dagger.hilt.android.qualifiers.ApplicationContext
import kotlinx.coroutines.flow.Flow
import kotlinx.coroutines.flow.map
import javax.inject.Inject
import javax.inject.Singleton

/**
 * preferencesDataStore 委托：name 唯一，重复定义同名 DataStore 会抛
 * IllegalStateException("There are multiple DataStores active for the same file")。
 * ⚠️ 因此它必须是单例（放顶层或由 Hilt 单例提供），绝不能每次 new。
 */
private val Context.userDataStore: DataStore<Preferences> by preferencesDataStore(
    name = "user_preferences",
    // 从 SharedPreferences 迁移：只执行一次，读完后旧文件会被删除
    produceMigrations = { context ->
        listOf(androidx.datastore.preferences.SharedPreferencesMigration(context, "user_sp"))
    },
)

data class AppSettings(
    val darkMode: Boolean = false,
    val fontSizeSp: Int = 16,
    val lastChannel: String = "recommend",
)

@Singleton
class UserPreferencesDataSource @Inject constructor(
    @ApplicationContext private val context: Context,
) {
    val settings: Flow<AppSettings> = context.userDataStore.data.map { prefs ->
        AppSettings(
            darkMode = prefs[KEY_DARK_MODE] ?: false,
            fontSizeSp = prefs[KEY_FONT_SIZE] ?: 16,
            lastChannel = prefs[KEY_CHANNEL] ?: "recommend",
        )
    }

    /** edit 是原子的：要么全写入，要么全不写 */
    suspend fun setDarkMode(enabled: Boolean) {
        context.userDataStore.edit { prefs -> prefs[KEY_DARK_MODE] = enabled }
    }

    suspend fun setFontSize(sp: Int) {
        context.userDataStore.edit { prefs -> prefs[KEY_FONT_SIZE] = sp.coerceIn(12, 24) }
    }

    private companion object {
        val KEY_DARK_MODE = booleanPreferencesKey("dark_mode")
        val KEY_FONT_SIZE = intPreferencesKey("font_size_sp")
        val KEY_CHANNEL = stringPreferencesKey("last_channel")
    }
}

[!WARNING] dataStore.data 抛出的 IOException 会让 Flow 终止。生产代码应加一层兜底：

.catch { if (it is IOException) emit(emptyPreferences()) else throw it }

否则一次磁盘 IO 失败会让设置页永久空白。

2.7 Proto DataStore：有 schema 的配置

// 文件路径：docs/samples/ch10/SettingsSerializer.kt
package com.techfeed.core.datastore

import androidx.datastore.core.Serializer
import kotlinx.serialization.Serializable
import kotlinx.serialization.encodeToString
import kotlinx.serialization.decodeFromString
import kotlinx.serialization.json.Json
import java.io.InputStream
import java.io.OutputStream

/** Proto DataStore 的模型（示例用 kotlinx.serialization 承载，工程里也可用 protobuf-lite） */
@Serializable
data class SettingsProto(
    val darkMode: Boolean = false,
    val fontSizeSp: Int = 16,
    val autoPlayVideo: Boolean = true,
)

object SettingsSerializer : Serializer<SettingsProto> {
    override val defaultValue: SettingsProto = SettingsProto()

    override suspend fun readFrom(input: InputStream): SettingsProto = try {
        Json.decodeFromString(input.readBytes().decodeToString())
    } catch (e: Exception) {
        // 解析失败返回默认值，避免配置损坏导致 App 打不开
        defaultValue
    }

    override suspend fun writeTo(t: SettingsProto, output: OutputStream) {
        output.write(Json.encodeToString(t).toByteArray())
    }
}

// 文件路径：docs/samples/ch10/DataStoreModule.kt
package com.techfeed.core.datastore.di

import android.content.Context
import androidx.datastore.core.DataStore
import androidx.datastore.dataStore
import com.techfeed.core.datastore.SettingsProto
import com.techfeed.core.datastore.SettingsSerializer
import dagger.Module
import dagger.Provides
import dagger.hilt.InstallIn
import dagger.hilt.android.qualifiers.ApplicationContext
import dagger.hilt.components.SingletonComponent
import javax.inject.Singleton

private val Context.settingsDataStore: DataStore<SettingsProto> by dataStore(
    fileName = "settings.pb",
    serializer = SettingsSerializer,
)

@Module
@InstallIn(SingletonComponent::class)
object DataStoreModule {
    @Provides
    @Singleton
    fun provideSettingsDataStore(@ApplicationContext context: Context): DataStore<SettingsProto> =
        context.settingsDataStore
}

2.8 文件存储：内部、缓存与清理

// 文件路径：docs/samples/ch10/FileStorage.kt
package com.techfeed.core.datastore.file

import android.content.Context
import dagger.hilt.android.qualifiers.ApplicationContext
import java.io.File
import javax.inject.Inject
import javax.inject.Singleton

@Singleton
class AppFileStorage @Inject constructor(
    @ApplicationContext private val context: Context,
) {
    /** 内部存储：私有、无需权限、随卸载删除 —— 放用户草稿、离线包 */
    fun draftsDir(): File = File(context.filesDir, "drafts").apply { mkdirs() }

    /** 缓存目录：系统内存不足时可能自动清理，必须容忍文件不存在 */
    fun imageCacheDir(): File = File(context.cacheDir, "images").apply { mkdirs() }

    /** 外部私有目录：放下载的大文件，避免撑爆内部存储 */
    fun downloadsDir(): File? = context.getExternalFilesDir(android.os.Environment.DIRECTORY_DOWNLOADS)

    /**
     * 缓存清理：只删超过 maxAgeMs 的文件。
     * ⚠️ 不要无脑 deleteRecursively，会把正在使用的文件删掉。
     */
    fun evictCache(maxAgeMs: Long = DEFAULT_MAX_AGE_MS): Long {
        var freed = 0L
        val now = System.currentTimeMillis()
        imageCacheDir().listFiles()?.forEach { file ->
            if (now - file.lastModified() > maxAgeMs) {
                freed += file.length()
                file.delete()
            }
        }
        return freed
    }

    /** 查询缓存大小，用于设置页展示"清理缓存"入口 */
    fun cacheSizeBytes(): Long =
        imageCacheDir().walkTopDown().filter { it.isFile }.sumOf { it.length() }

    private companion object {
        const val DEFAULT_MAX_AGE_MS = 7L * 24 * 60 * 60 * 1000   // 7 天
    }
}

2.9 MediaStore：保存图片到公共相册

// 文件路径：docs/samples/ch10/MediaStoreSaver.kt
package com.techfeed.core.datastore.file

import android.content.ContentValues
import android.content.Context
import android.os.Build
import android.provider.MediaStore
import dagger.hilt.android.qualifiers.ApplicationContext
import java.io.OutputStream
import javax.inject.Inject

/**
 * Android 10+ 分区存储：公共目录只能通过 MediaStore 写入，不能再直接 new File("/sdcard/DCIM/...")。
 * Android 10 及以上用 IS_PENDING 占位，写完置 0 后其他应用才可见。
 */
class MediaStoreSaver @Inject constructor(
    @ApplicationContext private val context: Context,
) {
    fun saveImage(displayName: String, mimeType: String = "image/jpeg"): OutputStream? {
        val values = ContentValues().apply {
            put(MediaStore.Images.Media.DISPLAY_NAME, displayName)
            put(MediaStore.Images.Media.MIME_TYPE, mimeType)
            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
                put(MediaStore.Images.Media.RELATIVE_PATH, "Pictures/TechFeed")
                put(MediaStore.Images.Media.IS_PENDING, 1)   // 写入期间对外不可见
            }
        }
        val resolver = context.contentResolver
        val uri = resolver.insert(MediaStore.Images.Media.EXTERNAL_CONTENT_URI, values) ?: return null
        val stream = resolver.openOutputStream(uri) ?: return null
        return if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
            object : java.io.FilterOutputStream(stream) {
                override fun close() {
                    super.close()
                    values.clear()
                    values.put(MediaStore.Images.Media.IS_PENDING, 0)   // 写完公开
                    resolver.update(uri, values, null, null)
                }
            }
        } else {
            stream
        }
    }
}

2.10 加密存储：EncryptedFile 与 Token 落地

// 文件路径：sample/core/datastore/src/main/java/com/techfeed/core/datastore/secure/SecureTokenStorage.kt
package com.techfeed.core.datastore.secure

import android.content.Context
import androidx.security.crypto.EncryptedFile
import androidx.security.crypto.MasterKey
import dagger.hilt.android.qualifiers.ApplicationContext
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.withContext
import javax.inject.Inject
import javax.inject.Singleton

/**
 * Token 的落地方案：EncryptedFile + Android Keystore。
 * 为什么不用 DataStore 明文存？——Root/备份导出场景下明文 Token 等于账号被盗。
 * Keystore 的密钥不可导出，且可配置需要生物识别才能使用（第 19 章）。
 */
@Singleton
class SecureTokenStorage @Inject constructor(
    @ApplicationContext private val context: Context,
) {
    private val masterKey by lazy {
        MasterKey.Builder(context)
            .setKeyScheme(MasterKey.KeyScheme.AES256_GCM)
            .build()
    }

    private fun encryptedFile() = EncryptedFile.Builder(
        context,
        java.io.File(context.filesDir, "token.enc"),
        masterKey,
        EncryptedFile.FileEncryptionScheme.AES256_GCM_HKDF_4KB,
    ).build()

    suspend fun save(token: String) = withContext(Dispatchers.IO) {
        encryptedFile().openFileOutput().use { it.write(token.toByteArray()) }
    }

    suspend fun read(): String? = withContext(Dispatchers.IO) {
        runCatching { encryptedFile().openFileInput().use { it.readBytes().decodeToString() } }
            .getOrNull()   // 文件不存在或密钥失效时返回 null，交由上层走重新登录
    }

    suspend fun clear() = withContext(Dispatchers.IO) {
        java.io.File(context.filesDir, "token.enc").delete()
    }
}

2.11 UI 双体系：收藏列表

// 文件路径：sample/feature/profile/src/main/java/com/techfeed/feature/profile/ui/FavoriteListScreen.kt
package com.techfeed.feature.profile.ui

import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.lazy.LazyColumn
import androidx.compose.foundation.lazy.items
import androidx.compose.material3.ListItem
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.ui.Modifier
import androidx.hilt.navigation.compose.hiltViewModel
import androidx.lifecycle.compose.collectAsStateWithLifecycle
import com.techfeed.core.model.Article

/** Compose 版：collectAsStateWithLifecycle 让收集随生命周期自动启停（第 11 章） */
@Composable
fun FavoriteListScreen(
    modifier: Modifier = Modifier,
    viewModel: FavoriteViewModel = hiltViewModel(),
) {
    val favorites by viewModel.favorites.collectAsStateWithLifecycle()
    LazyColumn(modifier = modifier.fillMaxSize()) {
        // key 必填：否则数据变化时的动画与状态会错位
        items(items = favorites, key = { it.id }) { article ->
            ListItem(
                headlineContent = { Text(article.title) },
                supportingContent = { Text(article.summary) },
            )
        }
    }
}

// 文件路径：docs/samples/ch10/FavoriteFragment.kt
package com.techfeed.feature.profile.ui

import android.os.Bundle
import android.view.LayoutInflater
import android.view.View
import android.view.ViewGroup
import androidx.fragment.app.Fragment
import androidx.fragment.app.viewModels
import androidx.lifecycle.Lifecycle
import androidx.lifecycle.lifecycleScope
import androidx.lifecycle.repeatOnLifecycle
import androidx.recyclerview.widget.LinearLayoutManager
import com.techfeed.feature.profile.databinding.FragmentFavoriteBinding
import dagger.hilt.android.AndroidEntryPoint
import kotlinx.coroutines.launch

/** View 版：RecyclerView + Adapter，数据同样来自 Room 的 Flow */
@AndroidEntryPoint
class FavoriteFragment : Fragment() {

    private var _binding: FragmentFavoriteBinding? = null
    private val binding get() = requireNotNull(_binding)

    private val viewModel: FavoriteViewModel by viewModels()
    private val adapter = FavoriteAdapter()

    override fun onCreateView(inflater: LayoutInflater, container: ViewGroup?, saved: Bundle?): View {
        _binding = FragmentFavoriteBinding.inflate(inflater, container, false)
        return binding.root
    }

    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        super.onViewCreated(view, savedInstanceState)
        binding.recyclerView.layoutManager = LinearLayoutManager(requireContext())
        binding.recyclerView.adapter = adapter
        // 设置固定尺寸：列表项高度固定时能跳过测量，滚动更顺
        binding.recyclerView.setHasFixedSize(true)

        viewLifecycleOwner.lifecycleScope.launch {
            // repeatOnLifecycle：页面不可见时停止收集，避免后台仍然触发数据库查询
            viewLifecycleOwner.repeatOnLifecycle(Lifecycle.State.STARTED) {
                viewModel.favorites.collect { adapter.submitList(it) }
            }
        }
    }

    override fun onDestroyView() {
        binding.recyclerView.adapter = null   // 断开 Adapter 对视图的引用
        _binding = null                       // ⚠️ 必须置空，否则泄漏整棵视图树
        super.onDestroyView()
    }
}

2.12 测试：Room 与 DataStore

// 文件路径：docs/samples/ch10/ArticleDaoTest.kt
// ⚠️ 必须放 androidTest（仪器化测试）：ApplicationProvider 需要真实的应用 Context，
// src/test 的纯 JVM 环境里会抛 IllegalStateException。
package com.techfeed.core.database

import androidx.room.Room
import kotlinx.coroutines.flow.first
import kotlinx.coroutines.test.runTest
import androidx.test.core.app.ApplicationProvider
import org.junit.After
import org.junit.Before
import org.junit.Test

/**
 * 仪器化测试用 Room.inMemoryDatabaseBuilder + ApplicationProvider；
 * 若想在 JVM（src/test）上跑，可给 builder 加 `.setDriver(BundledSQLiteDriver())`
 * 并去掉对 ApplicationProvider 的依赖。
 */
class ArticleDaoTest {

    private lateinit var db: TechFeedDatabase

    @Before
    fun setUp() {
        db = Room.inMemoryDatabaseBuilder(
            ApplicationProvider.getApplicationContext(),
            TechFeedDatabase::class.java,
        ).build()
    }

    @After
    fun tearDown() {
        db.close()      // ⚠️ 不关会泄漏内存数据库实例
    }

    @Test
    fun `replacePage 后 Flow 推送新数据`() = runTest {
        val dao = db.articleDao()
        dao.replacePage(1, listOf(createEntity("a-1", page = 1)))

        val list = dao.observeFeed(null).first()
        assert(list.size == 1 && list[0].id == "a-1")
    }

    @Test
    fun `收藏的文章不会被清页删除`() = runTest {
        val dao = db.articleDao()
        dao.upsertAll(listOf(createEntity("a-1", page = 1), createEntity("a-2", page = 1)))
        dao.setFavorite("a-1", true)
        dao.deleteStale(minPage = 2)     // 只删 page < 2 且未收藏的

        val remaining = dao.observeFeed(null).first()
        assert(remaining.any { it.id == "a-1" })      // 收藏项保留
        assert(remaining.none { it.id == "a-2" })
    }

    private fun createEntity(id: String, page: Int) = com.techfeed.core.database.entity.ArticleEntity(
        id = id, title = "t-$id", summary = "", coverUrl = null,
        authorId = "au", authorName = "n", authorAvatar = null,
        publishedAt = System.currentTimeMillis(), page = page,
    )
}

// 旧写法：SharedPreferences —— 同步 IO、无事务、无错误信号
val sp = getSharedPreferences("user", MODE_PRIVATE)
sp.edit().putBoolean("dark_mode", true).apply()   // apply 异步但不保证何时落盘
val dark = sp.getBoolean("dark_mode", false)      // 主线程读盘，可能卡顿

// 旧写法：裸 SQLite —— SQL 拼错运行时才崩，变更需手动通知 UI
val db = writableDatabase
db.rawQuery("SELECT * FROM article WHERE id = ?", arrayOf(id)).use { cursor -> /* 手动解析 */ }
contentResolver.notifyChange(uri, null)   // 忘了这行 UI 永远不刷新

三、常见坑 ⚠️

四、调试技巧

1. Database Inspector（首选）：App Inspection → Database Inspector，可实时查看表内容、直接执行 SQL， 还能勾选"Live updates"观察 Flow 查询的实时变化。
2. 导出真实数据库文件：

   # debug 包可用 run-as 读取私有目录（release 包不行）
   adb exec-out run-as com.techfeed.app cat databases/techfeed.db > techfeed.db
   # 用 sqlite3 或 DB Browser 打开分析
   sqlite3 techfeed.db ".schema articles"
   

3. 校验 schema 演进：schemas/ 目录下每个版本一个 JSON，Code Review 时 diff 一下就能看出迁移是否安全。
4. DataStore 文件位置：/data/data/pkg/files/datastore/*.preferences_pb，同样用 run-as 导出排查配置没生效的问题。
5. 开启 Room 的查询日志：Room 会在编译期把 SQL 写入生成代码，可在 build/generated/ksp/... 下查看最终 SQL。
6. StrictMode 检测主线程磁盘读写（开发期必开，第 17 章）：

   StrictMode.setThreadPolicy(
       StrictMode.ThreadPolicy.Builder().detectDiskReads().detectDiskWrites().penaltyLog().build()
   )
   

7. 模拟"数据库被杀"：用 adb shell am kill 后重进 App，验证缓存与恢复逻辑（第 03 章）。

五、最佳实践

1. 一库一数据源：对外只暴露 Flow，UI 只读本地；网络只写本地，不直接喂 UI（SSOT）。
2. 缓存型数据扁平化：减少 join，用空间换查询速度；真正需要独立查询的实体才拆表。
3. exportSchema = true 并提交：迁移的事故几乎都源于"不知道线上到底是哪版 schema"。
4. 迁移对象永不删除：用户可能跨越多个版本升级。
5. release 禁用 destructiveMigration：缓存库可用 onDowngrade 精确降级，不要全局兜底。
6. DataStore 单例化：重复实例会直接抛异常；并给 data 加 catch (IOException) 兜底。
7. 缓存要有上限：配合 WorkManager 定期清理，并在设置页提供手动清理入口。
8. 敏感数据一律加密：Token、支付凭据走 EncryptedFile + Keystore，不进明文 DataStore。
9. 大文件不进数据库：数据库只存路径或 Uri，文件放文件系统 / MediaStore。
10. 查询映射切线程：Flow.map 后加 flowOn(Dispatchers.Default)，避免大列表解析阻塞。

六、本章小结

1. 选型三要素：数据形态（键值/结构/二进制）+ 访问频率 + 安全等级，决定用 DataStore、Room 还是文件系统。
2. Room 三件套：Entity 描述表、Dao 描述查询、Database 管理版本；返回 Flow 让数据变化自动驱动 UI，编译期校验 SQL 消灭运行时崩溃。
3. 迁移是长期负债：自动迁移处理简单变更，手写 Migration 处理复杂变更，destructiveMigration 是 release 禁区，迁移对象永不删除。
4. DataStore 取代 SharedPreferences：异步、事务、类型安全；Preferences 简单、Proto 有 schema；迁移用 SharedPreferencesMigration 一次性完成。
5. 文件与加密：内部/缓存/外部私有/MediaStore 各有边界；敏感数据用 EncryptedFile + Keystore，不进明文存储。

上一章衔接：第 09 章 网络请求 的 Result<List<Article>> 正是本章 dao.replacePage() 的输入， 两者组合成了离线优先仓库。 下一章：Flow 与 suspend 贯穿了本章全部代码，但你还需要系统理解它们——进入 第 11 章 异步处理：协程与 Flow，掌握结构化并发、异常处理与 StateFlow/SharedFlow 的取舍。

七、动手练习

基础题

1. 新建 DraftEntity（字段：id、articleId、content、updatedAt），写出对应 Dao，要求：按 updatedAt 倒序返回 Flow，并支持 Upsert。
2. 写一次手动迁移 MIGRATION_3_4（给 articles 加一列 read_progress INTEGER NOT NULL DEFAULT 0），并在 Database Inspector 中验证旧数据未丢失。
3. 用 DataStore Preferences 实现"记住上次选择的频道"，杀进程后重新进入 App 验证值被恢复。

进阶题 4. 实现 OfflineFirstFeedRepository 的刷新竞态处理：快速下拉刷新两次时，保证第一次的结果不会覆盖第二次（提示：Mutex 或请求序号，见第 11 章）。 5. 给 AppFileStorage 加一个"缓存超过 100MB 时按 LRU 淘汰"的策略，并写单元测试验证淘汰顺序正确。 6. 把 SecureTokenStorage 接入第 09 章的 TokenProvider 接口，实现"App 冷启动从加密文件恢复 Token"，并覆盖"文件损坏/密钥失效"的降级路径。

思考题 7. 为什么 Room 的 Flow 查询方法不需要 suspend，而一次性查询却需要？如果给 Flow 查询也加上 suspend 会发生什么？ 8. fallbackToDestructiveMigration() 在什么场景下是可以接受的？如果某个表是用户草稿（不可丢）、另一个表是缓存（可丢），你怎么设计迁移策略？ 9. 分区存储（Scoped Storage）限制 App 直接写公共目录，这对"导出日志到 SD 卡""保存用户头像到相册"这类需求分别意味着什么？

📄 第 11 章 异步处理：协程与 Flow 11-coroutines-and-flow.md✓ 标记已学

阶段：进阶 ｜ 预计阅读 90 min ｜ 代码落地模块：:core:common、:core:testing、:feature:feed 前置：第 01 章 Kotlin 速成与协程预热 ｜ 第 03 章 应用组件与生命周期 ｜ 第 09 章 网络请求 相关章节：第 10 章 数据存储 ｜ 第 14 章 分层架构与 MVI ｜ 第 21 章 测试策略 ｜ 第 17 章 性能优化

学习目标

• [ ] 理解结构化并发：协程树如何随生命周期自动取消，为什么禁用 GlobalScope。
• [ ] 能正确选择 Job / SupervisorJob、launch / async、coroutineScope / supervisorScope，并解释它们的失败传播差异。
• [ ] 掌握协程异常处理三件套：try/catch、CoroutineExceptionHandler、以及"CancellationException 绝不能吞"。
• [ ] 理解 Flow 的冷流本质与常用操作符，能写出搜索防抖、多源聚合等真实场景。
• [ ] 说清 StateFlow 与 SharedFlow 的差异与 replay 配置，会用 stateIn + WhileSubscribed 做生命周期感知的共享。
• [ ] 会用 runTest、TestDispatcher 与 Turbine 为协程与 Flow 写确定性测试（不再 sleep）。

一、核心概念

1.1 为什么 Android 必须异步

Android 的主线程（Main Thread / UI Thread）负责绘制与事件分发，单线程循环处理消息队列。 主线程被阻塞 5 秒 → ANR（Application Not Responding，应用无响应）；阻塞 16ms 以上 → 掉帧。

因此有一条铁律：主线程只做两件事——更新 UI 和分发事件，其他一律挪走。

flowchart LR
    A["用户点击"] --> B["主线程消息队列"]
    B --> C["事件分发 / 测量布局绘制"]
    C --> D{"是否有耗时操作?"}
    D -->|"是：网络/DB/大图"| E["切到后台线程"]
    E --> F["withContext(Dispatchers.IO)"]
    F --> G["回到主线程更新 UI"]
    D -->|"否"| H["直接执行"]
    G --> B

协程解决的是**"切过去再切回来"这件本来需要回调嵌套的事**。它的杀手锏是：用同步的书写顺序表达异步逻辑。

1.2 结构化并发：协程是一棵树

这是协程最重要、也最容易被忽略的概念。每个协程都有父协程，取消父协程会递归取消所有子协程。

flowchart TB
    VM["viewModelScope<br/>CoroutineScope(SupervisorJob + Main)"] --> A["Job A：加载信息流"]
    VM --> B["Job B：加载用户信息"]
    VM --> C["Job C：上报埋点"]
    A --> A1["子协程：网络请求"]
    A --> A2["子协程：写入 Room"]
    B --> B1["子协程：读取 DataStore"]
    VM -.->|"ViewModel.onCleared()<br/>cancel 所有子协程"| A
    VM -.->|"递归取消"| A1

结构化并发带来三条推论：

1. 不需要手动管理生命周期：viewModelScope 在 onCleared() 时自动取消，页面销毁后不会有回调继续执行。
2. 父协程会等待所有子协程完成：launch 的父作用域退出前，会等它的所有子协程结束（这就是"结构化"的含义）。
3. GlobalScope 是反模式：它不属于任何生命周期，取消不了，是内存泄漏与"页面销毁后更新 UI 崩溃"的头号来源。

[!WARNING] 只有一种场景可以接受全局作用域：进程级别的、本就应该活到 App 结束的任务（如崩溃上报的兜底）。 即便如此也应自建 @Singleton class AppScope(...) : CoroutineScope，而不是直接用 GlobalScope——前者至少可测试、可取消。

1.3 Job 与 SupervisorJob：失败是否连坐

// viewModelScope 内部就是 SupervisorJob + Dispatchers.Main.immediate
// 所以 ViewModel 里两个并行的请求互不影响 —— 这是官方的有意设计

注意 SupervisorJob 只对子协程生效：如果你在自己的 Scope 里 coroutineScope { } 再包一层，内层仍是普通 Job，仍会连坐。

1.4 Dispatcher 怎么选

[!TIP] suspend 函数必须是主线程安全的：它内部自己 withContext 切线程，调用方无需关心。 所以 Retrofit 的 suspend 接口、Room 的 suspend 查询，你直接调就行——它们已经切好了。

1.5 launch 与 async

⚠️ async 最容易犯的错：启动了却没 await，异常被吞且任务白跑。并发聚合请优先用 coroutineScope { } 包住。

1.6 coroutineScope 与 supervisorScope

两者都是挂起函数，会等待内部所有子协程完成后才返回，区别在于失败传播：

• coroutineScope：任一子协程失败 → 取消其余兄弟、自己抛出（全败）。
• supervisorScope：子协程失败互不影响，你可以逐个 try/catch 处理（部分成功）。

1.7 取消是协作式的

协程取消不是强制杀线程，而是：job.cancel() 把协程标记为取消 → 协程在下一个挂起点（delay、withContext、await、Flow 的 emit）抛出 CancellationException。

推论：

• 纯 CPU 循环不会响应取消。要手动检查：while (isActive) 或 ensureActive()。
• Thread.sleep() 不响应取消，必须用 delay()。
• 阻塞式 I/O 也不响应取消，包在 withContext(Dispatchers.IO) 里也不行——得用可中断的 API 或超时。

1.8 异常处理：三条规则

flowchart TB
    A["协程抛出异常"] --> B{"是 CancellationException?"}
    B -->|"是"| C["正常取消信号<br/>必须重新抛出"]
    B -->|"否"| D{"用 launch 还是 async?"}
    D -->|"launch"| E["交给 CoroutineExceptionHandler<br/>或向上冒泡到根作用域崩溃"]
    D -->|"async"| F["暂存在 Deferred<br/>await() 时才抛出"]

1. CancellationException 必须重新抛出。用 catch (e: Exception) 会把它一起吞掉，导致协程"取消不了"， ViewModel 销毁后任务仍在跑——这是最隐蔽的泄漏。
2. launch 的异常无法用外层 try/catch 捕获（因为 launch 立即返回）。要在协程体内 try/catch，或装 CoroutineExceptionHandler。
3. CoroutineExceptionHandler 只对 launch 生效，对 async 无效（async 的异常在 await 处抛出）。它不是"吞异常"的兜底， 更不能被用来替代正确的错误处理——它拿不到协程上下文之外的业务信息。

1.9 Flow：冷流

Flow 是冷流（Cold Stream）：没有收集者（collector）时，上游代码根本不会执行；每次 collect 都会重新跑一遍上游。

flowchart LR
    A["flow { emit(1); emit(2) }"] -->|"map"| B["转换"]
    B -->|"filter"| C["过滤"]
    C -->|"flowOn(IO)"| D["切换上游线程"]
    D --> E["collect 收集"]
    E -->|"每次 collect 重新执行"| A

这与 StateFlow（热流，Hot Stream）形成对比：热流独立于收集者存在，数据缓存在对象里。

1.10 StateFlow 与 SharedFlow 的分工

[!WARNING] 用 SharedFlow(replay = 1) 当事件通道是可行的，但不要用 StateFlow 承载一次性事件： 旋转屏幕后重新收集，StateFlow 会把上次的 Toast 事件再推一次，用户会看到重复弹窗。

1.11 stateIn：把冷流变成生命周期感知的热流

Repository 返回的冷流 Flow<List<Article>>，如果每个收集者都自己跑一遍（重查一次数据库、重发一次请求），就是浪费。 stateIn 把它变成共享的 StateFlow：

SharingStarted.WhileSubscribed(stopTimeoutMillis = 5_000)

含义：最后一个订阅者消失后，再等 5 秒才停止上游。为什么要等？因为旋转屏幕、短暂跳页会造成"订阅者瞬间消失又回来"， 5 秒的宽限期能避免上游被反复启停（数据库被关了又开）。其他策略：

1.12 flowOn 与 launchIn

• flowOn(Dispatchers.IO)：只影响它上游的执行线程（下游仍在收集者的线程）。多次调用可分段切换。
• launchIn(scope)：在指定作用域中启动收集，返回 Job，等价于 scope.launch { flow.collect() }，链式写起来更顺。

1.13 callbackFlow：把回调 API 变成 Flow

第三方 SDK（定位、传感器、网络回调、广播）只给回调接口。用 callbackFlow 可以把它包装成 Flow， 从而享受 Flow 的操作符与生命周期管理。两个关键约束：

1. 必须 awaitClose { 注销回调 }——否则收集结束后回调还在跑，必然泄漏。
2. trySend 而非阻塞的 send（在 callbackFlow 内推荐用 trySend 避免意外挂起）。

1.14 测试：为什么必须换掉调度器

生产代码里的 Dispatchers.Main 在 JVM 单元测试中不存在（会抛 IllegalStateException: Module with the Main dispatcher had failed to initialize）， Dispatchers.IO 又是真实的线程池——导致测试不确定、需要 sleep。解法是 kotlinx-coroutines-test：

1.15 背压与限流

背压（Backpressure）指"生产快于消费"时的处理策略。Flow 默认通过挂起 emit 自动适配（生产者等消费者）， 但当生产来自非挂起源头（回调、callbackFlow、传感器）时，就必须显式选择策略：

另一类问题是并发数量失控：循环里 launch 一万个协程会把线程池撑爆。正确做法是用 Semaphore（信号量）限流，或用 Flow 的背压机制把批量任务变成可控的流。

1.16 Flow 与 Channel 怎么选

Channel 是热的、带缓冲的协程间通信原语，支持多生产多消费。 绝大多数业务场景应优先用 Flow：

• Flow 更声明式，能享受操作符、生命周期与测试设施；Channel 需要手动管理发送与关闭。
• 需要"跨协程共享事件队列"时才用 Channel（如生产者消费者模型、多路复用 select）。
• Channel 的发送方如果忘了 close()，消费者会永远挂起——这是最常见的死锁来源。

[!TIP] 判断口诀："我想要一份可组合的数据流" → Flow；"我要一个协程往里塞、另一个协程往外取的队列" → Channel。

1.17 性能视角：协程不是免费的

协程很轻（一个对象几十字节），但不是零成本。三条需要记住的性能常识：

1. 创建成本 ≈ 几十纳秒，但一万个协程仍会占用一万个 Job 对象与调度开销。批量任务要限流。
2. Dispatchers.IO 默认最多 64 线程，且每个 withContext(IO) 切换都是一次线程调度。 在循环里逐条插入数据库并每次切 IO，比"一次批量插入"慢一个数量级——批量优于频繁切换。
3. withContext 是安全的挂起点，但每次切换都会经历"挂起—入队—恢复"。 不要写 withContext(IO) { 1 + 1 } 这种粒度小到不值得切换的代码。

与之相对的是真正的性能杀手：runBlocking 在主线程调用会阻塞整条消息队列， 造成掉帧甚至 ANR；Thread.sleep 会占住线程不放。这两者在业务代码里应被视为禁词。

二、示例代码

2.1 依赖

// 文件路径：sample/core/common/build.gradle.kts
dependencies {
    implementation(libs.kotlinx.coroutines.android)   // 提供 Dispatchers.Main
    testImplementation(libs.bundles.testing.unit)     // junit + truth + turbine + coroutines-test
    // 版本统一由 gradle/libs.versions.toml 收口，正文不写死版本号
}

2.2 结构化并发：Scope 的正确用法

// 文件路径：sample/feature/feed/src/main/java/com/techfeed/feature/feed/ui/FeedViewModel.kt
package com.techfeed.feature.feed.ui

import androidx.lifecycle.ViewModel
import androidx.lifecycle.viewModelScope
import com.techfeed.core.model.AppError
import com.techfeed.core.model.Article
import com.techfeed.core.model.Result
import com.techfeed.feature.feed.domain.GetFeedUseCase
import com.techfeed.feature.feed.domain.RefreshFeedUseCase
import dagger.hilt.android.lifecycle.HiltViewModel
import kotlinx.coroutines.CancellationException
import kotlinx.coroutines.Job
import kotlinx.coroutines.flow.MutableSharedFlow
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.SharedFlow
import kotlinx.coroutines.flow.StateFlow
import kotlinx.coroutines.flow.asSharedFlow
import kotlinx.coroutines.flow.asStateFlow
import kotlinx.coroutines.launch
import javax.inject.Inject

/** UI 状态：一个不可变快照，UI 只是它的函数 */
data class FeedUiState(
    val isLoading: Boolean = false,
    val articles: List<Article> = emptyList(),
    val error: AppError? = null,
    val isRefreshing: Boolean = false,
)

/** 一次性事件：不进 UiState，避免重建时重复触发 */
sealed interface FeedEvent {
    data class ShowToast(val message: String) : FeedEvent
    data class NavigateToDetail(val articleId: String) : FeedEvent
    data object ScrollToTop : FeedEvent
}

@HiltViewModel
class FeedViewModel @Inject constructor(
    private val getFeed: GetFeedUseCase,
    private val refreshFeed: RefreshFeedUseCase,
) : ViewModel() {

    private val _uiState = MutableStateFlow(FeedUiState())
    val uiState: StateFlow<FeedUiState> = _uiState.asStateFlow()

    private val _events = MutableSharedFlow<FeedEvent>(
        // extraBufferCapacity：允许在没人收集时（如页面刚重建）先缓存一个事件不丢
        extraBufferCapacity = 1,
    )
    val events: SharedFlow<FeedEvent> = _events.asSharedFlow()

    // 保存刷新任务的句柄：用于"重复点击只保留最后一次"
    private var refreshJob: Job? = null

    init {
        load()
    }

    private fun load() {
        // viewModelScope 在 onCleared 时自动 cancel，无需手动管理
        viewModelScope.launch {
            _uiState.value = _uiState.value.copy(isLoading = true)
            when (val result = getFeed()) {
                is Result.Success -> _uiState.value = FeedUiState(articles = result.data)
                is Result.Failure -> _uiState.value = FeedUiState(error = result.error)
                Result.Loading -> Unit
            }
        }
    }

    fun onRefresh() {
        // 取消上一次未完成的刷新：避免两次结果乱序覆盖（竞态）
        refreshJob?.cancel()
        refreshJob = viewModelScope.launch {
            _uiState.value = _uiState.value.copy(isRefreshing = true)
            try {
                when (val result = refreshFeed()) {
                    is Result.Success -> _events.emit(FeedEvent.ScrollToTop)
                    is Result.Failure -> _events.emit(FeedEvent.ShowToast("刷新失败"))
                    Result.Loading -> Unit
                }
            } catch (e: CancellationException) {
                // ⚠️ 取消是正常信号，必须原样抛出，否则协程无法真正取消
                throw e
            } finally {
                // finally 中恢复标志位；注意：取消时 finally 仍会执行（但里面的挂起调用会立即再抛取消）
                _uiState.value = _uiState.value.copy(isRefreshing = false)
            }
        }
    }

    fun onArticleClick(id: String) {
        viewModelScope.launch { _events.emit(FeedEvent.NavigateToDetail(id)) }
    }
}

2.3 launch vs async：并发聚合首页数据

// 文件路径：docs/samples/ch11/LoadHomeUseCase.kt
package com.techfeed.feature.feed.domain

import com.techfeed.core.common.DispatcherProvider
import com.techfeed.core.model.Article
import com.techfeed.core.model.Banner
import kotlinx.coroutines.async
import kotlinx.coroutines.coroutineScope
import kotlinx.coroutines.withContext
import javax.inject.Inject

data class HomeData(val articles: List<Article>, val banners: List<Banner>, val unreadCount: Int)

class LoadHomeUseCase @Inject constructor(
    private val articleRepo: ArticleRepository,
    private val bannerRepo: BannerRepository,
    private val messageRepo: MessageRepository,
    private val dispatchers: DispatcherProvider,
) {
    /**
     * 三个接口并发请求，全部成功后一起返回（总耗时 = 最慢的那个，而非三者之和）。
     * coroutineScope：任一失败则整体失败并取消其余请求 —— 首页数据缺一不可，这是正确的语义。
     */
    suspend operator fun invoke(): HomeData = withContext(dispatchers.default) {
        coroutineScope {
            val articles = async { articleRepo.topArticles() }
            val banners = async { bannerRepo.activeBanners() }
            val unread = async { messageRepo.unreadCount() }
            // await 时才抛异常；三个都 await 了，异常不会被吞
            HomeData(articles.await(), banners.await(), unread.await())
        }
    }
}

// 文件路径：docs/samples/ch11/LoadHomeTolerantUseCase.kt
package com.techfeed.feature.feed.domain

import com.techfeed.core.model.Article
import com.techfeed.core.model.Banner
import kotlinx.coroutines.async
import kotlinx.coroutines.supervisorScope
import javax.inject.Inject

/**
 * 容错版：某个接口挂了不影响其他数据（"有总比没有好"）。
 * supervisorScope 阻断失败向上传播，对每个 Deferred 单独 try/catch。
 */
class LoadHomeTolerantUseCase @Inject constructor(
    private val articleRepo: ArticleRepository,
    private val bannerRepo: BannerRepository,
) {
    suspend operator fun invoke(): HomeData = supervisorScope {
        val articles = async { runCatching { articleRepo.topArticles() }.getOrDefault(emptyList()) }
        val banners = async { runCatching { bannerRepo.activeBanners() }.getOrDefault(emptyList()) }
        HomeData(
            articles = articles.await(),
            banners = banners.await(),
            unreadCount = 0,
        )
    }
}

[!TIP] 选 coroutineScope 还是 supervisorScope，本质是业务问题：这一组数据缺一不可，还是缺了也能用？ 首页主内容用前者，首页的"运营弹窗 + 消息红点"用后者。

2.4 Dispatcher 注入：让测试可控

// 文件路径：sample/core/common/src/main/java/com/techfeed/core/common/DispatcherProvider.kt
package com.techfeed.core.common

import kotlinx.coroutines.CoroutineDispatcher
import kotlinx.coroutines.Dispatchers
import javax.inject.Inject

/**
 * 不要在业务代码里直接写 Dispatchers.IO —— 那样测试时无法替换。
 * 注入接口，测试期传入 TestDispatcher，生产期传真实 Dispatcher。
 */
interface DispatcherProvider {
    val main: CoroutineDispatcher
    val io: CoroutineDispatcher
    val default: CoroutineDispatcher
}

class DefaultDispatcherProvider @Inject constructor() : DispatcherProvider {
    override val main: CoroutineDispatcher get() = Dispatchers.Main
    override val io: CoroutineDispatcher get() = Dispatchers.IO
    override val default: CoroutineDispatcher get() = Dispatchers.Default
}

// 文件路径：sample/core/common/src/main/java/com/techfeed/core/common/di/DispatcherModule.kt
package com.techfeed.core.common.di

import com.techfeed.core.common.DefaultDispatcherProvider
import com.techfeed.core.common.DispatcherProvider
import dagger.Binds
import dagger.Module
import dagger.hilt.InstallIn
import dagger.hilt.components.SingletonComponent
import javax.inject.Singleton

@Module
@InstallIn(SingletonComponent::class)
abstract class DispatcherModule {
    /** @Binds 比 @Provides 更高效：只是把实现类型映射到接口，无方法体 */
    @Binds
    @Singleton
    abstract fun bindDispatcherProvider(impl: DefaultDispatcherProvider): DispatcherProvider
}

2.5 取消、超时与资源释放

// 文件路径：docs/samples/ch11/CoroutineExt.kt
package com.techfeed.core.common

import kotlinx.coroutines.CancellationException
import kotlinx.coroutines.ensureActive
import kotlinx.coroutines.isActive
import kotlinx.coroutines.coroutineScope
import kotlinx.coroutines.delay
import kotlinx.coroutines.withTimeoutOrNull
import kotlin.coroutines.coroutineContext

/**
 * 带超时的重试：
 * 1. 用 withTimeoutOrNull 而非 withTimeout —— 后者抛 TimeoutCancellationException，需要额外 catch
 * 2. 用 delay 而非 Thread.sleep —— delay 可被取消，sleep 不能
 * 3. 遇到 CancellationException 立即抛出
 */
suspend fun <T> retryWithTimeout(
    times: Int = 3,
    initialDelayMs: Long = 500,
    timeoutMs: Long = 5_000,
    block: suspend () -> T,
): T? {
    var currentDelay = initialDelayMs
    repeat(times - 1) { attempt ->
        withTimeoutOrNull(timeoutMs) { block() }?.let { return it }
        delay(currentDelay)
        currentDelay *= 2      // 指数退避
    }
    return withTimeoutOrNull(timeoutMs) { block() }   // 最后一次尝试
}

/** CPU 密集循环必须手动检查 isActive，否则协程无法被取消 */
suspend fun computeHeavy(iterations: Int): Long = coroutineScope {
    var sum = 0L
    for (i in 1..iterations) {
        ensureActive()          // 等价于 if (!isActive) throw CancellationException()
        sum += i
        if (i % 1000 == 0) delay(1)   // 定期让出，给取消一个挂起点
    }
    sum
}

2.6 异常处理：CoroutineExceptionHandler 的正确位置

// 文件路径：docs/samples/ch11/CoroutineExceptionHandlerExt.kt
package com.techfeed.core.crash

import kotlinx.coroutines.CoroutineExceptionHandler
import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.launch

/**
 * ⚠️ CoroutineExceptionHandler 只对 launch 的根协程生效：
 * 装在子协程上不会起作用（异常会交给父协程）；装在 async 上也不起作用。
 * 它的定位是"兜底上报"，不是业务流程的错误处理。
 */
val GlobalReportHandler = CoroutineExceptionHandler { _, throwable ->
    CrashReporter.record(throwable)   // 上报，见第 18 章
}

fun CoroutineScope.safeLaunch(block: suspend CoroutineScope.() -> Unit) =
    launch(GlobalReportHandler, block = block)

// 文件路径：docs/samples/ch11/FeedViewModelErrorHandling.kt
package com.techfeed.feature.feed.ui

import androidx.lifecycle.viewModelScope
import kotlinx.coroutines.CancellationException
import kotlinx.coroutines.launch

/** 推荐的错误处理写法：在协程体内 try/catch，粒度最细、信息最全 */
fun FeedViewModel.loadSafely() {
    viewModelScope.launch {
        try {
            val data = getFeed()
            // 处理数据
        } catch (e: CancellationException) {
            throw e                                  // ① 取消必须重抛
        } catch (e: java.io.IOException) {
            _uiState.value = _uiState.value.copy(error = com.techfeed.core.model.AppError.Network(e))
        } catch (e: Exception) {
            _uiState.value = _uiState.value.copy(error = com.techfeed.core.model.AppError.Unknown(e))
        }
    }
}

[!WARNING] 不要用 runCatching { } 包住整个协程体：它会把 CancellationException 一起捕获， 导致协程取消失效（ViewModel 销毁后任务继续跑）。要么手写 try/catch 并重抛取消， 要么用 runCatching 后显式判断 if (e is CancellationException) throw e。

2.7 Flow 构建与常用操作符

// 文件路径：docs/samples/ch11/ObserveFeedUseCase.kt
package com.techfeed.feature.feed.domain

import com.techfeed.core.model.Article
import kotlinx.coroutines.ExperimentalCoroutinesApi
import kotlinx.coroutines.delay
import kotlinx.coroutines.flow.Flow
import kotlinx.coroutines.flow.catch
import kotlinx.coroutines.flow.combine
import kotlinx.coroutines.flow.distinctUntilChanged
import kotlinx.coroutines.flow.filter
import kotlinx.coroutines.flow.flatMapLatest
import kotlinx.coroutines.flow.flow
import kotlinx.coroutines.flow.flowOn
import kotlinx.coroutines.flow.map
import kotlinx.coroutines.flow.onEach
import kotlinx.coroutines.flow.onStart
import kotlinx.coroutines.flow.retryWhen
import javax.inject.Inject
import kotlin.time.Duration.Companion.seconds

class ObserveFeedUseCase @Inject constructor(
    private val repository: ArticleRepository,
    private val settings: SettingsRepository,
) {
    /**
     * 组合多个数据源：文章内容 + 用户的"只看收藏"开关。
     * combine：任一方变化就用最新的另一方重新计算（区别于 zip 的一对一配对）。
     */
    operator fun invoke(): Flow<List<Article>> = combine(
        repository.observeArticles(),
        settings.observeFavoritesOnly(),
    ) { articles, favoritesOnly ->
        if (favoritesOnly) articles.filter { it.isFavorite } else articles
    }
        .distinctUntilChanged()                    // 内容没变就不发射，减少无意义重组
        .flowOn(kotlinx.coroutines.Dispatchers.Default)   // 过滤/映射这类 CPU 操作放 Default
        .catch { emit(emptyList()) }               // Flow 异常兜底；注意它也会终止上游
}

@OptIn(ExperimentalCoroutinesApi::class)
class SearchUseCase @Inject constructor(private val repository: ArticleRepository) {
    /**
     * 搜索防抖：
     * debounce —— 停止输入 300ms 后才发请求
     * distinctUntilChanged —— 相同关键词不重复请求
     * flatMapLatest —— 新关键词到来时取消上一次未完成的搜索（关键！否则结果乱序）
     */
    operator fun invoke(queryFlow: Flow<String>): Flow<List<Article>> = queryFlow
        .map { it.trim() }
        .distinctUntilChanged()
        .debounce(300)
        .filter { it.length >= 2 }
        .flatMapLatest { query -> repository.search(query) }
        .retryWhen { cause, attempt ->
            // 网络类错误重试 2 次，其他直接抛出
            if (cause is java.io.IOException && attempt < 2) {
                delay(2.0.seconds.inWholeMilliseconds * (attempt + 1))
                true
            } else {
                false
            }
        }
}

/** 轮询：用 flow + delay 实现，天然可被取消（比 Timer/Handler 安全得多） */
fun tickerFlow(intervalMs: Long): Flow<Unit> = flow {
    while (true) {
        emit(Unit)
        delay(intervalMs)
    }
}

[!NOTE] debounce、flatMapLatest、retryWhen 在早期版本需要 @OptIn(ExperimentalCoroutinesApi::class)， 较新的 coroutines 版本已转正。以工程中实际编译提示为准。

2.8 StateFlow / SharedFlow 与 stateIn

// 文件路径：docs/samples/ch11/FeedStateHolder.kt
package com.techfeed.feature.feed.ui

import androidx.lifecycle.ViewModel
import androidx.lifecycle.viewModelScope
import com.techfeed.feature.feed.domain.ObserveFeedUseCase
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.SharingStarted
import kotlinx.coroutines.flow.StateFlow
import kotlinx.coroutines.flow.WhileSubscribed
import kotlinx.coroutines.flow.combine
import kotlinx.coroutines.flow.stateIn
import kotlinx.coroutines.flow.update

/**
 * 冷流转热流的标准写法：
 * - scope = viewModelScope：随 ViewModel 销毁而取消
 * - started = WhileSubscribed(5000)：最后一个订阅者离开 5 秒后才停上游
 *   → 旋转屏幕、短暂跳页不会导致数据库被关闭重开
 * - initialValue：StateFlow 必须有初始值，这里给 Loading
 */
class FeedStateHolder(
    observeFeed: ObserveFeedUseCase,
    private val scope: kotlinx.coroutines.CoroutineScope,
) {
    val uiState: StateFlow<FeedUiState> = combine(
        observeFeed(),
        MutableStateFlow(false),
    ) { articles, refreshing ->
        FeedUiState(articles = articles, isRefreshing = refreshing)
    }.stateIn(
        scope = scope,
        started = SharingStarted.WhileSubscribed(STOP_TIMEOUT_MS),
        initialValue = FeedUiState(isLoading = true),
    )

    private companion object {
        const val STOP_TIMEOUT_MS = 5_000L
    }
}

// 文件路径：docs/samples/ch11/EventFlow.kt
package com.techfeed.core.common

import kotlinx.coroutines.channels.BufferOverflow
import kotlinx.coroutines.flow.MutableSharedFlow
import kotlinx.coroutines.flow.SharedFlow
import kotlinx.coroutines.flow.asSharedFlow

/**
 * 事件通道的统一配置。三个参数必须理解清楚：
 * replay = 0        → 新订阅者不会收到历史事件（避免旋转屏幕重复弹 Toast）
 * extraBufferCapacity = 1 → 允许在无人收集时暂存 1 个事件（页面刚重建时不丢）
 * onBufferOverflow = DROP_OLDEST → 缓冲满时丢最旧的，保证 emit 不挂起
 */
class EventFlow<T> {
    private val _flow = MutableSharedFlow<T>(
        replay = 0,
        extraBufferCapacity = 1,
        onBufferOverflow = BufferOverflow.DROP_OLDEST,
    )
    val flow: SharedFlow<T> = _flow.asSharedFlow()

    /** tryEmit 非挂起：在 UI 回调、init 块中也能安全发送 */
    fun tryEmit(event: T) { _flow.tryEmit(event) }
}

2.9 callbackFlow：把回调 API 变成 Flow

// 文件路径：docs/samples/ch11/NetworkStatusFlow.kt
package com.techfeed.core.common

import android.content.Context
import android.net.ConnectivityManager
import android.net.Network
import android.net.NetworkCapabilities
import android.net.NetworkRequest
import kotlinx.coroutines.channels.awaitClose
import kotlinx.coroutines.flow.Flow
import kotlinx.coroutines.flow.callbackFlow
import kotlinx.coroutines.flow.distinctUntilChanged

/** 把 ConnectivityManager.NetworkCallback 包装成 Flow，替换已失效的 CONNECTIVITY_ACTION 广播 */
fun networkStatusFlow(context: Context): Flow<Boolean> = callbackFlow {
    val manager = context.getSystemService(ConnectivityManager::class.java)
    val request = NetworkRequest.Builder()
        .addCapability(NetworkCapabilities.NET_CAPABILITY_INTERNET)
        .build()

    val callback = object : ConnectivityManager.NetworkCallback() {
        override fun onAvailable(network: Network) { trySend(true) }
        override fun onLost(network: Network) { trySend(false) }
    }

    manager.registerNetworkCallback(request, callback)
    trySend(manager.isCurrentlyOnline())   // 先推一次当前状态，冷流不至于一开始没值

    // ⚠️ awaitClose 必须存在：收集结束时注销回调，否则 Context 泄漏
    awaitClose { manager.unregisterNetworkCallback(callback) }
}.distinctUntilChanged()

private fun ConnectivityManager.isCurrentlyOnline(): Boolean =
    activeNetwork?.let { getNetworkCapabilities(it) }
        ?.hasCapability(NetworkCapabilities.NET_CAPABILITY_INTERNET) == true

2.10 并发安全：Mutex 与 Semaphore

// 文件路径：docs/samples/ch11/ConcurrencyExt.kt
package com.techfeed.core.common

import kotlinx.coroutines.async
import kotlinx.coroutines.coroutineScope
import kotlinx.coroutines.sync.Mutex
import kotlinx.coroutines.sync.Semaphore
import kotlinx.coroutines.sync.withLock
import kotlinx.coroutines.sync.withPermit

/**
 * 场景一：保护共享可变状态（如内存缓存、写入同一文件）。
 * Mutex 是协程版的锁，但它是"挂起等待"而不是阻塞线程 —— 不会占用线程池。
 */
class InMemoryCache<T> {
    private val mutex = Mutex()
    private val map = mutableMapOf<String, T>()

    suspend fun put(key: String, value: T) = mutex.withLock { map[key] = value }
    suspend fun get(key: String): T? = mutex.withLock { map[key] }
}

/**
 * 场景二：批量任务限流。
 * Semaphore(3) 表示同时最多 3 个任务在执行，其余挂起等待许可。
 * 不用限流的话，1000 个并发上传会瞬间创建 1000 个协程并把连接池打满。
 */
suspend fun <T> List<T>.mapConcurrent(
    limit: Int,
    block: suspend (T) -> Unit,
) = coroutineScope {
    val semaphore = Semaphore(limit)
    map { item ->
        async {
            semaphore.withPermit { block(item) }   // 用完自动释放许可，异常也会释放
        }
    }.forEach { it.await() }
}

[!WARNING] Mutex 不是线程锁的替代品：它只在协程内生效，不能保护跨线程的共享可变状态。 另外不要用它包住整个网络请求——那会把并发退化成串行。它只应保护极短的临界区。

2.11 UI 双体系：如何安全收集 Flow

// 文件路径：sample/feature/feed/src/main/java/com/techfeed/feature/feed/ui/FeedScreen.kt
package com.techfeed.feature.feed.ui

import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.lazy.LazyColumn
import androidx.compose.foundation.lazy.items
import androidx.compose.material3.CircularProgressIndicator
import androidx.compose.material3.ListItem
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.runtime.LaunchedEffect
import androidx.compose.runtime.getValue
import androidx.compose.ui.Modifier
import androidx.hilt.navigation.compose.hiltViewModel
import androidx.lifecycle.compose.collectAsStateWithLifecycle

@Composable
fun FeedScreen(
    onArticleClick: (String) -> Unit,
    modifier: Modifier = Modifier,
    viewModel: FeedViewModel = hiltViewModel(),
) {
    // collectAsStateWithLifecycle：生命周期感知的收集，页面不可见时自动停止（省电、省资源）
    val uiState by viewModel.uiState.collectAsStateWithLifecycle()

    // 一次性事件：用 LaunchedEffect 收集，它的协程随 Composable 退出自动取消
    LaunchedEffect(Unit) {
        viewModel.events.collect { event ->
            when (event) {
                is FeedEvent.NavigateToDetail -> onArticleClick(event.articleId)
                is FeedEvent.ShowToast -> { /* 显示 Snackbar */ }
                FeedEvent.ScrollToTop -> { /* listState.animateScrollToItem(0) */ }
            }
        }
    }

    if (uiState.isLoading) {
        CircularProgressIndicator(modifier = modifier.fillMaxSize())
        return
    }

    LazyColumn(modifier = modifier.fillMaxSize()) {
        items(items = uiState.articles, key = { it.id }) { article ->
            ListItem(
                headlineContent = { Text(article.title) },
                supportingContent = { Text(article.summary) },
            )
        }
    }
}

// 文件路径：docs/samples/ch11/FeedFragment.kt
package com.techfeed.feature.feed.ui

import android.os.Bundle
import android.view.LayoutInflater
import android.view.View
import android.view.ViewGroup
import androidx.fragment.app.Fragment
import androidx.fragment.app.viewModels
import androidx.lifecycle.Lifecycle
import androidx.lifecycle.lifecycleScope
import androidx.lifecycle.repeatOnLifecycle
import com.techfeed.feature.feed.databinding.FragmentFeedBinding
import dagger.hilt.android.AndroidEntryPoint
import kotlinx.coroutines.launch

/**
 * View 体系下的标准收集姿势：
 * ⚠️ 直接 lifecycleScope.launch { collect{} } 是错的 —— 页面进入后台仍会收集，
 * 数据库查询与 UI 更新照跑，白白耗电。必须用 repeatOnLifecycle。
 */
@AndroidEntryPoint
class FeedFragment : Fragment() {

    private var _binding: FragmentFeedBinding? = null
    private val binding get() = requireNotNull(_binding)
    private val viewModel: FeedViewModel by viewModels()
    private lateinit var adapter: FeedAdapter

    override fun onCreateView(inflater: LayoutInflater, container: ViewGroup?, saved: Bundle?): View {
        _binding = FragmentFeedBinding.inflate(inflater, container, false)
        return binding.root
    }

    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        super.onViewCreated(view, savedInstanceState)
        adapter = FeedAdapter(onItemClick = { viewModel.onArticleClick(it) })
        binding.recyclerView.adapter = adapter
        binding.swipeRefresh.setOnRefreshListener { viewModel.onRefresh() }

        viewLifecycleOwner.lifecycleScope.launch {
            viewLifecycleOwner.repeatOnLifecycle(Lifecycle.State.STARTED) {
                // 两个收集独立 launch：互不阻塞
                launch { viewModel.uiState.collect { render(it) } }
                launch { viewModel.events.collect { handle(it) } }
            }
        }
    }

    private fun render(state: FeedUiState) {
        adapter.submitList(state.articles)
        binding.swipeRefresh.isRefreshing = state.isRefreshing
        binding.progress.isVisible = state.isLoading
    }

    private fun handle(event: FeedEvent) { /* Toast / 导航 */ }

    override fun onDestroyView() {
        binding.recyclerView.adapter = null
        _binding = null      // ⚠️ 必须置空
        super.onDestroyView()
    }
}

2.12 测试：runTest、TestDispatcher 与 Turbine

// 文件路径：sample/core/testing/src/main/java/com/techfeed/core/testing/MainDispatcherRule.kt
package com.techfeed.core.testing

import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.test.TestDispatcher
import kotlinx.coroutines.test.UnconfinedTestDispatcher
import kotlinx.coroutines.test.resetMain
import kotlinx.coroutines.test.setMain
import org.junit.rules.TestWatcher
import org.junit.runner.Description

/**
 * 把 Dispatchers.Main 替换为测试调度器。
 * 所有用到 viewModelScope / Dispatchers.Main 的测试都要加这个 Rule。
 */
class MainDispatcherRule(
    val testDispatcher: TestDispatcher = UnconfinedTestDispatcher(),
) : TestWatcher() {
    override fun starting(description: Description) {
        Dispatchers.setMain(testDispatcher)
    }

    override fun finished(description: Description) {
        Dispatchers.resetMain()
    }
}

// 文件路径：sample/core/testing/src/main/java/com/techfeed/core/testing/TestDispatcherProvider.kt
package com.techfeed.core.testing

import com.techfeed.core.common.DispatcherProvider
import kotlinx.coroutines.CoroutineDispatcher
import kotlinx.coroutines.test.TestDispatcher

/** 测试期替换 DispatcherProvider：所有业务都跑在同一个可控调度器上 */
class TestDispatcherProvider(private val dispatcher: TestDispatcher) : DispatcherProvider {
    override val main: CoroutineDispatcher get() = dispatcher
    override val io: CoroutineDispatcher get() = dispatcher
    override val default: CoroutineDispatcher get() = dispatcher
}

// 文件路径：sample/feature/feed/src/test/java/com/techfeed/feature/feed/ui/FeedViewModelTest.kt
package com.techfeed.feature.feed.ui

import app.cash.turbine.test
import com.google.common.truth.Truth.assertThat
import com.techfeed.core.model.Article
import com.techfeed.core.model.Result
import com.techfeed.core.testing.MainDispatcherRule
import com.techfeed.feature.feed.domain.FeedRepository
import com.techfeed.feature.feed.domain.GetFeedUseCase
import com.techfeed.feature.feed.domain.RefreshFeedUseCase
import kotlinx.coroutines.ExperimentalCoroutinesApi
import kotlinx.coroutines.test.StandardTestDispatcher
import kotlinx.coroutines.test.advanceUntilIdle
import kotlinx.coroutines.test.runTest
import org.junit.Rule
import org.junit.Test

@OptIn(ExperimentalCoroutinesApi::class)
class FeedViewModelTest {

    @get:Rule
    val mainDispatcherRule = MainDispatcherRule(StandardTestDispatcher())

    /**
     * GetFeedUseCase / RefreshFeedUseCase 是 final class（构造参数是 repository），
     * 不能用"继承 + override invoke"的方式伪造 —— 正确做法是伪造接口 FeedRepository，
     * 再把真实 UseCase 套在 Fake 仓库外面（UseCase 本身只是薄薄的委托）。
     * 注：本章的仓库契约为 getFeed/refresh 的简化形态；第 12 章起 FeedRepository
     * 演进为 observeFeed/refresh/toggleFavorite（演进见各章说明）。
     */
    private val fakeRepository = FakeFeedRepository()

    private fun createViewModel() = FeedViewModel(
        GetFeedUseCase(fakeRepository),
        RefreshFeedUseCase(fakeRepository),
    )

    @Test
    fun `首屏加载成功后状态带数据`() = runTest {
        fakeRepository.feedResult = Result.Success(listOf(createArticle("a-1")))

        val viewModel = createViewModel()
        advanceUntilIdle()      // StandardTestDispatcher 需要手动推进虚拟时间

        val state = viewModel.uiState.value
        assertThat(state.isLoading).isFalse()
        assertThat(state.articles).hasSize(1)
    }

    @Test
    fun `加载失败时状态带错误`() = runTest {
        fakeRepository.feedResult = Result.Failure(
            com.techfeed.core.model.AppError.Network(cause = RuntimeException("boom")),
        )

        val viewModel = createViewModel()
        advanceUntilIdle()

        assertThat(viewModel.uiState.value.error).isNotNull()
        assertThat(viewModel.uiState.value.articles).isEmpty()
    }

    @Test
    fun `点击文章发出导航事件`() = runTest {
        val viewModel = createViewModel()

        // Turbine：逐个断言 Flow 发射的事件
        viewModel.events.test {
            viewModel.onArticleClick("a-42")
            val event = awaitItem()
            assertThat(event).isInstanceOf(FeedEvent.NavigateToDetail::class.java)
            assertThat((event as FeedEvent.NavigateToDetail).articleId).isEqualTo("a-42")
            cancelAndConsumeRemainingEvents()   // ⚠️ 不调用会报"还有未消费事件"
        }
    }

    @Test
    fun `重复刷新只保留最后一次`() = runTest {
        val viewModel = createViewModel()
        viewModel.onRefresh()
        viewModel.onRefresh()      // 第二次应取消第一次
        advanceUntilIdle()

        assertThat(fakeRepository.completedCount).isEqualTo(1)
        assertThat(fakeRepository.cancelledCount).isEqualTo(1)
    }

    private fun createArticle(id: String) = Article(
        id = id, title = "标题-$id", summary = "摘要", coverUrl = null,
        author = com.techfeed.core.model.Author("au", "作者", null),
        publishedAt = 1_700_000_000L,
    )
}

/** Fake 只实现接口 FeedRepository —— 接口才是可替换的边界 */
private class FakeFeedRepository : FeedRepository {
    var feedResult: Result<List<Article>> = Result.Success(emptyList())
    var completedCount = 0
    var cancelledCount = 0

    override suspend fun getFeed(): Result<List<Article>> = feedResult

    override suspend fun refresh(page: Int): Result<Unit> {
        try {
            kotlinx.coroutines.delay(1_000)    // 虚拟时间，runTest 会瞬间跳过
            completedCount++
            return Result.Success(Unit)
        } catch (e: kotlinx.coroutines.CancellationException) {
            cancelledCount++
            throw e
        }
    }
}

// 文件路径：docs/samples/ch11/RetryTest.kt
package com.techfeed.core.common

import com.google.common.truth.Truth.assertThat
import kotlinx.coroutines.ExperimentalCoroutinesApi
import kotlinx.coroutines.test.advanceTimeBy
import kotlinx.coroutines.test.runTest
import org.junit.Test

@OptIn(ExperimentalCoroutinesApi::class)
class RetryTest {

    @Test
    fun `重试三次后成功`() = runTest {
        var attempts = 0
        val result = retryWithTimeout(times = 3, initialDelayMs = 500) {
            attempts++
            if (attempts < 3) error("失败") else "成功"
        }
        assertThat(result).isEqualTo("成功")
        assertThat(attempts).isEqualTo(3)
    }

    @Test
    fun `延迟可被虚拟时间跳过`() = runTest {
        var finished = false
        kotlinx.coroutines.launch {
            kotlinx.coroutines.delay(10_000)
            finished = true
        }
        advanceTimeBy(10_000)     // 不用真等 10 秒，测试瞬间完成
        assertThat(finished).isTrue()
    }
}

2.13 把回调式 SDK 包装成 suspend

// 文件路径：docs/samples/ch11/SuspendBridge.kt
package com.techfeed.core.common

import kotlinx.coroutines.suspendCancellableCoroutine
import kotlin.coroutines.resume
import kotlin.coroutines.resumeWithException

/** 假设这是第三方 SDK 的回调接口：无法修改，且回调在它自己的线程池 */
interface LegacyCallback<T> {
    fun onSuccess(value: T)
    fun onError(error: Throwable)
}

interface LegacySdk {
    fun fetch(id: String, callback: LegacyCallback<String>)
}

/**
 * suspendCancellableCoroutine：把一次性回调变成可取消的 suspend 函数。
 * ⚠️ 三个要点：
 * 1. 用 suspendCancellableCoroutine 而非 suspendCoroutine —— 前者才支持取消
 * 2. 只在未取消时 resume，否则会抛 IllegalStateException
 * 3. invokeOnCancellation 里要释放资源 / 注销回调
 */
suspend fun LegacySdk.awaitFetch(id: String): String = suspendCancellableCoroutine { cont ->
    val callback = object : LegacyCallback<String> {
        override fun onSuccess(value: String) {
            if (cont.isActive) cont.resume(value)
        }
        override fun onError(error: Throwable) {
            if (cont.isActive) cont.resumeWithException(error)
        }
    }
    fetch(id, callback)
    cont.invokeOnCancellation { /* 取消时：注销回调或标记作废 */ }
}

[!TIP] 这是把老 SDK 接入协程体系的标准姿势：一次性回调用 suspendCancellableCoroutine， 持续性回调用 callbackFlow。两者都支持结构化取消，是替换 CountDownLatch 等阻塞桥接的正确方式。

// 旧写法：AsyncTask —— 内部类持有 Activity 引用导致泄漏，配置变更后结果丢失，已被弃用
private class LoadTask extends AsyncTask<Void, Void, List<Article>> {
    protected List<Article> doInBackground(Void... v) { return api.load(); }
    protected void onPostExecute(List<Article> data) { adapter.submitList(data); }  // 泄漏 Activity
}

// 过渡写法：LiveData —— 生命周期安全，但只在主线程 setter、无线程切换能力、操作符贫乏
val articles: LiveData<List<Article>> = repository.observeArticles()
viewModel.articles.observe(viewLifecycleOwner) { adapter.submitList(it) }
// 想做"搜索防抖 + 请求取消"？LiveData 需要 switchMap + MediatorLiveData，写法冗长且难以测试

三、常见坑 ⚠️

四、调试技巧

1. 开启协程调试开关：VM 参数 -Dkotlinx.coroutines.debug=on（第 01 章），线程名会带上 @coroutine#3， 看堆栈时能一眼分清是哪个协程。
2. 打印当前上下文：

   println("thread=${Thread.currentThread().name}, dispatcher=${coroutineContext[ContinuationInterceptor]}, job=${coroutineContext[Job]}")
   

3. 协程调试面板：Android Studio 的 Run → Debugging → Coroutines（较新版本）可查看协程树与挂起点。
4. 检测泄漏的协程：StrictMode / LeakCanary 对"页面销毁后仍在跑的任务"很有帮助（第 18 章）。
5. Profiler 看线程：Profiler → CPU 中新建的 coroutine 线程名形如 DefaultDispatcher-worker-1， 主线程出现长条绿色（Running）就说明有耗时操作跑错了线程。
6. Flow 打点：调试期用 onEach { log(it) } / onStart / onCompletion 观察发射时机，别用 println 污染生产代码。
7. 测试不确定时：runTest 结束会报 UncompletedCoroutinesError，这恰好是它帮你抓出了"有协程没跑完"的问题—— 别用 runBlocking 绕过，去修真正的原因。
8. adb 验证 ANR：/data/anr/traces.txt（需 root 或用 adb bugreport），主线程堆栈卡在哪个方法就是元凶。

五、最佳实践

1. 协程必须挂在有明确生命周期的 Scope 上：viewModelScope / lifecycleScope；GlobalScope 视为 CR 不通过。
2. suspend 函数要主线程安全：内部自行 withContext，调用方不必关心线程。
3. Dispatcher 用注入而非硬编码：DispatcherProvider 让测试可以替换成 TestDispatcher。
4. CancellationException 永不吞：catch (e: CancellationException) { throw e } 写在所有 catch (Exception) 之前。
5. 并发聚合用 coroutineScope + async，容错场景用 supervisorScope；选择依据是业务语义而非习惯。
6. UI 状态用 StateFlow，一次性事件用 SharedFlow(replay = 0)：这是 UiState + Event 双通道的基础。
7. 共享冷流用 stateIn(WhileSubscribed(5000))：避免旋转屏幕导致上游反复启停。
8. CPU 密集用 Default，阻塞 I/O 用 IO：混用会让线程池被占满，排查起来非常痛苦。
9. 收集 Flow 必须生命周期感知：Compose 用 collectAsStateWithLifecycle，View 用 repeatOnLifecycle(STARTED)。
10. 测试用 runTest + Turbine + TestDispatcher：不写 sleep，不依赖真实时序。
11. 回调 API 一律包成 callbackFlow 并 awaitClose：让第三方 SDK 也享受结构化并发。
12. 限流高并发：批量任务用 Semaphore 或 Flow 的背压机制，不要无脑 launch 上万个协程。

六、本章小结

1. 结构化并发是协程的第一原则：协程成树、父亡子亡、GlobalScope 是反模式——它把"页面销毁后更新 UI"这类崩溃从根源消灭。
2. Job 与 SupervisorJob 决定失败是否连坐：全成全败用 coroutineScope，部分可用用 supervisorScope；选哪个是业务决策。
3. 异常处理三件事：launch 内部 try/catch、CoroutineExceptionHandler 只兜底根协程、CancellationException 必须重抛。
4. 冷流与热流分工明确：冷流（Room/网络）每次收集重跑，靠 stateIn 共享；StateFlow 承载状态、SharedFlow(replay=0) 承载事件。
5. 可测试性是协程的巨大红利：runTest 跳过真实等待、TestDispatcher 消除不确定性、Turbine 让 Flow 断言可读——异步代码第一次变得像同步代码一样好测。

上一章衔接：第 10 章 数据存储 里 Room 返回的 Flow<List<Article>>， 正是本章 stateIn 与 collectAsStateWithLifecycle 的上游。 下一章：这些 ViewModel、Repository、UseCase 目前都是手动 new 出来的——进入 第 12 章 依赖注入：Hilt，学习如何让框架替你装配依赖，并在测试中一键替换成 Fake。

七、动手练习

基础题

1. 写 suspend fun loadTwoPages(): List<Article>，用 coroutineScope + async 并发请求第 1、2 页并合并结果，验证总耗时接近单页耗时而非两倍。
2. 给上面的并发聚合补一个测试：让第 2 页抛异常，验证第 1 页的请求被取消（提示：在 Fake 中记录 CancellationException）。
3. 把 MutableStateFlow 换成 EventFlow，写一个 Turbine 测试验证"页面重建后不会收到历史 Toast 事件"。

进阶题 4. 实现搜索防抖：输入框 → debounce(300) → distinctUntilChanged() → flatMapLatest。用 Turbine 验证"输入 a、ab、abc 后只发出一次 abc 的请求"。 5. 实现一个带并发上限的批量上传器：Semaphore(3) 限流 20 个文件，并在任一个失败时用 SupervisorJob 保证其余继续上传，最后汇总成功/失败数量。 6. 用 callbackFlow 封装一个"模拟蓝牙扫描回调"的 SDK（每 200ms 回调一个设备），要求：收集停止时回调必须注销，写一个测试证明没有泄漏。

思考题 7. 为什么 CoroutineExceptionHandler 装在子协程上不生效？这种设计是想逼你形成什么样的编码习惯？ 8. StateFlow 的 WhileSubscribed(5000) 为什么是 5 秒而不是 0 秒？如果用户切到后台 10 秒再回来，你会观察到什么行为？ 9. 一个 suspend 函数内部既做了网络请求又做了大 JSON 解析，withContext 应该用 IO 还是 Default？分两段写又如何？ 10. 为什么 runTest 在结束时要检查"是否有未完成的协程"？如果它不检查，你会错过哪些真实 bug？

📄 第 12 章 依赖注入：Hilt 12-dependency-injection-hilt.md✓ 标记已学

阶段：进阶 ｜ 预计阅读 60 min ｜ 代码落地模块：:app、:core:network、:core:database、:feature:feed 前置：第 02 章 工程结构与 Gradle ｜ 第 10 章 数据存储 ｜ 第 11 章 协程与 Flow 相关章节：第 13 章 后台任务与通知 ｜ 第 15 章 模块化与组件化 ｜ 第 21 章 测试策略

学习目标

• [ ] 说清依赖注入（Dependency Injection, DI）解决什么问题，以及它与"工厂""单例""服务定位器"的本质区别。
• [ ] 掌握 Hilt 的核心注解：@HiltAndroidApp、@AndroidEntryPoint、@Inject、@Module、@Provides、@Binds、@Qualifier、@EntryPoint。
• [ ] 理解 Hilt 作用域与 Android 生命周期的对应关系，能判断一个对象该用 @Singleton 还是 @ViewModelScoped。
• [ ] 能在多模块工程中分层装配 DI：core 模块提供实现，feature 模块只依赖接口。
• [ ] 会用 @BindValue / @UninstallModules / HiltAndroidRule 在测试中替换依赖，并理解 Hilt 与 Koin 的取舍。

一、核心概念

1.1 为什么需要依赖注入

先看没有 DI 时代码的典型形态：

class FeedViewModel : ViewModel() {
    // 自己 new 依赖 → 要知道 Retrofit 怎么建、OkHttp 怎么配、DAO 从哪来
    private val repository = FeedRepository(
        remote = FeedRemoteDataSource(RetrofitProvider.api),
        local = AppDatabaseProvider.get(application).articleDao(),
    )
}

问题有四：

1. 构造知识泄漏：ViewModel 不该知道 Retrofit 的存在，却被它绑架。
2. 无法测试：想换成 Fake，要么改源码，要么借助反射/服务定位器 hack。
3. 生命周期错配：谁负责保证 OkHttpClient 全局唯一？靠自觉，而自觉不可靠。
4. 改动涟漪：新增一个参数，所有 new 出来的地方全要改。

依赖注入的核心思想只有一句：对象不自己创建依赖，而是声明"我需要什么"，由外部把它需要的东西送进来。

flowchart TB
    subgraph Before["无 DI：自己造依赖"]
        A1["FeedViewModel"] --> B1["new FeedRepository()"]
        B1 --> C1["new Retrofit()"]
        C1 --> D1["new OkHttpClient()"]
    end
    subgraph After["有 DI：声明需求，框架装配"]
        A2["FeedViewModel<br/>@Inject constructor(repo)"] -.->|"声明需要"| H["Hilt 依赖图"]
        H --> B2["FeedRepository"]
        H --> C2["Retrofit"]
        H --> D2["OkHttpClient"]
        H --> E2["ArticleDao"]
    end

1.2 三种"送进来"的方式

[!IMPORTANT] 还有两种常被误当作 DI 的反模式： 服务定位器（ServiceLocator.get<Repo>()）——依赖被隐藏在方法体里，编译期看不出依赖，测试要重置全局状态； 全局单例（object RepositoryProvider）——生命周期不可控、无法替换、无法销毁。 它们的共同问题是：把"依赖"从编译期可见的契约退化为运行期的隐式约定。

1.3 Hilt 是什么

Hilt 是 Google 在 Dagger 之上封装的 Android 专用 DI 框架。它做了三件事：

1. 预定义组件（Component）与作用域：不用你自己写 @Component、@Subcomponent。
2. 预定义注入入口：Activity、Fragment、View、Service、BroadcastReceiver、ViewModel、WorkManager 的 Worker 都能直接注入。
3. 编译期生成代码：与 Dagger 一样是编译期校验，依赖缺失在编译时就报错，而不是运行时 null。

1.4 核心注解速查

1.5 作用域与生命周期：Hilt 最需要背下来的一张表

作用域的本质是"这个对象在谁的生命周期内保持同一个实例"。

flowchart TB
    S["SingletonComponent<br/>@Singleton"] --> AR["ActivityRetainedComponent<br/>@ActivityRetainedScoped"]
    AR --> A["ActivityComponent<br/>@ActivityScoped"]
    A --> F["FragmentComponent<br/>@FragmentScoped"]
    A --> V["ViewComponent"]
    AR --> VM["ViewModelComponent<br/>@ViewModelScoped"]
    S --> SC["ServiceComponent<br/>@ServiceScoped"]

[!WARNING] 作用域越大，对象的存活越久，内存占用也越高。能用小作用域就用小作用域： 把带 Context 的对象标成 @Singleton 是内存泄漏的经典来源（Activity Context 被长生命周期对象持有）。

1.6 多模块下的 DI 装配

Hilt 的组件是全局聚合的：每个模块里 @InstallIn(SingletonComponent::class) 的 Module，在编译期会被合并进同一个依赖图。这带来两个好处与一个纪律：

• 好处：:core:network 提供 OkHttpClient，:feature:feed 直接注入即可，不需要 feature 依赖 network 的实现细节。
• 好处：模块间不需要互相 include，装配是自动的。
• 纪律：feature 模块之间不应互相依赖（第 15 章）；共享的东西下沉到 core 模块，由 core 的 Module 提供。

:app            ← @HiltAndroidApp，聚合所有模块
 ├─ :feature:*  ← 只依赖 core，注入 core 提供的接口
 └─ :core:*     ← @InstallIn(SingletonComponent) 提供实现

1.7 与 Koin 的对比

[!TIP] 选型的实际判据：团队规模与项目寿命。5 人以上、维护 3 年以上的项目，编译期校验省下的线上事故远超学习成本； 而 KMP（Kotlin Multiplatform）项目由于要跨平台共享，通常选 Koin 或手动 DI。本书统一用 Hilt。

二、示例代码

2.1 依赖与插件

// 文件路径：sample/build.gradle.kts（根工程，声明插件版本由 libs.versions.toml 收口）
plugins {
    alias(libs.plugins.hilt) apply false
    alias(libs.plugins.ksp) apply false
}

// 文件路径：sample/app/build.gradle.kts
plugins {
    alias(libs.plugins.android.application)
    alias(libs.plugins.kotlin.android)
    alias(libs.plugins.kotlin.compose)
    alias(libs.plugins.ksp)        // Hilt 用 KSP 生成代码，不用 kapt
    alias(libs.plugins.hilt)
}

dependencies {
    implementation(libs.hilt.android)
    ksp(libs.hilt.compiler)                       // 注解处理器
    implementation(libs.androidx.hilt.navigation.compose)  // hiltViewModel() 支持
    // 测试替换
    androidTestImplementation(libs.hilt.android.testing)
    kspAndroidTest(libs.hilt.compiler)
}

[!NOTE] Hilt 依赖图是跨模块聚合的，但聚合发生在 :app 模块（有 @HiltAndroidApp 的那个）。 因此 :app 必须直接或间接依赖所有带 @InstallIn 模块的工程模块，否则该模块里的 Module 不会进图—— 这是"注入时报 Unresolved reference / 找不到 Provider"的常见原因。

2.2 Application：启动 DI 容器

// 文件路径：sample/app/src/main/java/com/techfeed/app/TechFeedApplication.kt
package com.techfeed.app

import android.app.Application
import dagger.hilt.android.HiltAndroidApp

/**
 * 整个 App 必须有且仅有一个 @HiltAndroidApp 的 Application。
 * 它会生成 App 级组件（SingletonComponent），是所有依赖图的根。
 */
@HiltAndroidApp
class TechFeedApplication : Application()

<!-- 文件路径：sample/app/src/main/AndroidManifest.xml -->
<application
    android:name=".TechFeedApplication"
    android:allowBackup="false"
    android:theme="@style/Theme.TechFeed">
    <!-- ... -->
</application>

2.3 Android 类注入：@AndroidEntryPoint

// 文件路径：sample/app/src/main/java/com/techfeed/app/MainActivity.kt
package com.techfeed.app

import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.activity.enableEdgeToEdge
import com.techfeed.core.designsystem.theme.TechFeedTheme
import dagger.hilt.android.AndroidEntryPoint
import javax.inject.Inject

/**
 * @AndroidEntryPoint 让字段注入生效。
 * ⚠️ 规则：注入了 Activity，它附着的 Fragment 也必须加 @AndroidEntryPoint。
 */
@AndroidEntryPoint
class MainActivity : ComponentActivity() {

    // 字段注入只用于"框架创建、无法控制构造"的类
    @Inject lateinit var crashReporter: CrashReporter

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        crashReporter.install()
        enableEdgeToEdge()
        setContent { TechFeedTheme { TechFeedApp() } }
    }
}

2.4 构造函数注入：推荐的主路径

// 文件路径：docs/samples/ch12/GetFeedUseCase.kt
package com.techfeed.feature.feed.domain

import com.techfeed.core.model.Article
import kotlinx.coroutines.flow.Flow
import javax.inject.Inject

/**
 * 无作用域注解 = 每次注入都新建实例。
 * UseCase 无状态、创建成本极低，这正好 —— 不要给无状态类乱加 @Singleton。
 */
class GetFeedUseCase @Inject constructor(
    private val repository: FeedRepository,   // 接口，实现由 core 模块提供（见 2.7）
) {
    operator fun invoke(): Flow<List<Article>> = repository.observeArticles()
}

// 文件路径：sample/feature/feed/src/main/java/com/techfeed/feature/feed/ui/FeedViewModel.kt
package com.techfeed.feature.feed.ui

import androidx.lifecycle.ViewModel
import androidx.lifecycle.viewModelScope
import com.techfeed.feature.feed.domain.GetFeedUseCase
import dagger.hilt.android.lifecycle.HiltViewModel
import kotlinx.coroutines.flow.SharingStarted
import kotlinx.coroutines.flow.StateFlow
import kotlinx.coroutines.flow.map
import kotlinx.coroutines.flow.stateIn
import javax.inject.Inject

/**
 * @HiltViewModel + @Inject constructor：
 * ViewModel 由 Hilt 工厂创建，构造参数自动从依赖图里取。
 * ⚠️ 加了 @HiltViewModel 后，获取方式必须是 hiltViewModel()（Compose）
 *    或 by viewModels()（View 体系，需 @AndroidEntryPoint），不能用 ViewModelProvider 手动 new。
 */
@HiltViewModel
class FeedViewModel @Inject constructor(
    getFeed: GetFeedUseCase,
) : ViewModel() {

    val uiState: StateFlow<FeedUiState> = getFeed()
        .map { articles -> FeedUiState(articles = articles) }
        .stateIn(
            scope = viewModelScope,
            started = SharingStarted.WhileSubscribed(5_000),
            initialValue = FeedUiState(isLoading = true),
        )
}

[!NOTE] FeedViewModel 的构造签名在各章有演进：第 11 章为（getFeed、refreshFeed）两用例构造签名（配合该章的协程与状态管理教学）； 本章示例简化为单用例以聚焦 DI；第 24 章工程实际为 FeedViewModel(repository) 单参签名（演进见各章说明）。

2.5 @Module + @Provides：给"自己造不了"的第三方类

// 文件路径：sample/core/network/src/main/java/com/techfeed/core/network/di/NetworkModule.kt
package com.techfeed.core.network.di

import com.techfeed.core.network.AppJson
import com.techfeed.core.network.TokenProvider
import dagger.Module
import dagger.Provides
import dagger.hilt.InstallIn
import dagger.hilt.components.SingletonComponent
import okhttp3.MediaType.Companion.toMediaType
import okhttp3.OkHttpClient
import retrofit2.Retrofit
import retrofit2.converter.kotlinx.serialization.asConverterFactory
import java.util.concurrent.TimeUnit
import javax.inject.Named
import javax.inject.Singleton

/**
 * @Module：告诉 Hilt "这些对象怎么做出来"。
 * @InstallIn(SingletonComponent)：装进 App 级组件，全进程可见。
 * @Provides 用于第三方类（你改不了它的构造函数）；自己写的类请优先 @Inject constructor。
 */
@Module
@InstallIn(SingletonComponent::class)
object NetworkModule {

    @Provides
    @Singleton          // 连接池与 TLS 会话复用都在 client 上，必须全局唯一
    fun provideOkHttpClient(
        tokenProvider: TokenProvider,      // 参数由依赖图自动填入
    ): OkHttpClient = OkHttpClient.Builder()
        .connectTimeout(10, TimeUnit.SECONDS)
        .callTimeout(30, TimeUnit.SECONDS)
        .addInterceptor { chain ->
            val token = tokenProvider.accessToken()
            val request = chain.request().newBuilder()
                .apply { if (!token.isNullOrBlank()) header("Authorization", "Bearer $token") }
                .build()
            chain.proceed(request)
        }
        .build()

    @Provides
    @Singleton
    fun provideRetrofit(client: OkHttpClient, @Named("base_url") baseUrl: String): Retrofit =
        Retrofit.Builder()
            .baseUrl(baseUrl)
            .client(client)
            .addConverterFactory(AppJson.asConverterFactory("application/json".toMediaType()))
            .build()
}

[!NOTE] 本节 NetworkModule 是为聚焦 DI 讲解的节选，只保留了 @Provides / @Singleton / @Named 相关元素； 生产级完整实现（拦截器链、缓存目录绑定、TokenAuthenticator、redactHeader 脱敏、NetworkConfig.BASE_URL）见第 09 章 §2.5。

2.6 @Qualifier：同类型多实例如何区分

// 文件路径：docs/samples/ch12/Qualifiers.kt
package com.techfeed.core.common.di

import javax.inject.Qualifier

/** 限定符：同一种类型有多个提供者时，用自定义注解区分 */
@Qualifier
@Retention(AnnotationRetention.BINARY)
annotation class BaseUrl

@Qualifier
@Retention(AnnotationRetention.BINARY)
annotation class IoDispatcher

@Qualifier
@Retention(AnnotationRetention.BINARY)
annotation class DefaultDispatcher

@Qualifier
@Retention(AnnotationRetention.BINARY)
annotation class Authenticated      // 带鉴权头的 client

// 文件路径：sample/core/common/src/main/java/com/techfeed/core/common/di/DispatcherModule.kt
package com.techfeed.core.common.di

import dagger.Module
import dagger.Provides
import dagger.hilt.InstallIn
import dagger.hilt.components.SingletonComponent
import kotlinx.coroutines.CoroutineDispatcher
import kotlinx.coroutines.Dispatchers

@Module
@InstallIn(SingletonComponent::class)
object DispatcherModule {
    // 用限定符提供三个不同的 CoroutineDispatcher —— 它们的类型完全相同
    @Provides @IoDispatcher
    fun provideIo(): CoroutineDispatcher = Dispatchers.IO

    @Provides @DefaultDispatcher
    fun provideDefault(): CoroutineDispatcher = Dispatchers.Default

    @Provides @BaseUrl
    fun provideBaseUrl(): String = "https://api.techfeed.dev/"
}

注入侧：

// 文件路径：docs/samples/ch12/RefreshFeedUseCase.kt
package com.techfeed.feature.feed.domain

import com.techfeed.core.common.di.IoDispatcher
import com.techfeed.core.model.Result
import kotlinx.coroutines.CoroutineDispatcher
import kotlinx.coroutines.withContext
import javax.inject.Inject

class RefreshFeedUseCase @Inject constructor(
    private val repository: FeedRepository,
    @IoDispatcher private val io: CoroutineDispatcher,   // 限定符指明要哪一个
) {
    suspend operator fun invoke(page: Int = 1): Result<Unit> = withContext(io) {
        repository.refresh(page)
    }
}

[!TIP] @Named("base_url") 是 Hilt 内置的限定符，但字符串没有编译期校验，写错只能在运行时报错。 自定义 @Qualifier 注解是更安全的做法：写错名字直接编译不过。

2.7 @Binds：接口绑定到实现

// 文件路径：docs/samples/ch12/RepositoryModule.kt
package com.techfeed.core.database.di

import com.techfeed.feature.feed.domain.FeedRepository
import com.techfeed.core.database.repository.OfflineFirstFeedRepository
import dagger.Binds
import dagger.Module
import dagger.hilt.InstallIn
import dagger.hilt.components.SingletonComponent
import javax.inject.Singleton

/**
 * @Binds 把实现类型映射到接口：
 * - 必须是 abstract 方法（或 abstract class 模块）
 * - 参数类型必须能赋值给返回类型
 * - 比 @Provides 生成的代码更少、更快（无工厂方法调用）
 */
@Module
@InstallIn(SingletonComponent::class)
abstract class RepositoryModule {

    @Binds
    @Singleton
    abstract fun bindFeedRepository(impl: OfflineFirstFeedRepository): FeedRepository
}

[!IMPORTANT] 这里有一个关键的架构约定：接口 FeedRepository 定义在 :feature:feed（或 :core:navigation-api 这类 API 模块）， 实现 OfflineFirstFeedRepository 在 :core:database。 于是 feature 只依赖接口、不依赖实现，实现可以被测试 Fake 一键替换。这就是依赖倒置（第 15 章展开）。

2.8 作用域实战：什么时候用 @ViewModelScoped

// 文件路径：docs/samples/ch12/DetailStateHolder.kt
package com.techfeed.feature.detail.ui

import dagger.hilt.android.lifecycle.ViewModelScoped
import kotlinx.coroutines.flow.MutableStateFlow
import javax.inject.Inject

/**
 * @ViewModelScoped：同一个 ViewModel 实例内共享，ViewModel 销毁即释放。
 * 适合"与页面强相关、但仍需独立成类"的对象（分页器、表单草稿、滚动状态容器）。
 * ⚠️ 它内部不能持有 Activity/Fragment/View，否则必泄漏。
 */
@ViewModelScoped
class DetailScrollHolder @Inject constructor() {
    val scrollOffset = MutableStateFlow(0)
    fun onScroll(delta: Int) { scrollOffset.value += delta }
}

// 文件路径：docs/samples/ch12/LoginFlowController.kt
package com.techfeed.feature.auth

import dagger.hilt.android.scopes.ActivityRetainedScoped
import kotlinx.coroutines.flow.MutableStateFlow
import javax.inject.Inject

/**
 * @ActivityRetainedScoped：旋转屏幕后仍是同一个实例，但 Activity 真正销毁时释放。
 * 适合"跨配置变更保留、但不该活到 App 结束"的多步流程（如登录向导、发布流程）。
 */
@ActivityRetainedScoped
class LoginFlowController @Inject constructor() {
    private val _step = MutableStateFlow(LoginStep.Phone)
    val step: kotlinx.coroutines.flow.StateFlow<LoginStep> get() = _step
    fun next() { /* 推进流程 */ }
}

2.9 @EntryPoint：在非 Hilt 类中拿到依赖

// 文件路径：docs/samples/ch12/CrashEntryPoint.kt
package com.techfeed.core.crash

import dagger.hilt.EntryPoint
import dagger.hilt.InstallIn
import dagger.hilt.components.SingletonComponent

/**
 * 有些类 Hilt 管不了（如 ContentProvider、自定义 View 的构造、第三方 SDK 回调）。
 * 用 @EntryPoint 开一个"后门"显式取依赖，比把它做成全局单例干净得多。
 */
@EntryPoint
@InstallIn(SingletonComponent::class)
interface CrashEntryPoint {
    fun crashReporter(): CrashReporter
}

// 使用处
fun Context.crashReporter(): CrashReporter =
    dagger.hilt.android.EntryPointAccessors.fromApplication(
        applicationContext, CrashEntryPoint::class.java,
    ).crashReporter()

2.10 多模块装配全景

flowchart TB
    subgraph App["':app'"]
        A["TechFeedApplication<br/>@HiltAndroidApp"]
    end
    subgraph Core["':core:*' 提供实现"]
        N["NetworkModule<br/>@InstallIn(Singleton)"]
        D["DatabaseModule<br/>@InstallIn(Singleton)"]
        S["DataStoreModule<br/>@InstallIn(Singleton)"]
    end
    subgraph Feature["':feature:*' 只注入接口"]
        F1["':feature:feed'<br/>FeedViewModel"]
        F2["':feature:auth'<br/>LoginViewModel"]
    end
    A --> N
    A --> D
    A --> S
    N --> F1
    D --> F1
    S --> F2
    F1 -.->|"依赖 :core:model / :core:navigation-api"| Core
    F1 -.->|"零依赖"| F2

[!WARNING] feature 模块之间不允许互相依赖。若 :feature:feed 需要跳到 :feature:detail， 应依赖 :core:navigation-api 中定义的路由接口，由 :app 装配实现（第 15 章）。 DI 层面同理：跨 feature 共享的对象必须下沉到 core。

2.11 UI 双体系：两种获取 ViewModel 的方式

// 文件路径：sample/feature/feed/src/main/java/com/techfeed/feature/feed/ui/FeedScreen.kt
package com.techfeed.feature.feed.ui

import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.lifecycle.compose.collectAsStateWithLifecycle
import androidx.hilt.navigation.compose.hiltViewModel

/** Compose：hiltViewModel() 从 Hilt 工厂取 ViewModel（需 androidx.hilt:hilt-navigation-compose） */
@Composable
fun FeedScreen(
    modifier: Modifier = androidx.compose.ui.Modifier,
    viewModel: FeedViewModel = hiltViewModel(),     // 默认参数方便 Preview 传入 Fake
) {
    val uiState by viewModel.uiState.collectAsStateWithLifecycle()
    FeedContent(uiState = uiState, modifier = modifier)
}

// 文件路径：docs/samples/ch12/FeedFragment.kt
package com.techfeed.feature.feed.ui

import android.os.Bundle
import android.view.LayoutInflater
import android.view.View
import android.view.ViewGroup
import androidx.fragment.app.Fragment
import androidx.fragment.app.viewModels
import androidx.lifecycle.Lifecycle
import androidx.lifecycle.lifecycleScope
import androidx.lifecycle.repeatOnLifecycle
import com.techfeed.feature.feed.databinding.FragmentFeedBinding
import dagger.hilt.android.AndroidEntryPoint
import kotlinx.coroutines.launch

/** View 体系：@AndroidEntryPoint + by viewModels()，两者缺一不可 */
@AndroidEntryPoint
class FeedFragment : Fragment() {

    private var _binding: FragmentFeedBinding? = null
    private val binding get() = requireNotNull(_binding)

    // 只有加了 @AndroidEntryPoint，Hilt 才会给 ViewModel 提供构造参数
    private val viewModel: FeedViewModel by viewModels()

    override fun onCreateView(inflater: LayoutInflater, container: ViewGroup?, saved: Bundle?): View {
        _binding = FragmentFeedBinding.inflate(inflater, container, false)
        return binding.root
    }

    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        super.onViewCreated(view, savedInstanceState)
        viewLifecycleOwner.lifecycleScope.launch {
            viewLifecycleOwner.repeatOnLifecycle(Lifecycle.State.STARTED) {
                viewModel.uiState.collect { state -> render(state) }
            }
        }
    }

    private fun render(state: FeedUiState) {
        binding.tvEmpty.isVisible = state.articles.isEmpty()
    }

    override fun onDestroyView() {
        _binding = null      // ⚠️ 必须置空
        super.onDestroyView()
    }
}

2.12 测试替换：三种手段

手段一（首选）：单元测试根本不用 Hilt。 因为构造函数注入，直接 new Fake 即可。

// 文件路径：sample/feature/feed/src/test/java/com/techfeed/feature/feed/ui/FeedViewModelTest.kt
package com.techfeed.feature.feed.ui

import app.cash.turbine.test
import com.google.common.truth.Truth.assertThat
import com.techfeed.core.testing.MainDispatcherRule
import kotlinx.coroutines.flow.flowOf
import kotlinx.coroutines.test.runTest
import org.junit.Rule
import org.junit.Test

/** 构造函数注入的最大收益：测试里不需要任何 DI 框架 */
class FeedViewModelTest {

    // viewModelScope 使用 Dispatchers.Main，必须先用 Rule 替换成测试调度器
    @get:Rule
    val mainDispatcherRule = MainDispatcherRule()

    @Test
    fun `ViewModel 直接接收 Fake`() = runTest {
        // GetFeedUseCase 是 final class，不能被匿名 object 继承——
        // 正确做法：伪造接口 FeedRepository，再真实构造 UseCase 套在外面
        val fake = com.techfeed.feature.feed.domain.GetFeedUseCase(
            repository = FakeFeedRepository(),
        )
        val viewModel = FeedViewModel(fake)

        // ⚠️ WhileSubscribed 的 StateFlow：没有收集者时上游根本不启动，
        // value 永远停在 initialValue（articles 为空）——直接断言非空必失败。
        // 必须先订阅（Turbine 的 test 即订阅），再断言数据流出。
        viewModel.uiState.test {
            assertThat(awaitItem().isLoading).isTrue()      // 第一个值是 initialValue
            assertThat(awaitItem().articles).isNotEmpty()    // 订阅后上游才发射真实数据
            cancelAndIgnoreRemainingEvents()
        }
    }
}

private class FakeFeedRepository : com.techfeed.feature.feed.domain.FeedRepository {
    override fun observeArticles() = flowOf(
        listOf(
            com.techfeed.core.model.Article(
                id = "a-1", title = "t", summary = "", coverUrl = null,
                author = com.techfeed.core.model.Author("au", "n", null), publishedAt = 0L,
            ),
        ),
    )
    override suspend fun refresh(page: Int) = com.techfeed.core.model.Result.Success(Unit)
    override suspend fun toggleFavorite(id: String) = com.techfeed.core.model.Result.Success(Unit)
}

手段二（仪器化测试）：@UninstallModules + @BindValue。

// 文件路径：docs/samples/ch12/FeedFragmentTest.kt
package com.techfeed.feature.feed.ui

import androidx.test.ext.junit.runners.AndroidJUnit4
import com.techfeed.feature.feed.domain.FeedRepository
import dagger.hilt.android.testing.BindValue
import dagger.hilt.android.testing.HiltAndroidRule
import dagger.hilt.android.testing.HiltAndroidTest
import dagger.hilt.android.testing.UninstallModules
import org.junit.Before
import org.junit.Rule
import org.junit.Test
import org.junit.runner.RunWith
import javax.inject.Inject

@RunWith(AndroidJUnit4::class)
@HiltAndroidTest
// 卸载生产模块，避免真实网络/数据库被拉起
@UninstallModules(com.techfeed.core.database.di.RepositoryModule::class)
class FeedFragmentTest {

    @get:Rule
    val hiltRule = HiltAndroidRule(this)   // ⚠️ Rule 必须在 @Before 之前声明

    // @BindValue 把 Fake 塞进依赖图，替代被卸载模块提供的 FeedRepository
    @BindValue
    @JvmField
    val fakeRepository: FeedRepository = FakeFeedRepository()

    @Inject lateinit var okHttpClient: okhttp3.OkHttpClient   // 验证注入是否成功

    @Before
    fun setUp() {
        hiltRule.inject()      // ⚠️ 别漏了这行，否则 @Inject 字段为 null
    }

    @Test
    fun 列表渲染出假数据() {
        // 启动 Fragment 并断言
    }
}

手段三（可复用）：@TestInstallIn。 适合多个测试共用的 Fake 模块。

// 文件路径：docs/samples/ch12/TestRepositoryModule.kt
package com.techfeed.core.testing

import com.techfeed.feature.feed.domain.FeedRepository
import dagger.Binds
import dagger.Module
import dagger.hilt.components.SingletonComponent
import dagger.hilt.testing.TestInstallIn
import javax.inject.Singleton

/** @TestInstallIn = @InstallIn + 自动替换指定的生产模块，无需在每个测试类上写 @UninstallModules */
@Module
@TestInstallIn(
    components = [SingletonComponent::class],
    replaces = [com.techfeed.core.database.di.RepositoryModule::class],
)
abstract class TestRepositoryModule {
    @Binds
    @Singleton
    abstract fun bindFakeFeedRepository(impl: FakeFeedRepository): FeedRepository
}

// 旧写法：原生 Dagger 需要手写 Component / Subcomponent / Builder，样板代码极多
@Singleton
@Component(modules = [NetworkModule::class, DatabaseModule::class])
interface AppComponent {
    fun inject(activity: MainActivity)
    fun activityComponentBuilder(): ActivityComponent.Builder
}
// 每个 Activity 都要写 Subcomponent + Builder + 手动 inject()

// 更早的"服务定位器"：依赖藏在运行期，编译期看不出来，测试要重置全局状态
object ServiceLocator {
    lateinit var repository: FeedRepository
}

三、常见坑 ⚠️

四、调试技巧

1. 读编译错误：Hilt 的错误信息非常有信息量，格式是 [Dagger/MissingBinding] 或 [Dagger/DuplicateBindings]， 并且自带依赖链（com.techfeed.FeedRepository is requested at ...）。从最下面一行往上读最快。
2. 看生成代码：build/generated/ksp/debug/kotlin/... 下有 *_HiltModules、*_Factory， 搞清楚"到底生成了什么"，很多疑惑会立刻解开。
3. 生成依赖图：Dagger 支持输出可视化图（需在构建中开启），能直观看到组件与绑定的关系。
4. Logcat 过滤 Hilt：注入失败、组件未初始化等问题会在这里留痕。
5. 确认模块是否入图：临时把某个 @Provides 的返回类型打印日志，或故意在 @Inject 处写一个不存在的依赖看报错链。
6. 单元测试优先绕开 Hilt：如果某个类的测试必须启动 Hilt 才能写，多半说明它该改成构造函数注入。
7. ./gradlew :app:kspDebugKotlin --info：KSP 阶段报错时用它看完整堆栈。

五、最佳实践

1. 构造函数注入优先：自己写的类一律 @Inject constructor，@Provides 只留给第三方类。
2. 面向接口注入：业务类依赖 FeedRepository 接口，实现在 core 模块用 @Binds 绑定——这是可测试性的前提。
3. 作用域从大到小收敛：默认不加作用域；确实需要复用才加，且优先选更小的（@ViewModelScoped 优于 @Singleton）。
4. 自定义 @Qualifier 而不是 @Named：编译期校验能消灭拼写错误。
5. Context 一律 @ApplicationContext：除非你明确需要 Activity 上下文（且此时作用域不能大于 Activity）。
6. Module 按模块归属放：:core:network 的 Module 放 :core:network，不要堆在 :app。
7. feature 之间零依赖：共享对象下沉 core，跳转走 :core:navigation-api。
8. 测试不用 Hilt：构造函数注入让单元测试可以直接 new Fake；只有仪器化测试才用 @UninstallModules / @TestInstallIn。
9. @Binds 优于 @Provides：生成代码更少、运行更快。
10. 别给无状态类加 @Singleton：UseCase、Mapper 每次新建的成本远低于常驻内存的成本。

六、本章小结

1. DI 的本质是把"创建依赖"的职责外移：构造函数注入是最干净的形式，服务定位器与全局单例是反模式。
2. Hilt 是 Dagger 的 Android 封装：@HiltAndroidApp 建根、@AndroidEntryPoint 开注入点、@Module + @InstallIn 提供第三方对象。
3. 作用域必须与生命周期匹配：@Singleton 跨进程、@ActivityRetainedScoped 跨旋转、@ViewModelScoped 随 ViewModel；作用域越大越危险。
4. 多模块靠依赖倒置装配：接口在 feature（或 API 模块），实现在 core，用 @Binds 连接；feature 之间零依赖。
5. 可测试性是 DI 的最大红利：构造函数注入让单测无需框架；仪器化测试用 @UninstallModules / @TestInstallIn 一键换 Fake。

上一章衔接：第 11 章 协程与 Flow 中的 DispatcherProvider、Repository、UseCase 在真实工程里正是由 Hilt 装配的。 下一章：有些任务不该绑在页面上——进入 第 13 章 后台任务与通知， 学习用 WorkManager 做可靠的后台任务，以及通知渠道、运行时权限与推送通道抽象。

七、动手练习

基础题

1. 给 :core:datastore 加一个 DataStoreModule，用 @Provides @Singleton 提供 DataStore<Preferences>，并在 :feature:profile 的 ViewModel 中注入它。
2. 定义 @Qualifier 注解 @Authenticated 与 @Anonymous，提供两个不同的 OkHttpClient（一个带鉴权拦截器、一个不带），并在两个 Api 中分别注入。
3. 把 FeedRepository 改成接口（已定义），用 @Binds 在 :core:database 中绑定实现，验证 :feature:feed 不再依赖 :core:database 的实现类。

进阶题 4. 把一个多步"发布文章"流程的状态抽成 @ActivityRetainedScoped 的 PublishFlowController，验证旋转屏幕后流程步骤不丢失，而 Activity 真正销毁后实例被释放。 5. 写一个 @TestInstallIn 的假模块，把 FeedRepository 替换为内存实现，并跑通一个 Fragment 的仪器化测试（不触碰网络与数据库）。 6. 用 @EntryPoint 给一个 ContentProvider（Hilt 无法直接注入的类）提供 CrashReporter，说明为什么这里不能用字段注入。

思考题 7. 为什么 Hilt 要求"注入了 Fragment 就必须注入宿主 Activity"？这与 Fragment 的生命周期有什么关系？ 8. 把一个对象错误地标成 @Singleton 会有哪些后果？除了内存泄漏，还有哪些更隐蔽的问题（提示：状态污染、测试互相干扰）？ 9. 如果团队决定从 Hilt 迁到 Koin（或反之），迁移成本主要在哪？哪些代码是不需要改的（提示：构造函数注入的部分）？ 10. 为什么说"单元测试里需要启动 Hilt"往往是一个设计信号？它提示了类存在什么问题？

📄 第 13 章 后台任务与通知 13-background-work-notifications.md✓ 标记已学

阶段：进阶 ｜ 预计阅读 60 min ｜ 代码落地模块：:feature:push、:core:common、:core:database 前置：第 03 章 应用组件与生命周期 ｜ 第 08 章 Intent、IPC 与权限 ｜ 第 12 章 依赖注入：Hilt 相关章节：第 10 章 数据存储 ｜ 第 19 章 安全加固 ｜ 第 26 章 推送、监控与收尾

学习目标

• [ ] 理解 Android 后台执行限制的演进（Doze、应用待机、后台服务限制），知道"为什么以前的写法现在不管用"。
• [ ] 掌握 WorkManager 的四类任务（一次性、周期、加急、链式）与约束配置，能替代 Service / JobScheduler 实现可靠后台。
• [ ] 会观察任务状态、做重试退避与唯一任务去重，并能为 Worker 写单元测试。
• [ ] 掌握通知渠道（Android 8+）、通知创建、PendingIntent 可变性标志、以及 Android 13+ 的 POST_NOTIFICATIONS 运行时权限。
• [ ] 能设计推送通道抽象：国内 FCM 不可用的现实下，用接口隔离厂商通道，并具备本地通知降级能力。

一、核心概念

1.1 后台执行限制的演进

Android 从 6.0 起系统性地收紧后台权限，目的只有一个：续航。理解这条时间线，就不会再疑惑"为什么我的后台任务不执行了"。

[!IMPORTANT] 关键认知："我的代码想什么时候跑"和"系统允许你什么时候跑"是两件事。 现代 Android 后台任务的正确姿势是——向系统声明"我要做什么、什么条件下做、是否必须立刻做"，由系统统一调度。 WorkManager 就是这个声明的载体。

1.2 为什么不用 Service / JobScheduler

WorkManager 的三个核心保证：

1. 持久化：任务写入本地数据库，进程被杀、设备重启后仍会执行。
2. 约束感知：只在满足条件（有网、充电、空闲）时才跑。
3. 版本自适应：底层自动选择 JobScheduler（API 23+）、GcmNetworkManager（旧版）或自研调度器，你不用关心。

[!WARNING] WorkManager 不适合以下场景：需要精确到秒的闹钟（用 AlarmManager）、 需要持续运行且与用户交互的任务（用前台服务）、下载大文件（用 DownloadManager）。

1.3 WorkManager 的组成

flowchart TB
    A["WorkRequest<br/>任务描述：做什么 + 什么条件下做"] --> B["WorkManager.enqueue()"]
    B --> C[("内部 Room 数据库<br/>任务持久化")]
    C --> D["系统调度器<br/>JobScheduler / GCMNM / AlarmManager"]
    D --> E{"约束满足?"}
    E -->|"否"| D
    E -->|"是"| F["Worker.doWork()<br/>你的代码"]
    F --> G["Result.success / failure / retry"]
    G --> H["WorkInfo 状态更新"]
    H --> I["UI 通过 Flow 观察"]

任务状态机：

stateDiagram-v2
    [*] --> ENQUEUED : enqueue()
    ENQUEUED --> BLOCKED : 约束未满足
    BLOCKED --> ENQUEUED : 约束满足
    ENQUEUED --> RUNNING
    RUNNING --> SUCCEEDED : Result.success()
    RUNNING --> FAILED : Result.failure()
    RUNNING --> ENQUEUED : Result.retry()
    ENQUEUED --> CANCELLED : cancelWorkById()
    RUNNING --> CANCELLED
    SUCCEEDED --> [*]
    FAILED --> [*]
    CANCELLED --> [*]

1.4 四类任务

1.5 通知体系

1.6 推送通道抽象：国内现实

国内 Android 生态的特点是：Google Play 服务不可用，FCM（Firebase Cloud Messaging）在绝大多数设备上无法工作； 同时各手机厂商（华为、小米、OPPO、vivo、荣耀）都提供自己的系统级推送通道，且互相不兼容。

应对策略是通道抽象：

flowchart TB
    A["业务层<br/>PushMessage 领域模型"] --> B["PushDispatcher<br/>选路 + 去重 + 降级"]
    B --> C["VendorPushChannel<br/>厂商系统通道（在线时）"]
    B --> D["LocalPushChannel<br/>本地通知兜底"]
    B --> E["PollingWorkChannel<br/>WorkManager 轮询（最弱兜底）"]
    C --> F["NotificationHelper<br/>统一发通知"]
    D --> F
    E --> F

关键设计原则：

• 业务层只认识 PushMessage（标题、内容、deeplink、消息 ID），不认识任何厂商 SDK 的类型。
• 每个通道实现 PushChannel 接口，声明 available（该设备是否可用）。
• 选路逻辑（优先厂商、失败降级本地）集中在 PushDispatcher，便于替换与测试。
• 本章不绑定任何具体 SDK：厂商通道只给接口与"如何接入"的说明，避免示例代码因 SDK 版本失效。

二、示例代码

2.1 依赖

// 文件路径：sample/feature/push/build.gradle.kts
plugins {
    alias(libs.plugins.techfeed.android.library)
    alias(libs.plugins.kotlin.serialization)
    alias(libs.plugins.ksp)
    alias(libs.plugins.hilt)
}

dependencies {
    implementation(projects.core.model)
    implementation(projects.core.common)
    implementation(libs.androidx.work.runtime.ktx)   // WorkManager + CoroutineWorker
    implementation(libs.hilt.android)
    ksp(libs.hilt.compiler)
    // Hilt 与 WorkManager 的桥接
    implementation(libs.androidx.hilt.work)
    ksp(libs.androidx.hilt.compiler)
    testImplementation(libs.bundles.testing.unit)
    androidTestImplementation(libs.androidx.work.testing)   // 测试 Worker
}

2.2 CoroutineWorker + Hilt 注入

// 文件路径：sample/feature/push/src/main/java/com/techfeed/feature/push/worker/SyncFeedWorker.kt
package com.techfeed.feature.push.worker

import android.content.Context
import androidx.hilt.work.HiltWorker
import androidx.work.CoroutineWorker
import androidx.work.WorkerParameters
import com.techfeed.core.database.dao.ArticleDao
import com.techfeed.core.database.entity.toEntity
import com.techfeed.core.model.Result
import com.techfeed.core.network.datasource.FeedRemoteDataSource
import dagger.assisted.Assisted
import dagger.assisted.AssistedInject

/**
 * @HiltWorker + @AssistedInject：让 Worker 也能享受依赖注入。
 * ⚠️ context 与 params 必须用 @Assisted 标记 —— 它们是系统传入的，不在依赖图里。
 *
 * Worker 只依赖 core 层（FeedRemoteDataSource + ArticleDao），不依赖 feature:feed ——
 * "feature 之间零依赖"是本工程的模块化红线（第 15 章）。刷新写库逻辑与
 * FeedRepositoryImpl.refresh 同构，教学上取舍：宁可小段重复，不破模块边界；
 * 若逻辑变复杂，正确做法是把"刷新用例"下沉到 core，而不是让 feature 互相依赖。
 */
@HiltWorker
class SyncFeedWorker @AssistedInject constructor(
    @Assisted context: Context,
    @Assisted params: WorkerParameters,
    private val remote: FeedRemoteDataSource,
    private val dao: ArticleDao,
) : CoroutineWorker(context, params) {

    override suspend fun doWork(): Result = when (val r = remote.getFeed(page = 1, query = null)) {
        is Result.Success -> {
            // 同步与前台刷新共用同一条"保留收藏"的写库路径
            dao.upsertKeepingFavorite(r.data.map { it.toEntity() })
            Result.success()
        }
        // failure：受 runAttemptCount 限制地 retry，超过上限放弃（业务明确的失败）
        is Result.Failure -> if (runAttemptCount < MAX_RETRY) Result.retry() else Result.failure()
        is Result.Loading -> Result.retry()
    }

    private companion object {
        const val MAX_RETRY = 3
    }
}

[!TIP] 若任务通过 setExpedited(...) 以加急方式提交，在 Android 12 以下的系统上会退化为前台服务执行， 此时 Worker 必须实现 getForegroundInfo() 返回带通知的 ForegroundInfo（通知构建见 §2.5 的 NotificationHelper）。

// 文件路径：docs/samples/ch13/WorkerModule.kt
package com.techfeed.app.di

import androidx.hilt.work.HiltWorkerFactory
import androidx.work.Configuration
import dagger.Binds
import dagger.Module
import dagger.hilt.InstallIn
import dagger.hilt.components.SingletonComponent
import javax.inject.Singleton

/**
 * Hilt 接管 WorkerFactory 必须做两件事：
 * 1. @Binds 提供自定义的 WorkerFactory
 * 2. 在 AndroidManifest 中移除 WorkManager 的默认初始化器（见下方 XML）
 */
@Module
@InstallIn(SingletonComponent::class)
abstract class WorkerModule {
    @Binds
    @Singleton
    abstract fun bindWorkerFactory(factory: HiltWorkerFactory): androidx.work.WorkerFactory
}

/** 可选：自定义 Configuration（如设置日志级别、最小周期） */
@Module
@InstallIn(SingletonComponent::class)
object WorkManagerConfigModule {
    @Provides
    @Singleton
    fun provideWorkManagerConfiguration(factory: HiltWorkerFactory): Configuration =
        Configuration.Builder()
            .setWorkerFactory(factory)
            .setMinimumLoggingLevel(android.util.Log.INFO)
            .build()
}

<!-- 文件路径：sample/app/src/main/AndroidManifest.xml -->
<provider
    android:name="androidx.startup.InitializationProvider"
    android:authorities="${applicationId}.androidx-startup"
    android:exported="false"
    tools:node="merge">
    <!-- 移除 WorkManager 的默认初始化，改由 Hilt 在需要时初始化 -->
    <meta-data
        android:name="androidx.work.WorkManagerInitializer"
        android:value="androidx.startup"
        tools:node="remove" />
</provider>

<!-- Application 需实现 Configuration.Provider -->

2.3 提交任务：约束、输入、退避

// 文件路径：sample/feature/push/src/main/java/com/techfeed/feature/push/SyncScheduler.kt
package com.techfeed.feature.push

import androidx.work.BackoffPolicy
import androidx.work.Constraints
import androidx.work.ExistingWorkPolicy
import androidx.work.NetworkType
import androidx.work.OneTimeWorkRequestBuilder
import androidx.work.OutOfQuotaPolicy
import androidx.work.PeriodicWorkRequestBuilder
import androidx.work.WorkManager
import androidx.work.workDataOf
import com.techfeed.feature.push.worker.CacheCleanupWorker
import com.techfeed.feature.push.worker.SyncFeedWorker
import java.util.concurrent.TimeUnit
import javax.inject.Inject
import javax.inject.Singleton

@Singleton
class SyncScheduler @Inject constructor(
    private val workManager: WorkManager,
) {
    /** 一次性同步：要求联网且电量充足，失败按线性退避重试 */
    fun syncOnce(page: Int = 1, expedited: Boolean = false) {
        val constraints = Constraints.Builder()
            .setRequiredNetworkType(NetworkType.CONNECTED)      // 有网即可；UNMETERED 表示仅 WiFi
            .setRequiresBatteryNotLow(true)                     // 低电量时不跑
            .setRequiresCharging(false)
            .setRequiresDeviceIdle(false)                       // true 表示只在 Doze 维护窗口跑
            .setRequiresStorageNotLow(true)
            .build()

        val request = OneTimeWorkRequestBuilder<SyncFeedWorker>()
            .setConstraints(constraints)
            // 初始延迟：避免用户刚打开 App 就抢占资源
            .setInitialDelay(30, TimeUnit.SECONDS)
            // 退避：失败后 10s、20s、40s… 线性增长（EXPONENTIAL 也可）
            .setBackoffCriteria(BackoffPolicy.LINEAR, 10, TimeUnit.SECONDS)
            .setInputData(workDataOf("page" to page))
            .apply {
                // 加急：用户主动触发时用，受系统配额限制
                if (expedited) setExpedited(OutOfQuotaPolicy.RUN_AS_NON_EXPEDITED_WORK_REQUEST)
            }
            .addTag(TAG_SYNC)
            .build()

        // 唯一任务：同名任务只保留一个（APPEND 会排队，REPLACE 会取消旧的）
        workManager.enqueueUniqueWork(UNIQUE_SYNC, ExistingWorkPolicy.KEEP, request)
    }

    /** 周期清理：最小间隔 15 分钟，系统会对齐唤醒以省电 */
    fun scheduleCleanup() {
        val request = PeriodicWorkRequestBuilder<CacheCleanupWorker>(12, TimeUnit.HOURS)
            .setConstraints(
                Constraints.Builder()
                    .setRequiresCharging(true)          // 清理放在充电时做，对用户无感
                    .setRequiresDeviceIdle(true)
                    .build(),
            )
            .build()
        // KEEP：已存在就不重复提交，避免每次启动 App 都重置周期
        workManager.enqueueUniquePeriodicWork(UNIQUE_CLEANUP, ExistingWorkPolicy.KEEP, request)
    }

    /** 链式任务：先同步，再清理，最后上报 */
    fun syncThenCleanup() {
        val sync = OneTimeWorkRequestBuilder<SyncFeedWorker>().build()
        val cleanup = OneTimeWorkRequestBuilder<CacheCleanupWorker>().build()
        val report = OneTimeWorkRequestBuilder<ReportWorker>().build()

        workManager
            .beginUniqueWork(UNIQUE_CHAIN, ExistingWorkPolicy.REPLACE, sync)
            .then(listOf(cleanup, report))    // 两个后继并行执行
            .enqueue()
    }

    fun cancelAllSync() = workManager.cancelAllWorkByTag(TAG_SYNC)

    private companion object {
        const val TAG_SYNC = "sync"
        const val UNIQUE_SYNC = "unique_sync"
        const val UNIQUE_CLEANUP = "unique_cleanup"
        const val UNIQUE_CHAIN = "unique_chain"
    }
}

2.4 观察任务状态

// 文件路径：docs/samples/ch13/SyncStatusViewModel.kt
package com.techfeed.feature.profile.ui

import androidx.lifecycle.ViewModel
import androidx.work.WorkInfo
import androidx.work.WorkManager
import androidx.work.WorkQuery
import dagger.hilt.android.lifecycle.HiltViewModel
import kotlinx.coroutines.flow.Flow
import kotlinx.coroutines.flow.map
import javax.inject.Inject

@HiltViewModel
class SyncStatusViewModel @Inject constructor(
    workManager: WorkManager,
) : ViewModel() {

    /** 观察所有带 sync tag 的任务：数据库驱动，进程重启后依然能查到 */
    val syncStatus: Flow<SyncStatus> = workManager
        .getWorkInfosFlow(WorkQuery.fromTags("sync"))
        .map { infos ->
            when {
                infos.any { it.state == WorkInfo.State.RUNNING } -> SyncStatus.Running
                infos.any { it.state == WorkInfo.State.ENQUEUED } -> SyncStatus.Pending
                infos.any { it.state == WorkInfo.State.FAILED } -> SyncStatus.Failed
                else -> SyncStatus.Idle
            }
        }
}

enum class SyncStatus { Idle, Pending, Running, Failed }

2.5 通知：渠道、PendingIntent 与权限

// 文件路径：sample/feature/push/src/main/java/com/techfeed/feature/push/NotificationHelper.kt
package com.techfeed.feature.push

import android.app.NotificationChannel
import android.app.NotificationManager
import android.content.Context
import android.content.Intent
import android.os.Build
import androidx.core.app.NotificationCompat
import androidx.core.app.NotificationManagerCompat
import androidx.core.app.TaskStackBuilder
import androidx.core.net.toUri

/**
 * 通知的统一出口。三条铁律：
 * 1. Android 8+ 必须先建渠道，否则通知不显示（Logcat 会提示 "No channel found"）
 * 2. PendingIntent 必须显式指定 FLAG_IMMUTABLE / FLAG_MUTABLE（Android 12+ 强制）
 * 3. 发送前检查 areNotificationsEnabled()，Android 13+ 未授权时通知会被静默丢弃
 */
class NotificationHelper(private val context: Context) {

    private val manager = NotificationManagerCompat.from(context)

    fun createChannels() {
        // 渠道只在首次创建时生效；之后修改 importance 不会生效，只能改名字/描述
        create(CHANNEL_ARTICLE, "文章推荐", NotificationManager.IMPORTANCE_DEFAULT)
        create(CHANNEL_SYNC, "数据同步", NotificationManager.IMPORTANCE_LOW)   // 低优先级：静默
        create(CHANNEL_IM, "互动消息", NotificationManager.IMPORTANCE_HIGH)     // 高优先级：响铃+悬浮
    }

    private fun create(id: String, name: String, importance: Int) {
        if (Build.VERSION.SDK_INT < Build.VERSION_CODES.O) return
        val channel = NotificationChannel(id, name, importance).apply {
            description = "$name 类通知"
            enableVibration(importance >= NotificationManager.IMPORTANCE_DEFAULT)
        }
        context.getSystemService(NotificationManager::class.java).createNotificationChannel(channel)
    }

    fun showArticlePush(message: PushMessage) {
        if (!manager.areNotificationsEnabled()) return       // 未授权：静默返回，不要抛异常

        val notification = NotificationCompat.Builder(context, CHANNEL_ARTICLE)
            .setSmallIcon(com.techfeed.core.designsystem.R.drawable.ic_notification)
            .setContentTitle(message.title)
            .setContentText(message.content)
            .setContentIntent(buildDeepLinkIntent(message.deeplink))
            .setAutoCancel(true)                              // 点击后自动移除
            .setPriority(NotificationCompat.PRIORITY_DEFAULT)
            .setOnlyAlertOnce(true)                           // 同 id 多次更新只提醒一次
            .build()

        // ⚠️ Android 13+ 未授权会抛 SecurityException，这里做保护性 catch
        runCatching { manager.notify(message.id.hashCode(), notification) }
    }

    fun buildSyncNotification() = NotificationCompat.Builder(context, CHANNEL_SYNC)
        .setSmallIcon(com.techfeed.core.designsystem.R.drawable.ic_notification)
        .setContentTitle("正在同步数据")
        .setOngoing(true)
        .setContentIntent(buildDeepLinkIntent("techfeed://feed"))
        .build()

    /**
     * 深链 PendingIntent：
     * FLAG_IMMUTABLE —— Android 12+ 必须显式声明；这里不需要被系统修改 Intent，故用 IMMUTABLE
     * FLAG_UPDATE_CURRENT —— 复用已有 PendingIntent 并更新 extras，避免通知堆积
     * TaskStackBuilder —— 保证点击后回退栈正确（回到主页而不是直接退出）
     */
    private fun buildDeepLinkIntent(deeplink: String) = TaskStackBuilder.create(context).run {
        addNextIntentWithParentStack(
            Intent(Intent.ACTION_VIEW, deeplink.toUri()).apply {
                setPackage(context.packageName)   // 只允许本应用响应，防止劫持
            },
        )
        getPendingIntent(
            0,
            android.app.PendingIntent.FLAG_UPDATE_CURRENT or android.app.PendingIntent.FLAG_IMMUTABLE,
        )
    }

    companion object {
        const val CHANNEL_ARTICLE = "channel_article"
        const val CHANNEL_SYNC = "channel_sync"
        const val CHANNEL_IM = "channel_im"
    }
}

/** 推送消息的领域模型：业务层只认识它，不认识任何厂商 SDK 的类型 */
data class PushMessage(
    val id: String,
    val title: String,
    val content: String,
    val deeplink: String,
    val channel: String = NotificationHelper.CHANNEL_ARTICLE,
    val receivedAt: Long = System.currentTimeMillis(),
)

2.6 权限：POST_NOTIFICATIONS 的双体系实现

// 文件路径：docs/samples/ch13/PushPermissionCard.kt
package com.techfeed.feature.push.ui

import android.Manifest
import android.os.Build
import androidx.compose.foundation.layout.Column
import androidx.compose.material3.Button
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.runtime.LaunchedEffect
import androidx.activity.compose.rememberLauncherForActivityResult
import androidx.activity.result.contract.ActivityResultContracts
import androidx.compose.ui.platform.LocalContext

/**
 * Compose 版权限申请。
 * Android 13（API 33）以下无需申请，直接放行。
 */
@Composable
fun PushPermissionCard(onGranted: () -> Unit, onDenied: () -> Unit) {
    val context = LocalContext.current
    val launcher = rememberLauncherForActivityResult(
        ActivityResultContracts.RequestPermission(),
    ) { granted -> if (granted) onGranted() else onDenied() }

    LaunchedEffect(Unit) {
        // 已授权或系统版本低于 33 时直接视为可用
        val granted = Build.VERSION.SDK_INT < Build.VERSION_CODES.TIRAMISU ||
            androidx.core.content.ContextCompat.checkSelfPermission(
                context, Manifest.permission.POST_NOTIFICATIONS,
            ) == android.content.pm.PackageManager.PERMISSION_GRANTED
        if (granted) onGranted()
    }

    Column {
        Text("开启通知，第一时间收到你关注的技术更新")
        Button(onClick = {
            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
                launcher.launch(Manifest.permission.POST_NOTIFICATIONS)
            }
        }) { Text("开启通知") }
    }
}

// 文件路径：docs/samples/ch13/PushPermissionActivity.kt
package com.techfeed.feature.push.ui

import android.Manifest
import android.os.Build
import android.os.Bundle
import androidx.activity.enableEdgeToEdge
import androidx.activity.result.contract.ActivityResultContracts
import androidx.appcompat.app.AppCompatActivity
import com.techfeed.feature.push.databinding.ActivityPushPermissionBinding
import dagger.hilt.android.AndroidEntryPoint

/** View 版权限申请：与 Compose 版的差异只在"如何注册 launcher"与"如何刷新 UI" */
@AndroidEntryPoint
class PushPermissionActivity : AppCompatActivity() {

    private lateinit var binding: ActivityPushPermissionBinding

    // ⚠️ 必须在 Activity 创建阶段注册，不能在点击事件里注册
    private val requestPermissionLauncher = registerForActivityResult(
        ActivityResultContracts.RequestPermission(),
    ) { granted ->
        if (granted) finishGranted() else showRationale()
    }

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        enableEdgeToEdge()
        binding = ActivityPushPermissionBinding.inflate(layoutInflater)
        setContentView(binding.root)

        binding.btnEnable.setOnClickListener {
            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
                requestPermissionLauncher.launch(Manifest.permission.POST_NOTIFICATIONS)
            } else {
                finishGranted()     // Android 13 以下默认有通知权限
            }
        }
    }

    private fun finishGranted() { setResult(RESULT_OK); finish() }

    /** 被拒绝时给出解释，而不是反复弹系统弹窗（会招致用户反感并被系统限制） */
    private fun showRationale() {
        binding.tvHint.text = "未开启通知权限，可在系统设置中开启"
    }
}

2.7 推送通道抽象

// 文件路径：sample/feature/push/src/main/java/com/techfeed/feature/push/PushChannel.kt
package com.techfeed.feature.push

/**
 * 推送通道抽象：业务层只依赖这个接口。
 * 国内 FCM 不可用，因此需要同时具备厂商通道与本地降级通道；
 * 抽象的目的正是让"接哪家、接几家"成为配置问题，而不是代码改造问题。
 */
interface PushChannel {
    /** 通道标识，用于埋点与排障 */
    val id: String
    /** 通道展示名 */
    val displayName: String
    /** 当前设备该通道是否可用（如非小米设备小米通道不可用） */
    val available: Boolean
    /** 优先级，数值越大越优先 */
    val priority: Int

    /** 获取该通道的设备令牌；失败返回 null */
    suspend fun getToken(): String?

    /** 收到新令牌时回调（令牌可能轮换） */
    suspend fun onTokenRefresh(token: String)

    /** 订阅/取消主题 */
    suspend fun subscribe(topic: String)
    suspend fun unsubscribe(topic: String)

    /** 把消息送达本设备：厂商通道经厂商长连接下发，本地通道直接发通知 */
    suspend fun send(message: PushMessage)
}

// 文件路径：sample/feature/push/src/main/java/com/techfeed/feature/push/LocalPushChannel.kt
package com.techfeed.feature.push

import javax.inject.Inject
import javax.inject.Singleton

/**
 * 本地通道：不依赖任何 SDK，用 WorkManager 周期轮询 + 本地通知实现"最弱兜底"。
 * 它的价值在于：任何时候 App 都能发通知 —— 产品功能不会因为没接厂商 SDK 而不可用。
 */
@Singleton
class LocalPushChannel @Inject constructor(
    private val notificationHelper: NotificationHelper,
    private val scheduler: SyncScheduler,
) : PushChannel {
    override val id: String = "local"
    override val displayName: String = "本地通知"
    override val available: Boolean = true      // 永远可用
    override val priority: Int = 0              // 优先级最低

    override suspend fun getToken(): String? = null          // 本地通道没有设备令牌
    override suspend fun onTokenRefresh(token: String) = Unit
    override suspend fun subscribe(topic: String) = Unit
    override suspend fun unsubscribe(topic: String) = Unit

    /** 直接发本地通知：也可用于"定时提醒""下载完成"等纯本地场景 */
    fun show(message: PushMessage) = notificationHelper.showArticlePush(message)

    /** 本地通道的"送达"就是直接发通知 */
    override suspend fun send(message: PushMessage) = show(message)
}

// 文件路径：docs/samples/ch13/VendorPushChannel.kt
package com.techfeed.feature.push

import android.content.Context
import javax.inject.Inject
import javax.inject.Singleton

/**
 * 厂商通道占位实现：本章**不绑定任何具体 SDK**。
 * 接入方式（以任意厂商为例）：
 *   1. 引入该厂商的 push SDK 依赖（版本写入 libs.versions.toml）
 *   2. 在 getToken() 中调用 SDK 的 getToken / getAAID 等 API
 *   3. 在 SDK 的 Token 回调里调用 onTokenRefresh()
 *   4. 在 available 中判断是否为该厂商设备（如读取 Build.BRAND / 系统属性）
 * ⚠️ 接入要点：
 *   - 厂商 SDK 通常要求在主线程或特定时机初始化，放在 Application 的异步初始化里（第 17 章启动优化）
 *   - 透传消息（非通知栏消息）需要自己创建通知，走 NotificationHelper 统一出口
 *   - 令牌与账号的绑定关系要上报服务端，并在登出时解绑（第 25 章）
 */
@Singleton
class VendorPushChannel @Inject constructor(
    private val context: Context,
) : PushChannel {
    override val id: String = "vendor"
    override val displayName: String = "厂商系统通道"
    override val available: Boolean by lazy { detectVendorDevice() }
    override val priority: Int = 100

    override suspend fun getToken(): String? = runCatching {
        // TODO: return VendorPushSdk.getToken()
        null
    }.getOrNull()

    override suspend fun onTokenRefresh(token: String) {
        // TODO: 上报服务端，绑定当前账号
    }

    override suspend fun subscribe(topic: String) {
        // TODO: VendorPushSdk.subscribe(topic)
    }

    override suspend fun unsubscribe(topic: String) {
        // TODO: VendorPushSdk.unsubscribe(topic)
    }

    override suspend fun send(message: PushMessage) {
        // TODO: VendorPushSdk.sendMessage(message) —— 消息经厂商长连接下发，由系统通知栏展示
    }

    private fun detectVendorDevice(): Boolean {
        val manufacturer = android.os.Build.MANUFACTURER.lowercase()
        return VENDOR_KEYWORDS.any { manufacturer.contains(it) }
    }

    private companion object {
        val VENDOR_KEYWORDS = listOf("huawei", "honor", "xiaomi", "oppo", "vivo", "meizu")
    }
}

// 文件路径：docs/samples/ch13/PushDispatcher.kt
package com.techfeed.feature.push

import kotlinx.coroutines.flow.firstOrNull
import javax.inject.Inject
import javax.inject.Singleton

/**
 * 推送选路与分发：
 * - 选路：按 priority 从可用通道里挑一个
 * - 去重：同一 messageId 只处理一次（厂商通道与轮询通道可能重复触达）
 * - 降级：所有远程通道不可用时，回落到本地通知
 */
@Singleton
class PushDispatcher @Inject constructor(
    channels: Set<@JvmSuppressWildcards PushChannel>,
    private val local: LocalPushChannel,
    private val seenMessages: SeenMessageStore,
) {
    private val ordered = channels.filter { it.available }.sortedByDescending { it.priority }

    suspend fun dispatch(message: PushMessage) {
        // 去重：推送到达重复是常态（多通道 + 网络重试）
        if (!seenMessages.markIfNew(message.id)) return

        val channel = ordered.firstOrNull()
        if (channel == null || channel === local) {
            local.show(message)          // 无远程通道：本地直接展示
        } else {
            // 远程通道负责把消息经厂商长连接送达并展示，本地不再重复弹一条通知
            channel.send(message)
        }
    }

    suspend fun reportToken(): String? =
        ordered.firstNotNullOfOrNull { runCatching { it.getToken() }.getOrNull() }
}

/** 已处理消息的记录（可用 Room 或 DataStore 实现，见第 10 章） */
interface SeenMessageStore {
    suspend fun markIfNew(messageId: String): Boolean
}

// 文件路径：sample/feature/push/src/main/java/com/techfeed/feature/push/di/PushModule.kt
package com.techfeed.feature.push.di

import com.techfeed.feature.push.LocalPushChannel
import com.techfeed.feature.push.NotificationHelper
import com.techfeed.feature.push.PushChannel
import com.techfeed.feature.push.VendorPushChannel
import dagger.Binds
import dagger.Module
import dagger.Provides
import dagger.hilt.InstallIn
import dagger.hilt.android.qualifiers.ApplicationContext
import dagger.hilt.components.SingletonComponent
import dagger.multibindings.IntoSet
import javax.inject.Singleton

@Module
@InstallIn(SingletonComponent::class)
abstract class PushModule {

    /**
     * @IntoSet：把多个实现收集成 Set<PushChannel>。
     * 这是"插件式通道"的关键 —— 新增一个厂商通道只需加一个 @Binds，无需改 PushDispatcher。
     */
    @Binds
    @IntoSet
    @Singleton
    abstract fun bindLocalChannel(impl: LocalPushChannel): PushChannel

    @Binds
    @IntoSet
    @Singleton
    abstract fun bindVendorChannel(impl: VendorPushChannel): PushChannel

    companion object {
        @Provides
        @Singleton
        fun provideNotificationHelper(@ApplicationContext context: android.content.Context) =
            NotificationHelper(context).also { it.createChannels() }
    }
}

2.8 测试 Worker

// 文件路径：docs/samples/ch13/SyncFeedWorkerTest.kt
package com.techfeed.feature.push.worker

import android.content.Context
import androidx.test.core.app.ApplicationProvider
import androidx.work.ListenableWorker
import androidx.work.WorkerFactory
import androidx.work.WorkerParameters
import androidx.work.testing.TestListenableWorkerBuilder
import com.google.common.truth.Truth.assertThat
import com.techfeed.core.database.dao.ArticleDao
import com.techfeed.core.database.entity.ArticleEntity
import com.techfeed.core.model.AppError
import com.techfeed.core.model.Article
import com.techfeed.core.model.Author
import com.techfeed.core.model.Result
import com.techfeed.core.network.datasource.FeedRemoteDataSource
import kotlinx.coroutines.flow.Flow
import kotlinx.coroutines.flow.flowOf
import kotlinx.coroutines.runBlocking
import org.junit.Before
import org.junit.Test
import java.io.IOException

class SyncFeedWorkerTest {

    private lateinit var context: Context
    private lateinit var remote: FakeFeedRemoteDataSource
    private lateinit var dao: FakeArticleDao

    @Before
    fun setUp() {
        context = ApplicationProvider.getApplicationContext()
        remote = FakeFeedRemoteDataSource()
        dao = FakeArticleDao()
    }

    /**
     * Worker 的依赖（FeedRemoteDataSource / ArticleDao）都是接口，
     * Fake 直接实现接口即可；OfflineFirstFeedRepository 那样的 final 类不能被继承伪造。
     * 用 TestListenableWorkerBuilder + 匿名 WorkerFactory 手动组装 Worker（测试期不走 Hilt）。
     */
    private fun buildWorker(): SyncFeedWorker =
        TestListenableWorkerBuilder<SyncFeedWorker>(context)
            .setWorkerFactory(object : WorkerFactory() {
                override fun createWorker(
                    appContext: Context,
                    workerClassName: String,
                    workerParameters: WorkerParameters,
                ): ListenableWorker = SyncFeedWorker(appContext, workerParameters, remote, dao)
            })
            .build()

    @Test
    fun `同步成功 返回 success 且数据落库`() = runBlocking {
        remote.feedResult = Result.Success(listOf(createArticle("a-1")))

        val result = buildWorker().doWork()

        assertThat(result).isEqualTo(ListenableWorker.Result.success())
        assertThat(dao.upserted.map { it.id }).containsExactly("a-1")
    }

    @Test
    fun `同步失败 返回 retry（由退避策略重排）`() = runBlocking {
        remote.feedResult = Result.Failure(AppError.Network(IOException("no net")))

        assertThat(buildWorker().doWork()).isEqualTo(ListenableWorker.Result.retry())
    }

    private fun createArticle(id: String) = Article(
        id = id, title = "t-$id", summary = "", coverUrl = null,
        author = Author("au", "作者", null), publishedAt = 0L,
    )
}

/** Fake 只实现接口 FeedRemoteDataSource —— 接口才是可替换的边界 */
private class FakeFeedRemoteDataSource : FeedRemoteDataSource {
    var feedResult: Result<List<Article>> = Result.Success(emptyList())

    override suspend fun getFeed(page: Int, query: String?): Result<List<Article>> = feedResult
    override suspend fun getArticle(id: String): Result<Article> = error("测试未用到")
    override suspend fun toggleFavorite(id: String): Result<Article> = error("测试未用到")
}

/** Fake 只实现接口 ArticleDao；upsertKeepingFavorite 有默认实现（事务内查收藏位再批量 upsert），自动复用 */
private class FakeArticleDao : ArticleDao {
    val upserted = mutableListOf<ArticleEntity>()

    override fun observeFeed(query: String?): Flow<List<ArticleEntity>> = flowOf(emptyList())
    override fun observeFavorites(): Flow<List<ArticleEntity>> = flowOf(emptyList())
    override fun observeArticle(id: String): Flow<ArticleEntity?> = flowOf(null)
    override suspend fun getArticle(id: String): ArticleEntity? = null
    override suspend fun upsertAll(articles: List<ArticleEntity>) { upserted += articles }
    override suspend fun insert(article: ArticleEntity) { upserted += article }
    override suspend fun updateFavorite(id: String, favorite: Boolean) = Unit
    override suspend fun existingIds(ids: List<String>): List<String> = emptyList()
    override suspend fun favoriteIdsAmong(ids: List<String>): List<String> = emptyList()
    override suspend fun clearExpiredCache(expireAt: Long) = Unit
}

[!TIP] 上面用 TestListenableWorkerBuilder + 匿名 WorkerFactory 直接组装 Worker，无需启动 Hilt 或真实调度。 更完整的做法是把 Worker 的业务逻辑抽成独立的 UseCase，Worker 只做薄薄一层适配—— 这样 Worker 本身几乎不需要测试，逻辑测试回归到普通单元测试。这是更好的设计。

// 旧写法：IntentService —— 已在 API 30 弃用，后台启动受限，进程被杀后任务丢失
public class SyncService extends IntentService {
    protected void onHandleIntent(Intent intent) { doSync(); }   // 后台启动会抛 IllegalStateException
}

// 旧写法：JobScheduler —— 需自行处理 API 兼容、无持久化、无链式、无加急
JobInfo job = new JobInfo.Builder(JOB_ID, new ComponentName(this, SyncJobService.class))
    .setRequiredNetworkType(JobInfo.NETWORK_TYPE_ANY)
    .setPeriodic(15 * 60 * 1000)
    .build();
jobScheduler.schedule(job);

三、常见坑 ⚠️

四、调试技巧

# 1. 查看 WorkManager 的任务状态（最常用）
adb shell dumpsys jobscheduler | grep -A 20 "com.techfeed.app"

# 2. 强制进入 Doze 模式，验证约束是否生效
adb shell dumpsys battery unplug          # 模拟断开充电
adb shell dumpsys deviceidle force-idle   # 强制进入 idle
adb shell dumpsys deviceidle step         # 逐步推进 Doze 状态

# 3. 手动触发一个 Worker（需测试环境）
adb shell am broadcast -a androidx.work.diagnostics.REQUEST_DIAGNOSTICS -p com.techfeed.app

# 4. 查看通知渠道与权限状态
adb shell dumpsys notification --noredact | grep -A 5 "techfeed"
adb shell cmd appops get com.techfeed.app POST_NOTIFICATION

# 5. 直接发一条测试通知（不写代码验证渠道是否正确）
adb shell cmd notification post -S bigtext -t '标题' 'tag' '内容'

# 6. 模拟进程被杀，验证任务是否持久化
adb shell am kill com.techfeed.app

IDE 内：

• App Inspection → Background Task Inspector：可视化查看 WorkManager 任务的状态、约束、重试次数与执行历史——排查"为什么不执行"的第一工具。
• Logcat 过滤 WM- 可以看到 WorkManager 的内部日志（WM-WorkerWrapper、WM-SystemJobScheduler）。

五、最佳实践

1. 后台任务默认选 WorkManager：Service 只用于前台服务（音乐、导航、长连接），JobScheduler 交给 WorkManager 封装。
2. Worker 只做适配，逻辑放 UseCase：doWork() 里只调用一个 UseCase，这样业务逻辑可单测、Worker 几乎不用测。
3. CoroutineWorker 优于 Worker：前者直接给你 suspend 上下文，不再需要阻塞式 API。
4. 约束要克制：约束越多，任务越难触发。requiresCharging + requiresDeviceIdle 是清理类任务的合理组合，同步类任务通常只需要网络。
5. 唯一任务用 KEEP：避免每次启动 App 都重置周期或堆积重复任务。
6. 退避策略显式配置：默认退避是 30s 指数增长，按业务调整。
7. 渠道在 Application 启动时创建：按用途分渠道（推荐/同步/互动），让用户能分别开关。
8. PendingIntent 一律显式可变性标志：99% 场景用 FLAG_IMMUTABLE，需要 PendingIntent 被系统填充额外数据时才用 FLAG_MUTABLE。
9. 权限申请要有解释与降级：被拒绝后不要反复弹窗，给出设置入口；通知不可用时功能仍应可用。
10. 推送走通道抽象：业务只依赖 PushMessage 与 PushChannel，新增厂商通道不改业务代码。
11. 推送必须去重：多通道重复触达是常态，按 messageId 幂等处理。

六、本章小结

1. 后台限制是续航权衡的结果：Doze、应用待机、后台服务限制层层收紧，现代做法是"向系统声明、由系统调度"——WorkManager 是唯一推荐。
2. WorkManager 提供持久化、约束感知与版本自适应：CoroutineWorker 写 suspend 逻辑，四类任务（一次性/周期/加急/链式）覆盖绝大多数场景，WorkInfo 可被 Flow 观察。
3. 可测试性靠分层：把逻辑抽到 UseCase，Worker 只做薄适配，避免"为了测 Worker 而搭建整套 WorkManager"。
4. 通知有三道门槛：渠道（8+）、PendingIntent 可变性（12+）、POST_NOTIFICATIONS 权限（13+），缺一个通知就静默消失。
5. 推送必须抽象：国内 FCM 不可用，用 PushChannel 接口 + PushDispatcher 选路去重，让"接哪家厂商"成为配置问题而非改造问题。

上一章衔接：第 12 章 依赖注入 的 @HiltWorker 与 @IntoSet 多绑定， 正是本章 Worker 注入与多推送通道装配的技术基础。 下一章：至此阶段 2 的四项能力（网络、存储、异步、DI）与后台通知已齐备，进入 第 14 章 分层架构与 MVI，把这些零件按 UI / Domain / Data 三层组织成企业级架构。

七、动手练习

基础题

1. 写一个 CacheCleanupWorker（CoroutineWorker），要求：只在充电且空闲时运行，删除 7 天前的缓存文件，返回删除的文件数量到 outputData。
2. 用 enqueueUniquePeriodicWork 提交 12 小时一次的清理任务，用 Background Task Inspector 观察它的状态变化。
3. 创建两个通知渠道（"文章推荐" DEFAULT、"互动消息" HIGH），用 adb shell cmd notification post 验证渠道创建成功。

进阶题 4. 实现链式任务：同步 → 生成摘要 → 发通知。要求前一步的输出作为后一步的输入，并用 getWorkInfosFlow 在 UI 上展示进度（提示：setProgressAsync）。 5. 给 SyncFeedWorker 加"加急"分支：用户下拉刷新失败后点击"重试"时提交加急任务；用 OutOfQuotaPolicy.RUN_AS_NON_EXPEDITED_WORK_REQUEST 处理超配额情况，并写测试验证降级行为。 6. 扩展 PushChannel：再加一个 PollingPushChannel（用 WorkManager 每 6 小时轮询服务端未读消息并转本地通知），验证 PushDispatcher 无需改动即可纳入新通道。

思考题 7. 为什么 WorkManager 的周期任务最小间隔是 15 分钟？如果产品要求"每 5 分钟检查一次新消息"，你会怎么设计（至少给出两种方案及代价）？ 8. 加急任务（Expedited Work）与前台服务（Foreground Service）的区别是什么？为什么 Android 12 要引入前者并限制后者？ 9. 如果你的 App 在某国产 ROM 上完全收不到推送，你会按什么顺序排查？通道抽象在这条排查链上能提供什么帮助？ 10. 通知被用户关闭了渠道（而不是关闭权限），App 侧能感知吗？产品上应该如何设计降级体验？

📄 第 14 章 分层架构与单向数据流（MVI） 14-architecture-layering-mvi.md✓ 标记已学

阶段：企业级 ｜ 预计阅读 60 min ｜ 代码落地模块：:core:model、:feature:feed、:feature:detail 前置：第 03 章 应用组件与生命周期 ｜ 第 11 章 协程与 Flow ｜ 第 12 章 依赖注入 相关章节：第 15 章 模块化与组件化拆分 ｜ 第 16 章 Compose 与 View 互操作 ｜ 第 21 章 测试策略 ｜ 第 23 章 TechFeed 总览

学习目标

• [ ] 说清 MVC / MVP 在 Android 上为什么会失控，理解 MVP 的 IView 接口与 MVVM 双向绑定各自的代价。
• [ ] 掌握 UI / Domain / Data 三层职责与依赖方向，能画出依赖图并解释"为什么 UI 不能直接依赖 Data"。
• [ ] 能独立设计一个单一不可变 UiState，严格区分状态（State）与事件（Event），写出可测试、可重放的 ViewModel。
• [ ] 理解 UseCase、Repository、单一数据源（Single Source of Truth, SSOT）的价值边界，知道什么时候不该写 UseCase。
• [ ] 能区分领域模型、DTO、Entity 三层模型并完成映射，识别 ViewModel 职责越界的常见反模式。

一、核心概念

1.1 Activity 为什么会变成 3000 行

Android 官方从没指定过架构，于是大家照搬 Web 时代的 MVC（Model-View-Controller）：Model 是数据，View 是 XML，Controller 是 Activity。这套映射在 Android 上从一开始就错位了：

// ⚠️ 反模式：一个 Activity 同时扮演了 Controller、半个 View、半个 Model
class FeedActivity : AppCompatActivity() {
    private val articles = mutableListOf<Article>()   // Model 状态混在这里
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_feed)        // View 的创建
        findViewById<Button>(R.id.btn_refresh)        // View 的查找
            .setOnClickListener {                     // Controller 的事件处理
                Thread {                              // 自己做线程切换
                    val json = URL("https://api.techfeed.dev/feed").readText()  // 自己做网络
                    val list = Gson().fromJson(json, Array<Article>::class.java) // 自己做解析
                    runOnUiThread {                   // 自己做回调
                        articles.clear(); articles.addAll(list)
                        (recyclerView.adapter as FeedAdapter).submitList(articles.toList())
                        progressBar.visibility = View.GONE   // 自己做状态同步
                    }
                }.start()
            }
    }
}

这份代码的致命问题不是"丑"，而是四条结构性缺陷：

MVP（Model-View-Presenter） 的补救是把 View 抽成接口：

interface FeedView { fun showLoading(); fun showList(list: List<Article>); fun showError(msg: String) }

Presenter 只依赖接口，于是可以脱离 Android 跑单元测试。但 MVP 在企业项目里同样会失控：

1. 接口爆炸：每屏一个 IView，稍有改动就要改接口 + 实现类 + Presenter 三处。
2. 生命周期手工绑定：Presenter 什么时候 attachView/detachView 全靠自觉，漏一次就是泄漏或空指针。
3. Presenter 依旧是 God Object： Presenter 取代 Activity 变成新的 3000 行。
4. 状态一致性没解决：showLoading / showList 是命令式调用，"当前到底什么状态"没有唯一答案。

MVVM（Model-View-ViewModel） 用数据绑定把 View 和 ViewModel 解耦，Android 早期用 DataBinding / LiveData。但一旦引入双向绑定（@={}），"这个字段到底被谁改了"就彻底失控——调试时你追不到修改来源。

于是 Google 在 2020 年前后明确了官方推荐：单向数据流（Unidirectional Data Flow, UDF），在 Android 语境下常被称作 MVI（Model-View-Intent）。它不是一个新框架，而是三条硬约束。

先用一张表把四种范式的取舍一次看清（" Model 维个数"指状态是否有唯一存放地）：

一句话概括差别：MVC/MVP 回答的是"谁去改 View"，MVI 回答的是"现在是什么状态"。前者是命令式调用链，后者是声明式快照。当你能用"给同一份 UiState，画出同一幅画面"来定义 UI 时，旋转屏幕、进程重建、UI 测试这三件以往最头疼的事，会自动变成同一件事。

1.2 三层架构与依赖方向

官方分层只有三层：UI 层 → Domain 层 → Data 层。关键在于依赖方向：

flowchart TD
    UI["<b>UI 层</b><br/>Compose / View + XML<br/>ViewModel · UiState · Event"]
    DOM["<b>Domain 层</b>（可选但推荐）<br/>UseCase · Repository 接口<br/>领域模型 Article / Author"]
    DATA["<b>Data 层</b><br/>Repository 实现 · Remote/Local 数据源<br/>DTO · Entity · 数据源门面"]

    UI -->|"① 依赖：调用 UseCase"| DOM
    DATA -->|"② 依赖并实现：Repository 接口"| DOM
    UI -.->|"❌ 禁止：UI 直接 import Data"| DATA

    style DOM fill:#e8f0fe,stroke:#4a76c8
    style UI fill:#fff6e0,stroke:#c8a04a
    style DATA fill:#e9f7ee,stroke:#4aa86a

这张图有三点容易看漏：

1. Domain 层不依赖任何外层，它是纯 Kotlin（理想情况下），不 import android.*、不 import Retrofit、不 import Room。这是它能被秒级单测的根本原因。
2. Data 层依赖 Domain 层（实现它的接口），箭头方向反直觉但必须如此——这就是依赖倒置原则（Dependency Inversion Principle, DIP）。
3. UI 层不许 import Data 层的具体类。UI 拿到的永远是 Domain 层定义的抽象（Repository 接口、UseCase）。

三层的职责边界：

[!TIP] Domain 层是可选的。 如果你的 App 只是"请求 → 展示"，UseCase 全都是一行转发，那么加一层只会让文件数量翻倍。判断标准见 1.6 节。

分层最容易被写口号。要让它真的生效，必须落在可被工具检查的位置：

1. 包结构上先分层：feature/feed/ui/、feature/feed/domain/、feature/feed/data/ 三个包，Review 时一眼看出某个类是否放错层。
2. 再落成 Gradle 模块：第 15 章会把 ui / data 拆成独立模块，届时"UI 不许 import Retrofit"不再靠自觉，而是编译期直接报错。
3. 用静态检查兜底：Detekt 的自定义规则可以禁止 ui 包中出现 import androidx.room.*，CI 卡住而非口头约定。

换句话说：分层不是画图，是用编译器和 CI 把边界固定下来。在团队超过 5 人之后，这一点比选哪种范式更重要。

1.3 单向数据流（UDF）：状态向下，事件向上

UDF 的完整闭环只有四个环节：

sequenceDiagram
    participant U as UI（Compose / View）
    participant V as ViewModel
    participant D as Domain / Data
    U->>V: ① 用户意图 Event（onClick / 下拉刷新）
    V->>D: ② 调用 UseCase（suspend / Flow）
    D-->>V: ③ 返回数据或 Result
    V->>V: ④ 计算出新的 UiState（copy）
    V-->>U: ⑤ StateFlow 推送新快照
    U->>U: ⑥ UI 按快照重新渲染（幂等）

三条铁律：

1. 状态向下流动，事件向上流动（State down, Events up），不存在反向。
2. UI 是状态的函数：同一份 UiState 渲染出的画面必须完全一致（幂等），旋转屏幕只是重新执行这个函数。
3. 唯一修改入口：UiState 只能在 ViewModel 内部被 _uiState.update {} 修改，UI 永远只读。

这三条约束带来的收益可以量化：

• 可重放：把历史上产生过的 UiState 序列记下来，就能在测试或崩溃复现时逐帧重现画面（第 21 章的截图测试正是靠这一点）。
• 可观性：出问题时你不需要猜"哪个调用改了这个控件"，只需要看"这一刻的 UiState 是什么"和"上一个 Action 是什么"——调试维度从"所有代码"降到"两个变量"。
• 可并行改写：状态入口唯一，意味着两个人同时加功能时，冲突面从"多个控件的可见性判断"收缩到"一个 copy 表达式"。

代价也要说清楚：MVI 比 MVVM 多一些样板（State、Event、Action 三个密封类），对极其简单的页面显得啰嗦。评判标准很简单——如果这个屏幕有三种以上的视觉状态（加载/空/错误/内容），用 MVI 一定回本。

1.4 UiState：一个屏幕，一个不可变快照

UiState 是全章最重要的数据结构。四条设计原则：

① 单一状态对象。 一个屏幕（或一个顶层目的地）对应一个 UiState，而不是每个控件一个 LiveData。

// ❌ 反模式：状态分散，三者可能同时为真（既加载中又显示错误又显示空列表）
val isLoading: StateFlow<Boolean>
val articles: StateFlow<List<Article>>
val error: StateFlow<String?>

// ✅ 正确：单一快照，状态天然互斥自洽
data class FeedUiState(
    val isLoading: Boolean = false,
    val articles: List<Article> = emptyList(),
    val errorMessage: String? = null,
) {
    // 派生属性：不要再开一个 StateFlow 去维护它
    val isEmpty: Boolean get() = !isLoading && errorMessage == null && articles.isEmpty()
}

② 屏幕级而非控件级。 UiState 描述"这一屏长什么样"，而不是"这个 Button 是不是选中"。控件级的局部状态（TextField 的输入中字符、滚动位置、动画进度）留在 UI 内部即可，不要塞进 UiState——否则每敲一个字符都要走一轮 ViewModel 往返，白白增加延迟与重组。

③ 不可变 + copy。 全部字段用 val，容器类型用只读接口 List/Map。更新必须用 copy，因为 StateFlow 的相等判定依赖 equals：直接 mutableList.add() 引用没变，StateFlow 认为值没变，UI 不会刷新。

④ 不做基站式巨型状态。 一个 UiState 里出现 40 个字段说明这个屏幕该拆了。常见做法是把底部弹窗、次级区块拆成独立的小 UiState。

1.5 State 与 Event 必须分离

这是新手最常踩的一条：

如果把 Toast 塞进 UiState，旋转屏幕后 UI 重新收集 StateFlow 会再弹一次。这就是必须为一次性事件单独开一个通道的原因。

// ⚠️ 反模式：偷懒把一次性事件做成 UiState 字段
data class FeedUiState(val toastMessage: String? = null)   // 旋转屏幕就会被重放

// ✅ 事件通道：SharedFlow 默认 replay = 0，不缓存、不重放
private val _events = MutableSharedFlow<FeedEvent>(
    extraBufferCapacity = 1,   // 允许在 UI 尚未开始收集时先缓存一个事件，避免 send 挂起
)

[!NOTE] 为什么不用 Channel？ Channel 默认是 rendezvous（会挂起等待接收方），而且把事件交给它之后你无法同时给多个订阅者；SharedFlow 支持多订阅、tryEmit、replay/extraBufferCapacity 可调，行为更可控。只有在明确需要"单个消费者、绝不重放"的极端场景下才考虑 Channel。

事件通道还有两个容易忽略的细节：

• 回执机制：事件消费完（例如 Snackbar 已关闭）后 UI 应上报一个动作（见 2.1 的 FeedAction.MessageShown），让 ViewModel 清掉对应状态，避免"错误提示存在于状态里但已被用户关掉"的不一致。
• 谁来消费：事件必须在有生命周期的一方消费（Compose 的 LaunchedEffect、View 的 repeatOnLifecycle），否则页面进入后台时发出的事件会在回来时被一次性补执行。

1.6 UseCase：什么时候该写，什么时候不该写

一个 UseCase 就是一个命名的业务意图，通常只有一个方法 operator fun invoke(...)：

class GetFeedUseCase @Inject constructor(private val repository: FeedRepository) {
    suspend operator fun invoke(page: Int, forceRefresh: Boolean = false): List<Article> = ...
}

该写 UseCase 的四类场景：

1. 跨多个数据源编排：「首屏 = 用户信息 + 信息流 + 未读数」三个 Repository 并发聚合。
2. 业务规则集中：购买前校验（登录态 + 库存 + 风控），多个页面共用。
3. 被多个 ViewModel 复用：收藏操作在列表页、详情页、个人页都要用。
4. 作为清晰的测试边界：单测一个 UseCase 只需 mock 几个 Repository。

不该写 UseCase 的场景（写了就是负担）：

• 只是 return repository.getFeed() 的一行转发，且只有一个调用方。
• 纯 UI 行为：排序顺序切换、展开/收起、Tab 选中。
• 纯数据转换：那是 Mapper 或 UiState 派生属性的活儿。
• 把 Repository 方法换个名字包一层，只为"看起来架构整齐"。

[!WARNING] 每增加一层，就多一层样板代码与 Review 成本。先写薄的 ViewModel，等出现第二处复用或业务变复杂时再抽取 UseCase，比一开始就全铺开要健康得多。

1.7 Repository 与单一数据源（SSOT）

Repository 是数据层的门面：调用方不知道数据来自网络还是数据库。

flowchart LR
    VM["ViewModel"] --> UC["UseCase"] --> R["FeedRepository（接口在 Domain）"]
    R --> IMPL["FeedRepositoryImpl（实现在 Data）"]
    IMPL --> REM["RemoteDataSource<br/>Retrofit"]
    IMPL --> LOC["LocalDataSource<br/>Room"]
    LOC -.->|"单一数据源：先落库"| DB[("Room DB")]
    DB -->|"Flow 持续推送缓存"| VM

单一数据源（Single Source of Truth, SSOT） 的落地形态通常是"网络写库 → 数据库作为唯一真相 → UI 只订阅数据库 Flow"：

override fun observeFeed(): Flow<List<Article>> =
    dao.observeArticles().map { list -> list.map { it.toDomain() } }  // UI 只订阅本地

这样做的好处：离线可用、天然缓存、数据源切换不影响 UI、旋转屏幕不会重新请求。

三种常见的 Repository 读策略，先把它们摆清楚再选：

代价都要直面一件事：数据新鲜度。缓存优先会让首帧显示几分钟前的旧数据，因此需要配套的过期机制（shouldRefresh() 判定、 stamps 时间戳、或 WorkManager 周期同步），这部分实战在第 25 章展开。

[!WARNING] 别把三种策略混在一个 Repository 里随机使用。团队里最常见的 bug 是" A 页面缓存优先、B 页面网络优先"，同一份数据在不同页面显示不一致。策略要写进模块文档，并让所有调用方走同一个 Repository 方法。

1.8 三层模型：DTO / Entity / Domain

为什么不能一个类走天下？因为三种模型的变更原因完全不同：

不分层会发生什么？后端把 publish_time 从秒改成毫秒，你的 UI 代码、数据库迁移、单元测试一起炸。分层之后，改动被限制在 Mapper 里，一行改完。

Mapper 的方向与归属也要约定清楚，否则很快会出现循环依赖：

原则是：内层不认识外层。写 Article.toArticleDto() 意味着 Domain 层要知道 Retrofit 的存在，这就破坏了依赖方向；所以映射函数一律写成 ArticleDto.toDomain()（外层认识内层），放在外层模块里。

[!NOTE] 有些团队会把 Entity 与 Domain 合一（用 Room 的 @Entity 类直接当领域模型）。这在小项目里完全可接受，省一层样板；一旦你的领域模型需要表达"Entity 里没有的业务字段"（例如由两张表拼出来的 isFavorite），就会被迫重新拆开。

1.9 ViewModel 的职责边界

ViewModel 是 UI 层的状态容器，它恰好做四件事：

1. 持有并计算 UiState（唯一写入者）。
2. 接收 UI 上报的事件，翻译成 UseCase 调用。
3. 在 viewModelScope 中启动协程，生命周期结束时自动取消（第 03 章）。
4. 通过 SavedStateHandle 保存跨进程重建的关键状态。

除此之外一概不做：

1.10 端到端走一遍：一次下拉刷新发生了什么

把抽象落到具体，才能在 Review 时对得上直觉。用户下拉一次，完整链路是这样的：

1. SwipeRefreshLayout / PullToRefreshBox 回调 → UI 上报 FeedAction.Refresh（事件向上）。
2. ViewModel 在 viewModelScope 里先 _uiState.update { copy(isRefreshing = true) }，UI 立刻显示转圈——注意此时网络还没开始。
3. ViewModel 调用 suspend 的 RefreshFeedUseCase → Repository → RemoteDataSource 请求网络。
4. 网络返回 DTO → Mapper 转 Entity → 写入 Room。
5. Room 数据变动触发 Flow 推送 → Repository 的 observeFeed() 收到新列表 → Mapper 转领域模型 → ViewModel 的 onEach 里 copy(articles = new)，状态向下回到 UI。
6. UI 收到新快照，adapter.submitList() / LazyColumn 差分刷新，同时 isRefreshing = false 收起指示器；ViewModel 再发一个 FeedEvent.ScrollToTop 事件。

三条容易被忽略的结论：

• 第 2 步是先改 UI 再干活：用户等待反馈的耐心只有 100ms 量级，真实数据到了再更新同一份 UiState 即可。
• 第 5 步是自动的：ViewModel 并没有手动合并列表或请求下一页，本地数据库 Flow 推什么就渲染什么——这是 SSOT 最具体的收益。
• 失败不影响正确性：网络失败只是不写库，旧数据照常显示，额外置一个错误字段或发一个事件即可。

二、示例代码

下面以一个真实信息流页面串起全链路：UiState/Event → ViewModel → UseCase → Repository → 数据源 → 映射 → Compose UI → View/XML UI。

2.1 UiState 与 Event 契约

[!NOTE] 演进说明：本章为聚焦 MVI 概念，FeedUiState 的错误字段使用最朴素的 errorMessage: String?。工程最终形态（第 21 章测试与第 24 章代码清单）已将其演进为 error: AppError?（领域错误类型），UI 层通过 error.userMessage 取展示文案——错误分类与文案映射的动机见第 09 章 AppError。两种写法都满足"状态收敛于单一快照"的原则。

// sample/feature/feed/src/main/java/com/techfeed/feature/feed/ui/FeedContract.kt
package com.techfeed.feature.feed.ui

import com.techfeed.core.model.Article

/** 屏幕级单一快照：所有字段 val（不可变），默认值代表初始态 */
data class FeedUiState(
    val isLoading: Boolean = false,
    val isRefreshing: Boolean = false,   // 下拉刷新与首次加载是两种视觉反馈，但要同源于一个状态对象
    val articles: List<Article> = emptyList(),
    val errorMessage: String? = null,
    val keyword: String = "",
) {
    /** 派生属性：不额外占一个 Flow，避免状态不同步 */
    val showEmpty: Boolean get() = !isLoading && errorMessage == null && articles.isEmpty()
}

/** 一次性事件：绝不进 UiState，否则旋转屏幕会重复消费 */
sealed interface FeedEvent {
    data class ShowToast(val message: String) : FeedEvent
    data class NavigateToDetail(val articleId: String) : FeedEvent
    data object ScrollToTop : FeedEvent
}

/** 用户意图：UI 只上报"我做了什么"，不指挥"你怎么改状态" */
sealed interface FeedAction {
    data object Refresh : FeedAction
    data object LoadNextPage : FeedAction
    data class QueryChanged(val text: String) : FeedAction
    data class ArticleClicked(val articleId: String) : FeedAction
    data object MessageShown : FeedAction   // UI 消费完错误后回执，让 VM 清除状态
}

[!TIP] 把 Action 也建模成密封类型（而不是 fun refresh() / fun loadMore() 一堆方法），好处是：所有用户行为集中一处，when 穷尽检查，埋点与日志可以统一挂在一个入口上。

2.2 ViewModel：唯一的 state 写入者

[!NOTE] 演进说明：本章沿用第 11/12 章的构造签名（注入 GetFeedUseCase + RefreshFeedUseCase）；第 24 章起工程实际为 FeedViewModel(repository: FeedRepository)——UseCase 层数减少、VM 直接依赖 Repository 接口，且用 query.flatMapLatest 订阅 DB 级过滤流。签名变化的动机与完整代码见第 24 章。

// sample/feature/feed/src/main/java/com/techfeed/feature/feed/ui/FeedViewModel.kt
package com.techfeed.feature.feed.ui

import androidx.lifecycle.ViewModel
import androidx.lifecycle.viewModelScope
import com.techfeed.core.model.AppError
import com.techfeed.feature.feed.domain.GetFeedUseCase
import com.techfeed.feature.feed.domain.RefreshFeedUseCase
import dagger.hilt.android.lifecycle.HiltViewModel
import kotlinx.coroutines.Job
import kotlinx.coroutines.flow.MutableSharedFlow
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.SharedFlow
import kotlinx.coroutines.flow.StateFlow
import kotlinx.coroutines.flow.asSharedFlow
import kotlinx.coroutines.flow.asStateFlow
import kotlinx.coroutines.flow.catch
import kotlinx.coroutines.flow.launchIn
import kotlinx.coroutines.flow.onEach
import kotlinx.coroutines.flow.update
import kotlinx.coroutines.launch
import javax.inject.Inject

@HiltViewModel
class FeedViewModel @Inject constructor(
    private val getFeed: GetFeedUseCase,
    private val refreshFeed: RefreshFeedUseCase,
) : ViewModel() {

    private val _uiState = MutableStateFlow(FeedUiState(isLoading = true))
    val uiState: StateFlow<FeedUiState> = _uiState.asStateFlow()   // 对外只读，封住写权限

    private val _events = MutableSharedFlow<FeedEvent>()           // 默认 replay=0：不重放历史事件
    val events: SharedFlow<FeedEvent> = _events.asSharedFlow()

    private var observeJob: Job? = null

    init {
        // 单一数据源：订阅本地数据库 Flow，而不是一次性的网络结果
        observeJob = getFeed()
            .onEach { articles -> _uiState.update { it.copy(isLoading = false, articles = articles) } }
            .catch { e -> _uiState.update { it.copy(isLoading = false, errorMessage = e.message) } }
            .launchIn(viewModelScope)
    }

    /** UI 只调用这一个方法，所有分支都在 when 里，便于统一埋点 */
    fun onAction(action: FeedAction) {
        when (action) {
            FeedAction.Refresh -> refresh()
            FeedAction.LoadNextPage -> loadNextPage()
            is FeedAction.QueryChanged -> _uiState.update { it.copy(keyword = action.text) }
            is FeedAction.ArticleClicked ->
                // viewModelScope 自动随 ViewModel 销毁取消，无需担心泄漏
                viewModelScope.launch { _events.emit(FeedEvent.NavigateToDetail(action.articleId)) }
            FeedAction.MessageShown -> _uiState.update { it.copy(errorMessage = null) }
        }
    }

    private fun refresh() {
        viewModelScope.launch {
            _uiState.update { it.copy(isRefreshing = true, errorMessage = null) }
            runCatching { refreshFeed() }
                .onFailure { error ->
                    _uiState.update {
                        it.copy(isRefreshing = false, errorMessage = error.toMessage())
                    }
                }
                .onSuccess {
                    _uiState.update { it.copy(isRefreshing = false) }
                    _events.emit(FeedEvent.ScrollToTop)
                }
        }
    }

    private fun loadNextPage() { /* 第 24 章分页展开 */ }

    /** 错误到文案的映射放在 UI 层：Domain 层不认识中文文案 */
    private fun Throwable.toMessage(): String = when (this) {
        is AppError.Network -> "网络不可用，请检查连接"
        is AppError.Auth -> "登录已失效，请重新登录"
        else -> "加载失败，请稍后重试"
    }
}

关键点：asStateFlow() 对外暴露只读类型；update {} 保证原子更新；所有 String 文案留在 UI 层（Domain 层不应出现用户可见语言，除非你在做多语言抽象）。

2.3 UseCase：命名一个业务意图

// sample/feature/feed/src/main/java/com/techfeed/feature/feed/domain/GetFeedUseCase.kt
package com.techfeed.feature.feed.domain

import com.techfeed.core.model.Article
import kotlinx.coroutines.flow.Flow
import javax.inject.Inject

/**
 * 观察信息流。
 * 注意：这里返回 Flow 而非 suspend List —— 因为本地数据库是单一数据源，数据会持续变化。
 * 这一层不 import 任何 android.* / Retrofit / Room，纯 Kotlin 可直接跑 JUnit。
 */
class GetFeedUseCase @Inject constructor(
    private val repository: FeedRepository,
) {
    operator fun invoke(keyword: String = ""): Flow<List<Article>> =
        repository.observeFeed(keyword)
}

// sample/feature/feed/src/main/java/com/techfeed/feature/feed/domain/RefreshFeedUseCase.kt
package com.techfeed.feature.feed.domain

import javax.inject.Inject

/** 拉取远端并落库。suspend 语义：一次性的动作，不返回持续流 */
class RefreshFeedUseCase @Inject constructor(
    private val repository: FeedRepository,
) {
    suspend operator fun invoke() = repository.refresh()
}

// sample/feature/feed/src/main/java/com/techfeed/feature/feed/domain/FeedRepository.kt
package com.techfeed.feature.feed.domain

import com.techfeed.core.model.Article
import kotlinx.coroutines.flow.Flow

/** 接口定义在 Domain 层（依赖倒置）：Data 层来实现它，UI 层只认它 */
interface FeedRepository {
    fun observeFeed(keyword: String): Flow<List<Article>>
    suspend fun refresh()
}

2.4 Data 层：Repository 实现 + 三层模型映射

// sample/feature/feed/src/main/java/com/techfeed/feature/feed/data/ArticleDto.kt
package com.techfeed.feature.feed.data

import kotlinx.serialization.SerialName
import kotlinx.serialization.Serializable

/** DTO：严格镜像后端 JSON，字段名可以不遵循 Kotlin 规范，用 @SerialName 对齐 */
@Serializable
data class ArticleDto(
    val id: String,
    val title: String,
    val summary: String? = null,
    @SerialName("cover_image") val coverImage: String? = null,
    @SerialName("publish_time") val publishTime: Long,   // 后端给毫秒时间戳
    val author: AuthorDto,
)

@Serializable
data class AuthorDto(val id: String, val name: String, @SerialName("avatar") val avatar: String? = null)

// sample/feature/feed/src/main/java/com/techfeed/feature/feed/data/FeedRepositoryImpl.kt
package com.techfeed.feature.feed.data

import com.techfeed.core.model.Article
import com.techfeed.feature.feed.domain.FeedRepository
import kotlinx.coroutines.flow.Flow
import kotlinx.coroutines.flow.map
import javax.inject.Inject

class FeedRepositoryImpl @Inject constructor(
    private val remote: FeedRemoteDataSource,
    private val local: FeedLocalDataSource,
) : FeedRepository {

    // 单一数据源：UI 订阅的永远是数据库，网络只负责往库里写
    override fun observeFeed(keyword: String): Flow<List<Article>> =
        local.observeArticles(keyword)
            .map { entities -> entities.map { it.toDomain() } }   // Entity → 领域模型

    override suspend fun refresh() {
        val dtos = remote.fetchFeed()          // 网络 → DTO
        local.replaceAll(dtos.map { it.toEntity() })   // DTO → Entity → 落库
    }
}

// sample/feature/feed/src/main/java/com/techfeed/feature/feed/data/ArticleMappers.kt
package com.techfeed.feature.feed.data

import com.techfeed.core.model.Article
import com.techfeed.core.model.Author

/**
 * 三层模型的转换集中在 Mapper。
 * 好处：后端改字段名、数据库改列名，改动范围都被限制在这一个文件里。
 */
fun ArticleDto.toDomain(): Article = Article(
    id = id,
    title = title,
    summary = summary.orEmpty(),
    coverUrl = coverImage,
    author = author.toDomain(),
    publishedAt = publishTime,   // 单位统一在这里收敛，UI 不再关心毫秒还是秒
)

fun AuthorDto.toDomain(): Author = Author(id = id, name = name, avatarUrl = avatar)

2.5 UI 之一：Compose 渲染 UiState

// sample/feature/feed/src/main/java/com/techfeed/feature/feed/ui/FeedScreen.kt
package com.techfeed.feature.feed.ui

import androidx.compose.foundation.clickable
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.lazy.LazyColumn
import androidx.compose.foundation.lazy.items
import androidx.compose.material3.CircularProgressIndicator
import androidx.compose.material3.ExperimentalMaterial3Api
import androidx.compose.material3.ListItem
import androidx.compose.material3.Text
import androidx.compose.material3.pulltorefresh.PullToRefreshBox
import androidx.compose.runtime.Composable
import androidx.compose.runtime.LaunchedEffect
import androidx.compose.runtime.getValue
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.hilt.navigation.compose.hiltViewModel
import androidx.lifecycle.compose.collectAsStateWithLifecycle

@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun FeedScreen(
    onNavigateToDetail: (String) -> Unit,
    modifier: Modifier = Modifier,
    viewModel: FeedViewModel = hiltViewModel(),   // Hilt 提供 VM（第 12 章）
) {
    // collectAsStateWithLifecycle：只在 STARTED 之后收集，后台自动停，省资源
    val uiState by viewModel.uiState.collectAsStateWithLifecycle()

    // 一次性事件：LaunchedEffect(Unit) 保证只注册一次消费者
    LaunchedEffect(Unit) {
        viewModel.events.collect { event ->
            when (event) {
                is FeedEvent.NavigateToDetail -> onNavigateToDetail(event.articleId)
                is FeedEvent.ShowToast -> { /* Snackbar 宿主显示 */ }
                FeedEvent.ScrollToTop -> { /* listState.animateScrollToItem(0) */ }
            }
        }
    }

    FeedContent(
        uiState = uiState,                       // 状态向下
        onAction = viewModel::onAction,          // 事件向上
        modifier = modifier,
    )
}

/** 无状态（Stateless）内容组件：只依赖入参，天然可在 @Preview / 截图测试中复用 */
@OptIn(ExperimentalMaterial3Api::class)
@Composable
private fun FeedContent(
    uiState: FeedUiState,
    onAction: (FeedAction) -> Unit,
    modifier: Modifier = Modifier,
) {
    PullToRefreshBox(
        isRefreshing = uiState.isRefreshing,
        onRefresh = { onAction(FeedAction.Refresh) },
        modifier = modifier.fillMaxSize(),
    ) {
        when {
            uiState.isLoading -> Box(Modifier.fillMaxSize(), contentAlignment = Alignment.Center) {
                CircularProgressIndicator()
            }
            uiState.errorMessage != null -> Box(Modifier.fillMaxSize(), contentAlignment = Alignment.Center) {
                Text(uiState.errorMessage)
            }
            uiState.showEmpty -> Box(Modifier.fillMaxSize(), contentAlignment = Alignment.Center) {
                Text("还没有内容，下拉试试")
            }
            else -> LazyColumn(Modifier.fillMaxSize()) {
                items(items = uiState.articles, key = { it.id }) { article ->   // key 保证重组复用正确
                    ListItem(
                        headlineContent = { Text(article.title) },
                        supportingContent = { Text(article.author.name) },
                        modifier = Modifier.clickable { onAction(FeedAction.ArticleClicked(article.id)) },
                    )
                }
            }
        }
    }
}

[!NOTE] 拆出 FeedContent 这种无状态组件是 MVI 在 Compose 下的关键收益：FeedScreen 负责"接 ViewModel"，FeedContent 只吃参数。Preview、截图测试（第 21 章）、换另一套 ViewModel 都不用改它。

2.6 UI 之二：View / XML 渲染同一份 UiState

同一个 ViewModel，在 View 体系里渲染，只需把 StateFlow 收集起来刷新控件：

// sample/feature/feed/src/main/java/com/techfeed/feature/feed/ui/FeedFragment.kt
package com.techfeed.feature.feed.ui

import android.os.Bundle
import android.view.View
import androidx.core.view.isVisible
import androidx.fragment.app.Fragment
import androidx.fragment.app.viewModels
import androidx.lifecycle.Lifecycle
import androidx.lifecycle.lifecycleScope
import androidx.lifecycle.repeatOnLifecycle
import androidx.recyclerview.widget.LinearLayoutManager
import com.techfeed.feature.feed.databinding.FragmentFeedBinding
import dagger.hilt.android.AndroidEntryPoint
import kotlinx.coroutines.launch

@AndroidEntryPoint
class FeedFragment : Fragment(R.layout.fragment_feed) {

    private val viewModel: FeedViewModel by viewModels()
    private var _binding: FragmentFeedBinding? = null
    private val binding get() = _binding!!
    private val adapter = FeedAdapter { article -> viewModel.onAction(FeedAction.ArticleClicked(article.id)) }

    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        _binding = FragmentFeedBinding.bind(view)   // ViewBinding：避免 Kotlin synthetics 的 id 冲突
        binding.recyclerView.layoutManager = LinearLayoutManager(requireContext())
        binding.recyclerView.adapter = adapter
        binding.swipeRefresh.setOnRefreshListener { viewModel.onAction(FeedAction.Refresh) }

        observeUiState()
        observeEvents()
    }

    private fun observeUiState() {
        viewLifecycleOwner.lifecycleScope.launch {
            // repeatOnLifecycle(STARTED)：页面不可见时停止收集，避免后台刷新 UI
            repeatOnLifecycle(Lifecycle.State.STARTED) {
                viewModel.uiState.collect { state -> render(state) }
            }
        }
    }

    /** 纯函数式渲染：给定 state，产出画面；与 Compose 的 FeedContent 逻辑一一对应 */
    private fun render(state: FeedUiState) = with(binding) {
        progressBar.isVisible = state.isLoading
        swipeRefresh.isRefreshing = state.isRefreshing
        emptyView.isVisible = state.showEmpty
        errorView.isVisible = state.errorMessage != null
        errorView.text = state.errorMessage.orEmpty()
        // submitList 内部做差分：传新 List 实例才会触发 DiffUtil
        adapter.submitList(state.articles)
    }

    private fun observeEvents() {
        viewLifecycleOwner.lifecycleScope.launch {
            repeatOnLifecycle(Lifecycle.State.STARTED) {
                viewModel.events.collect { event ->
                    when (event) {
                        is FeedEvent.NavigateToDetail -> parentFragmentManager.navigateToDetail(event.articleId)
                        is FeedEvent.ShowToast -> toast(event.message)
                        FeedEvent.ScrollToTop -> binding.recyclerView.smoothScrollToPosition(0)
                    }
                }
            }
        }
    }

    // Fragment 的 View 被销毁但实例还在，必须切断 binding 引用（第 03 章）
    override fun onDestroyView() {
        binding.recyclerView.adapter = null
        _binding = null
        super.onDestroyView()
    }
}

[!TIP] 双 UI 体系共用一套 ViewModel 是可行的，前提是 ViewModel 不 import android.view.*（本节的写法满足）。这也是第 16 章渐进式迁移能成立的基础：先迁 UI，ViewModel 与下层一行不动。

2.7 Hilt 装配接口与实现

// sample/feature/feed/src/main/java/com/techfeed/feature/feed/di/FeedDataModule.kt
package com.techfeed.feature.feed.di

import com.techfeed.feature.feed.data.FeedRepositoryImpl
import com.techfeed.feature.feed.domain.FeedRepository
import dagger.Binds
import dagger.Module
import dagger.hilt.InstallIn
import dagger.hilt.components.SingletonComponent
import javax.inject.Singleton

@Module
@InstallIn(SingletonComponent::class)
abstract class FeedDataModule {
    // @Binds 把实现类绑定到接口：UI 层永远拿的是 Domain 层的抽象
    @Binds
    @Singleton
    abstract fun bindFeedRepository(impl: FeedRepositoryImpl): FeedRepository
}